GEMKIT
by Gordon Billingsley
GEMKIT is a set of ST, BASIC subroutines that gives you easy access to the power of the ST Graphics Environment Manager. GEMKIT uses simple, one-word GOSUB calls to manipulate graphics and text, create dialog boxes, use the mouse and perform many other functions with the lightning fast speed we all expected of the ST. All of the features work in any screen resolution.
Since GEMKIT is intended for use in all resolutions, some GEM features that work only for color monitors are not included. Also, because ST BASIC is, itself, a GEM application many GEM features that duplicate BASIC statements and functions are not included. Often BASIC statements already are making direct GEM system calls.
In other ways, GEMKIT expands on what GEM has to offer. For example:
- GEMKIT uses an algorithm not available in GEM to automatically center lines of text in any of four type sizes ranging up to twice normal size;
- GEMKIT contains an algorithm to automatically assign individual characters in a text string to an array allowing pixel-accurate placement of the whole string. (Without the algorithm you'd have have to put the text string on the screen essentially one letter at a time.)
Listing 1 contains not only GEMKIT itself (Lines 60000 on), but also a short program that demonstrates its features. To use GEMKIT in your own programs, delete Lines 10-410 (the demo program) in Listing 1.
Reading the mouse
GOSUB READMOUSE tells you where the mouse pointer is located and whether one of the mouse buttons has been pressed. The x- and y-coordinates (mx, my) are returned as pixel locations on the screen.
Mouse button presses may be detected in a variable called button, with values as follows: 0 = no button pressed; 1 = left button pressed; 2 = right button pressed.
Here's a program example that calls the subroutine to read the mouse status and then checks for the x-coordinate location of the pointer and the status of the right button:
10 GOSUB READMOUSE 20 if mx> 150 and button = 2 then 40 30 goto 10 40 REM program continues here
Pointer shapes
Each of the following routines automatically changes the form of the mouse pointer to the shape the name of the subroutine implies:
GOSUB ARROW: the default pointer
GOSUB BEAM: an I-beam shape useful in word processing
GOSUB BEE: the famous busy bumblebee
GOSUB FINGER: a hand with a pointing finger
GOSUB HAND: the back of a hand or grabbing hand
GOSUB CROSSHAIR: a thin-line version of the crosshair
GOSUB FATHAIR: a thickened version of the crosshair
GOSUB HOLLOWHAIR: an outline version of the crosshair
Pointer visibility
GOSUB HIDE allows you to make the pointer invisible at any time you want to ensure it does not appear on the screen. GOSUB SHOW allows you to ensure that the pointer is visible at all times it is needed.
Text manipulation
Each of the following routines automatically changes the typeface as it appears on the screen to the form implied in the subroutine name. A change in type style remains in effect until explicitly changed again.
GOSUB NORMAL: system default typeface
GOSUB BOLD: a thickened version of the default face
GOSUB HATCH: a hatched look, sometimes called ghost letters
GOSUB ITALICS: a skewed face
GOSUB UNDERLINE: underlines the system default face
GOSUB OUTLINE: a hollow typeface
Calling a type-style subroutine does not affect type styles of characters already on the screen.
Adventurous programmers may use GOSUB NEWFACE to create faces that are combinations of the six standard faces. For instance, it is possible for a typeface to be both bold and italic at the same time. To do this you assign an appropriate value to a variable called font, then call GOSUB NEWFACE.
Each type style has a unique number value as below:
| Normal = 0 | Bold = 1 |
| Hatch = 2 | Italics = 4 |
| Underline = 8 | Outline = 16 |
To create a combined style, add the values for the styles you wish to have combined. Bold/italics would equal 5, for instance. This is the same method used to combine type styles in ST-Writer.
As an example, the command sequence to set the type style to bold/italic/underlined would be:
10 font = 13 : GOSUB NEWFACE
Four type sizes are available in GEMKIT for the creation of showy title and menu screens: small, regular, large and extra large. A line of any size type may be placed on the screen with pixel accuracy by using the mnemonic GOSUB routines.
GOSUB STYPE: small type, ½ system-default type size
GOSUB RTYPE: regular type, system-default type size
GOSUB LTYPE: large type, 1.5 times system-default type size
GOSIB XLTYPE: extra large type, two times system-default size
Each of these subroutines must be preceded by program lines to indicate the desired text string and to set xy pixel coordinates for placing the first letter of the text. The text string is set in a variable called text$. The pixel locations are set with variables called tx and ty. For instance:
10 text$ = "Hello World!" 20 tx = 50 : REM x-coordinate 30 ty = 150 : REM y-coordinate 40 GOSUB XLTYPE
When using any of the type-size subroutines, each single line of text must have its own pixel-precise coordinates and separate GOSUB call. You cannot use combinations of GOTOXY and PRINT to place nonstandard character sizes on the screen because PRINT does not space nonstandard letter sizes correctly. As much as half of each of the letters may disappear because of overlapping when PRINT is used.
Of course, the standard or default type style, may be placed on the screen using PRINT statements, but it is not necessary in that instance to use GOSUB RTYPE. GOSUB RTYPE should be used only when you want pixel-accurate placement of the standard type size.
Text and graphics in ST BASIC are normally limited to the output window. With GEMKIT placement routines, however, the entire screen is available. You could, for instance, place scoring information in the upper right corner of the screen, outside the playing window of a game.
BASIC views position 0,0 as being the upper left corner of the output window. GEM views position 0,0 as the upper left corner of the screen. You should be careful about obliterating menu bar items and such unless you really want to.
A line of any size of text may be automatically centered in the BASIC output window. Simply assign the desired y-coordinate pixel position (vertical position) to the variable called ty, set the text string in the variable called text$ and call the appropriate centering subroutine.
A subroutine is available for each of the four type sizes and each has been given a mnemonic name. You do not have to set the type size first. The centering routine automatically sets the type size and centers the line of text. It also adjusts the point at which it centers for any screen resolution.
GOSUB SCENTER: centers a line of small type (half size)
GOSUB RCENTER: centers a line of regular type (default size)
GOSUB LCENTER: centers a line of large type (1.5X)
GOSUB XLCENTER: centers a line of extra large type (2X)
Here is an example of the appropriate sequence:
10 text$ = "GEMKIT SAVES WORK" 20 TY = 250 30 GOSUB LCENTER
GEMKIT text centering routines center text in the output window. This is not the true center of the screen. If you desire screen-centered text you should change the values assigned to the variable called rez, which can be found in the TYPESIZE subroutine. Appropriate values would be 320 rather than 300, and 160 rather than 150. The type size is automatically returned to the default after each text line.
Writing mode determines the conditions under which text and graphics are printed to the screen. You may control, for instance, whether letters appearing on a patterned fill completely block out the pattern in and around the letters or whether the space around the letters is transparent and permits the fill to show through.
The routines are:
GOSUB BLANKOUT: replace mode, covers previous objects
GOSUB TRANSPARENT: see-through mode
GOSUB EXCLUSIVE: XOR mode, cancels out where pixels conflict
GOSUB REVERSE: white on black (transparent only)
BLANKOUT and EXCLUSIVE are not called with their typical system names of replace and xor, because those are reserved words in ST BASIC. Writing mode will remain in the selected mode until explicitly changed to a new mode or back to the default mode.
Graphics
Three types of graphic elements that GEM refers to as bars may be called through GEMKIT. Essentially the bars are boxes of any size and shape in any screen location.
To use the routines you must set x- and y-pixel coordinates for two corners of the box using variables called barx1 and bary1 for the first corner and barx2, bary2 for the second corner. Then use GOSUB to call for the type of box you desire. If you want a specific fill pattern in the box use the COLOR statement in ST BASIC before you call the bar shape with the GEMKIT. The ST BASIC Sourcebook contains a chart of the various fills available.
GOSUB BAR: a filled box with square corners
GOSUB ROUNDBAR: a filled box with round corners
GOSUB HOLLOWBAR: unfilled box with round corners; ignores fill pattern set in COLOR statement
Example:
10 REM round cornered box with "Easter egg" pattern 20 COLOR 1,1,1,17,2 30 barx1 = 50 : bary1 = 50 : barx2 = 300 : bary2 = 90 40 GOSUB ROUNDBAR
Polymarkers are predefined graphic shapes that can be manipulated by selecting screen locations, writing mode, colors and so on. GEMKIT has established four pro forma sizes for the polymarkers. Each of the sizes corresponds to one of the four available type sizes. There are six types of markers.
GOSUB DOT: a one-pixel dot (size does not change)
GOSUB PLUS: makes a +
GOSUB ASTERISK: makes an *
GOSUB SQUARE: makes a square
GOSUB CROSSBUCK: makes a diagonal cross
GOSUB DIAMOND: makes diamond (horizontal orientation)
After calling one of the polymarker shapes, you must request a marker size. Pro forma sizes are as follows:
GOSUB SMARK: makes marker one-half default type size
GOSUB RMARK: makes marker default type size
GOSUB LMARK: makes marker 1.5X default type size
GOSUB XLMARK: makes marker 2X default type size
You also must set x- and y-pixel coordinates for the location of the polymarker. The variables are "markx," "marky."
Example:
10 REM a double-sized diamond-shaped polymarker 20 REM note that the shape is called before the size 30markx = 40:marky = 120: GOSUB DIAMOND: GOSUB XLMARK
Polyline features allow you to determine what lines drawn with BASIC programs will look like. The two features available in GEMKIT are the width of the line and the types of ends on the line.
GOSUB ENDSTYLE: sets one of three patterns for either or both ends of a line
GOSUB LINEWIDTH: sets width of line in pixels
To use GOSUB ENDSTYLE you must assign values to two variables (one for each end of the line) called leftend, rightend. For each variable: 0 = square end (default); 1 = arrow; 2 = rounded.
Example:
10 leftend = 2:rightend = 1: GOSUB ENDSTYLE 20 REM sets linestyles so that the left end of a line will be round and the right end will be an arrow.
To use GOSUB LINEWIDTH you must assign an appropriate value to a variable called linew. The values are integers indicating the number of pixels wide you want the line to be. Only odd numbers (such as 1,3,5,7 should be used).
Example:
10 linew = 5: GOSUB LINEWIDTH 20 REM sets lines to 5 pixels wide
There are two pro-forma dialog boxes available in GEMKIT. Each may be called with a one-word subroutine name.
GOSUB FINISHED: ? in corner, message = "Finished?" yes/no buttons that may be clicked with the mouse, return key works with "no"
GOSUB CONTINUE: ! in corner, message = "Click box or press RETURN", one response box = "CONTINUE"
You also may design your own dialog boxes with GEMKIT. A variable called box$ is used to tell GEMKIT what graphic feature you want in the dialog box corner, what message you want in the box and the number and messages in the response boxes to be clicked with mouse.
To indicate which button will respond to a press of the return key, assign an appropriate value to a variable called return-box. You can have up to three buttons in a dialog box and they are numbered left to right. To call a dialog box use GOSUB DIABOX.
Here's the syntax to create your own dialog box:
10 BOX$ = "[2][Will you|continue with your lesson?][YES|NO]" 20 returnbox = 2: GOSUB DIABOX
In Line 10, you will note the dialog box is described in three parts set off in brackets. The number 2 in the first set of brackets tells GEMKIT to put a ? in the upper left corner. The three available graphics are 1 =!; 2 = ?; 3 = stop sign.
The second set of brackets contains the main message in the box. Note the use of the OR symbol (Shift + Backslash). It is used to separate lines of text in the box. You may have up to five lines, and the box grows to accommodate longer lines.
The third bracket set contains the text to be included in the buttons. They also are separated by the Shift + Backslash symbol. Three is the maximum. GEMKIT knows how many buttons to make by checking for the number of OR symbols. Button text should be kept short, under 20 characters total.
Notice there are no spaces between the brackets. GEMKIT likes it that way and can return some strange looking dialog boxes if you aren't careful about that.
Once the box is created it will be asking you to make a choice from among the buttons. The variable that detects which button was clicked with the mouse (or return key) is called inbox. It reads the buttons and numbers them from left to right.
Using the example above:
10 BOX$ = [2][Will you/continue with|your lesson?] [YES|NO] 20 returnbox = 2 : GOSUB DIABOX 30 if inbox = 2 then goto 50 40 REM "yes" would fall through to this line 50 REM "no" jumps to this line
Housekeeping features
The title in the middle of the upper bar of the output window may be changed to, for instance, the name of your program. Assign the text you want to appear there in a variable called title$. The call GOSUB NEWTITLE.
Example:
10 title$ = "GEMKIT" : GOSUB NEWTITLE
Instead of a STOP or END statement to terminate program execution, use the call GOSUB GET.OUT. This isn't required, it's just a tidier way of leaving because it changes the name of the output window back to output.
Improvements
Aside from simply including more routines, GEMKIT could be enhanced by creating more algorithms and user routines that make using the GEM features of GEMKIT easier. Programming techniques—such as the one demonstrated in the sampler for making menu selections with the mouse—could make program development much faster.