Text Windowing

The Z88 provides a large number of facilities for creating text windows, applying effects (eg bold and underlining) to text and displaying special characters. All of these facilities can be accessed by sending certain sequences of characters to the standard output device; however, CamelForth provides slightly easier access to them.

Creating Windows

When you start CamelForth or use the CINIT word, the screen is divided into a single large text window. You can, however, use a number of text windows within your program. Each window is identified by a window id, which must be between 1 and 6.

OPENWINDOW ( x y w h id -- )
This creates a standard window with top left corner at (x,y), with a width w and height h. This is defined as window number id, then selected for current output and cleared.
OPENTITLED ( x y w h c-addr id -- )
Similarly, this creates a window, but with a title defined by the null-terminated string at c-addr. The height specified is reduced by one to make room for the title.
OPENPOPUP ( x y w h c-addr id -- )
Finally, this word produces a titled window with a bottom border, in the style made popular by Interlogic. The height specified is reduced by two to make room for the title and bottom border.
WINDOW ( id -- )
This word redirects all further output to the window specified.
WINDOW? ( -- w h id )
Returns the width, height and ID of the currently selected window.

As an example, let's resize the standard window and give it a title. As titles must be null-terminated strings, this must be done from a definition:

    : NEWWIN  1 0 45 8  0" CamelForth" 1 OPENTITLED ;
    NEWWIN

Note that we have specified the top-left corner as (1,0); this is important, as using (0,0) would cause the left-hand bar to encroach on the menu window at the left of the display.

Also note that none of the words above use the standard output words EMIT or TYPE; however the words in the following sections all do.

Text effects

A variety of text effects are available, and these are specified by a single character code, as follows:

When a window is created in CamelForth, cursor and vertical scrolling are automatically turned on.

To set, clear and toggle the settings of these features for the current window, use the following words:

ESET ( char -- )
Turns the specified effect on
ECLR ( char -- )
Turns the specified effect off
ETOG ( char -- )
Toggles the specified effect
EAPPLY ( n -- )
Applies all current effects to the next n characters in the window, retaining the current text.
EAPPLYX ( n -- )
As for the previous word, but exclusive-ORs current effects with the effects currently applied to the next n characters.

For example, to turn bold text on, use the following phrase:

    CHAR B ESET

Other effects

A few other effects are also available:

GREY ( -- )
Makes the current window go grey (giving an "unselected window" effect)
UNGREY ( -- )
Reverses the effects of the last GREY
SCRUP ( -- )
Scrolls the current window up one line.
SCRDOWN ( -- )
Scrolls the current window down one line.
EALIGN ( char -- )
Aligns the next line of text output according to the character given. This should be used with care, and never with ACCEPT, or very strange effects can occur.

User-defined graphics

The Z88 allows you to define up to 64 user-defined graphic characters (unexpanded machines can only use 16 without encroaching on the memory used by map displays). These characters are given codes in the range 64 (@) to 127 (DEL) and are accessed in the following way:

First of all, a Forth word holding the UDG definition must be defined. This is done simply with CREATE, and compiling the 8 rows of the UDG data immediately afterwards. Each row has 6 pixels, with bit 5 being the leftmost and bit 0 being rightmost.

DEFUDG ( udgaddr char -- )
Use this word to actually define a previously setup UDG definition to the character specified. This should always be done after any RC_DRAW error has been received, as UDGs are global and may be overwritten by other applications during pre-emption.
UDG ( char -- )
Output the specified UDG character to the current window.

Here's a complete example to set up a UDG definition, define a UDG character and display it. We'll use binary for the definition as it's much easier to see that way:

    2 BASE !
    CREATE smiley 
      000000 C,
      010010 C,
      001100 C,
      001100 C,
      000000 C,
      010010 C,
      001100 C,
      000000 C,
    DECIMAL

    smiley CHAR @  DEFUDG

    CHAR @ UDG

Special characters

There are also several builtin special characters which can be output, using the following words:

XCHAR ( char -- )
Outputs a special character according to the character given (hex-codes are listed with characters in brackets):
XLINE ( char -- )
Draws a single character as an arrow or line, or combination of lines. The character you should specify is hex 41 to 4F, where each bit 0 to 3 represents a direction: If only one bit is set, a pointer arrow is drawn. If two bits are set, a corner is drawn; if three bits are set a "T"-junction is drawn; and if all four bits are set a cross is drawn.

More about CamelForth

Back to the Z88 home page