MODified Shapes For Atari ST
Robert G. Geiger
This fresh adaptation of a popular COMPUTE! program creates pleasing graphics and also contains valuable information about using GEMSYS and VDISYS in ST BASIC. With the techniques explained here, you can draw on a full-screen graphics area (without BASIC'S usual window borders), manipulate dialog boxes, and monitor mouse events.Paul Carlson's article "MODified Shapes For IBM" (COMPUTE!, May 1986) is interesting both as a tutorial on the MOD operator and for its outstanding graphics. Since ST BASIC also has the MOD operator, the logic used in the IBM program works equally well on the Atari ST. But the ST is capable of doing much more. With the aid of GEMSYS and VDISYS, you can not only replicate the original program, but also add distinctive ST features such as dialog boxes and mouse input.
Type in "MODified Shapes For ST" below and save a copy before you run it. When typing the program, you'll notice that several lines (those containing VDISYS or GEMSYS calls) are more than 80 characters long. This is done so that all the information for each GEM call is on one program line. The ST BASIC editor allows you to enter lines up to 255 characters in length, provided that the first character in the second screen line is a space.
If you have a 520ST with 512K RAM and the TOS operating system on disk instead of in ROM (Read Only Memory), you must turn off buffered graphics before you run the program. If your ST has more than 512K of memory or TOS in ROM, you should have enough memory to run the program without taking this step.
The program runs in any screen resolution—low or medium resolution on a color monitor, or high resolution on a monochrome monitor. However, low resolution is truest to the four-color IBM screen used in the original program. In medium or high resolution, the design occupies only part of the screen.
From PC To ST
If you have any familiarity with IBM BASIC, you may find it instructive to compare the original program with the ST version. Some statements in the PC/PCjr program, such as KEY OFF, are unnecessary in ST BASIC and can be omitted. Most of the program logic, which simply manipulates variables, works on the ST with no modification at all.
However, other operations require different commands. For instance, at the conclusion of the IBM program, the INKEY$ statement is used to make the program pause until you press a key. ST BASIC lacks INKEY$, but you can substitute the INP(2) function. And though the LINEF command in ST BASIC differs a bit in syntax, it can draw lines much like the IBM version. The IBM clears the screen with CLS, but the ST uses CLEARW 2, and so on.
It's possible to translate most of the IBM program by making BASIC substitutions, but if you confine yourself to ordinary BASIC commands, you'll end up with a translation that's almost, but not quite, satisfactory. One major problem involves the ST BASIC output window. When you open the window to full screen size with FULLW 2:CLEARW 2, part of the visible screen area is taken up by the window border, title line, and menu bar. In low resolution, the usable screen area is less than 40 characters wide, and you can print only 17 lines of text before the window's contents begin to scroll upward.
Because screen space is taken up by the window borders, it appears impossible to duplicate the IBM's 320 X 200 pixel screen exactly. Even worse, while IBM BASIC defines the upper-left corner of the screen as coordinate (0,0), ST BASIC considers coordinate (0,0) to be the upper-left point inside the output window. As a result, any graphics designed to occupy the entire IBM screen will be clipped in the ST BASIC output window.
Full Screens In ST BASIC
The solution is to use system calls for screen output. GEM (Graphics Environment Manager) allows you to draw anywhere on the screen, including the areas normally occupied by the BASIC windows themselves. Two of the more important parts of GEM are the VDI (Virtual Device Interface), which handles low-level mouse input and graphics display, and the AES (Applications Environment Services), which handles more complex routines such as managing windows, drop-down menus, icons, and dialog boxes.
The basic method of calling a VDI routine is to store the information it requires into reserved memory locations which are defined by the reserved variables CONTRL, PTSIN, and INTIN. These memory locations are known as parameter blocks. Every VDI routine requires different information, and some VDI routines don't need information in all three parameter blocks. Once this preliminary work is done, you call the VDI routine with the statement VDISYS(0). The 0 is a dummy parameter and can be any numeric value. You can learn more about VDISYS routines in a two-article series entitled "Adding System Power To ST BASIC" in the April and May 1986 issues of COMPUTE!.
The procedure for calling an AES routine is similar—first you store the information it requires in memory, then you call the routine with a GEMSYS statement—but different information must be passed to the routine, and the number inside the parentheses is significant. For instance, GEMSYS(52) calls AES routine 52 (see below). This program uses VDISYS to create graphics, and GEMSYS to handle user input.
Dialog Boxes
Some of the most useful AES functions involve various forms of the dialog box—a box that appears on top of the current screen display whenever it's time for you to select an option, respond with a yes or no answer, and so forth. When the interaction is over, GEM restores the screen and lets you continue where you left off. Dialog boxes are a powerful way of creating a friendly atmosphere in your programs. The full capabilities of the dialog box are beyond the scope of BASIC (unless you have the Resource Construction Set utility from the ST Development System), but two forms of the dialog box—the alert box and the error box—are available.
When you run MODified Shapes, it begins by displaying a dialog box with three options labeled EX1, EX2, and EX3. Depending on which option you click on, the program will create example screen 1, 2, or 3. After you make a choice, the box disappears, the screen is redrawn, and the program proceeds. This dialog box is created with AES routine 52, known as FORM_ALERT, which both creates a dialog box and tells GEM to get input from it. To use FORM_ALERT, you must store two items of information in memory, then call the routine with GEMSYS(52). After the interaction is finished, FORM__ALERT passes one item of information back to you.
Most of the information needed by FORM_ALERT can be passed in the form of a BASIC string. First the string is defined, then you POKE the address of the beginning of the string in a reserved variable area known as ADDRIN (ADDress IN). This tells GEM where the string is located.
The FORM_ALERT string begins with a code number indicating which sort of icon you want the box to contain. You may choose a stop sign icon, an exclamation point, or a question mark. These icons appear frequently during GEM desktop operations and are familiar to every ST user. After the icon number comes the text which you want to print inside the box. If an icon is also used, the box has enough room for up to five lines of text.
Buttons In A Box
The next portion of the string contains the text you want to appear inside the buttons. Don't confuse this sort of button with the physical button on the ST mouse device. In this context, a button is a smaller boxed-in area within the dialog box. You point to the dialog button with the mouse, then click the left mouse button to select that option.
Up to three dialog buttons may be included in a single dialog box. If you include only one button, its box may contain up to 20 characters of text. It is also possible to outline one of the buttons with a heavier line to indicate that it can be selected by pressing RETURN as well as clicking with the mouse.
Line 70 of the program creates a typical FORM_ALERT string. Notice that each component of the string is enclosed in a set of square brackets in the sequence [icon code] [message text] [button text]. Notice that new lines within the message text and button text are separated by the logical OR character (|). This character is obtained by pressing the backslash key (\) while holding down SHIFT.
After creating a string and POKEing its location into memory, you must POKE a value into the location defined as GINTIN to indicate which button is to be chosen by pressing RETURN. POKE a zero into this location to indicate that RETURN should be ignored. POKE GINTIN with a 1, 2, or 3 to indicate the first, second, or third button, respectively.
When the FORM_ALERT dialog is over, you need some way to learn what choice was made. This output is returned in the location defined as GINTOUT, which you can PEEK from BASIC. When GINTOUT equals 1, the first dialog button was clicked. Values of 2 and 3 indicate that the second and third dialog buttons were clicked, Again, keep in mind that these are buttons within the dialog box on the screen, not physical buttons on the mouse.
Reading Mouse Events
MODified Shapes uses another AES routine—number 21, known as MOUSE_EVENT—to pause until you press both mouse buttons. The MOUSE—EVENT routine requires three inputs which are passed in locations beginning at GINTIN. The first value to be passed indicates the number of clicks to be detected, the second value indicates the mouse button to be read, and the third indicates the button condition you wish to look for. The number of clicks should be either 1 or 2. For the second value, use the value 1 to indicate the left button, 2 to indicate the right button, and 3 to indicate both buttons. The third value determines which condition— being pressed or not pressed—the routine checks for. In most cases this value will be 1, indicating that you want to know when the indicated button is pressed. If you supply a 0, the routine tells you whether the button is not pressed.
By calling GEM and AES routines, we can not only mimic the IBM's graphics, but also add the ST's own signature to the program in the form of dialog boxes and mouse input. The accompanying table shows summaries of the various VDI and AES routines used in this program, along with the program lines in which each routine is called.
"MODified Shapes For Atari ST" demonstrates how to draw graphics on the entire screen surface, including areas normally occupied by BASIC'S window borders.
With the aid of GEMSYS, you can call system routines from BASIC to create dialog boxes like the one shown here.
Set—Color Representation
(lines 20, 30, 570, 580)
Input Parameters
POKE CONTRL, 14 opcode
POKE CONTRL +2,0 number of vertices
POKE CONTRL +6,4 number of attributes
POKE INTIN,0-15 number of pen color
POKE INTIN +2,0-1000 red intensity
POKE INTIN +4,0-1000 green intensity
POKE INTIN +6,0-1000 blue intensity
Clear—Workstation
(lines 40, 170, 310, 440)
Input Parameters
POKE CONTRL, 3 opcode
POKE CONTRL + 2,0 number of vertices
POKE CONTRL + 6,0 number of attributes
Show—Cursor
(lines 50 and 110)
Input Parameters
POKE CONTRL, 122 opcode
POKE CONTRL + 2,0 number of vertices
POKE CONTRL + 6,1 number of attributes
POKE INTIN,0 reset flag
(NOTE: The VDI normally makes note internally of how often the HIDE CURSOR call is used; to disable this function, set the reset flag to 0.)
Form—Alert
(Lines 60-80,120-140)
Input Parameters
POKE GINTIN,0 button simulated by pressing RETURN
X# = ADDRIN ADDRIN is addressed as a double-precision variable
POKE X#, VARPTR(Message$)
Output Parameters
KEY = PEEK(GINTOUT) value of the button clicked
Hide-Cursor (line 90)
Input Parameters
POKE CONTRL,123 opcode
POKE CONTRL + 2,0 number of vertices
POKE CONTRL + 6,0 number of attributes
Polyline (lines 240, 380, 510)
Input Parameters
POKE CONTRL.6 opcode
POKE CONTRL+2,2 number of vertices one line
POKE CONTRL+6, 0 number of attributes
POKE PTSIN,X1 X coordinate of first point
POKE PTSIN + 2,Y1 Y coordinate of first point
POKE PTSIN + 4,X2 X coordinate of second point
POKE PTSIN + 6,Y2 Y coordinate of second point
Evnt—Button
(lines 290, 420, 560)
Input Parameters
(POKE GINTIN,1-2 number of clicks for action
(POKE GINTIN + 2,1-3 mouse button(s) to be read
POKE GINTIN+4,1 button condition to detect