ON DISK!
Programming In BASIC
Resourceful GFA BASIC, Part Three
by John L. Hutchinson
Add flair to your GFA programs using resource files. Sample file DIALOG.ARC on your START disk.
This is our third and final installment of START's series on using a resource construction set (RCS) to create true AES dialog boxes for use with GFA BASIC. Here I'll explain how to use the AES library procedures in a GFA BASIC program; an example program and its resource file are included on your START disk.
If you've been following along in our previous discussions; you should now have a better understanding of the structure of resources (Summer 1988 issue) and how to use an RCS (Special Issue #4). Now we'll explore a GFA BASIC program to implement the resource file we created last issue.
Tho AES library Procedures
To incorporate your dialog box or any other resources in your programs, you need to use a number of AES library procedures. The following is a description of several standard AES library procedures as well as a few customized ones which are useful for the management of dialog boxes. While it is not essential for you to know how each of these procedures work, it is important to know what they do. They must be merged with your GFA BASIC program if it is to use resource-generated dialog boxes.
Rsrc_load(Filename$) This procedure must be called early in your program to load your resource file into your computer's memory.
Rsrc_gtree(Tree_number%, *Tree%) This procedure is a simpler form of Rsrc_gaddr, both of which return the memory address of the desired tree which will form your dialog box. You must supply the procedure Tree_number%, an integer variable which refers to the index number of the tree in your resource file. Remember that trees are numbered consecutively, beginning with 0, in order of their creation. The integer variable Tree% will store the memory address of your tree and will be returned by this procedure due to the addition of the asterisk ( * ).
Form_center(Tree%) If you want your dialog box centered on screen, calling this procedure sets up the proper parameters. Tree% is the tree memory address returned by the Rsrc_gtree procedure.
Find_coords(Tree%) This is a handy procedure which minimizes repetition. It's purpose is to determine the value of the global variables X%, Y%, B% and H% which comprise the outside coordinates (clipping rectangle) of your dialog box.
Form_dial(F%,X1%,Y1%,B1%, H1%,X%,Y%,B%,H%) This is an optional procedure that creates special effects. F% may be either 0, 1, 2 or 3. The values 0 and 3 reserve and redraw screen memory, functions we can more easily perform in GFA BASIC with SGET and SPUT. If F% is 1, a grow-box effect is created when the dialog box is drawn on screen. Set to 2, a shrink-box effect is created in reverse fashion. The Find_coords procedure determines the X%, Y%, B% and H% variables. You must supply the values for the beginning coordinates, X1%, Y1%, B1% and H1%.
Objc_draw(Tree%,Start%,Depth%, X%,Y%,B%,H%) This procedure actually draws your dialog box objects on the screen. Start% is the integer value of the index of the starting tree. Set this variable to 0 for dialog box operations. Depth% is the levels of subordinate objects to draw; you should normally set this variable to 8. Again, Find_coords determines X%, Y%, B% and H%.
Form_do(Tree%,Start_ obj%) This procedure passes control from your program to the AES to manage the user's interaction with the box. Start_obj% is the integer value of the object number of the first editable field in your dialog box; use 0 if your box contains no editable fields.
Gstate(Tree%,Object_number%, *State%) This procedure determines what state the user left the selectable object you give as Tree% and Object_number% after exiting your dialog box. The procedure will return State%, which will be 1 if the object was selected or 0 if the object was unselected.
Gtext(Tree%,Object_number%, *Text$) This procedure determines what text the user entered in the editable text object you specify as Tree% and Object_number%. The procedure will return the user's input in the string variable, Text$.
Sstate(Tree%,Object_number%, State%) Objects in resource trees do not automatically revert to their original state when the user exits the tree, so this procedure resets or changes the state of selectable objects. If State%=1, the object will become selected (darkened); if State%=0, the object becomes unselected. In some cases you might want the dialog box to reflect the user's previous input. If so, you don't need to call this procedure except to change the state of any exit buttons back to their original, unselected state.
Start(Tree%,Object_number%, Text$) Like Sstate, this procedure changes text or string objects in resource trees. If Text$ is longer than the text or string object was designed for, it will be truncated to fit. Due to a quirk in AES, this call must be used to initially store a null string ("") in any editable text fields that you want to be empty.
See For Yourself
The program listed in the sidebar to this article is on this issue's START disk. Note that this printed listing omits the actual AES procedures. To access the complete program, un-ARC the file DIALOG.ARC following the Disk Instructions elsewhere in this issue. This file contains DEMO.RSC, the resource file we created last issue, DIALOG.PRG, a program which uses the dialog box in that file and prints the user's input on the screen, and DIALOG.LST, an ASCII listing of that program. To load the program into GFA BASIC, run GFA and then click on Merge and select DIALOG.LST. By examining the code, you can see how easy it is to use resource-generated dialog boxes in your own GFA BASIC programs.
Final Tips, Hints And Suggestions
The Kuma K-Resource utility has a "compatibility" option that allows you to properly size resource trees for medium resolution even if all you have to work with is a monochrome monitor. Even so, it is often easier to create separate resource files for each resolution to be supported. Your program should first check the current resolution with an Xbios(4) routine and then Gosub to the appropriate Rsrc_load procedure
Some RCS utilities limit resource files to a maximum of 32K (newer versions permit 64K resource files). Careful construction of dialog boxes to minimize the number of objects they contain can help you stay clear of this limit. For example, use a single BOXTEXT object instead of a TEXT object within a separate BOX object.
If you are using a relatively large resource file with several trees, you may want to reserve some memory space for the RCS file to prevent it from being "trampled" by your GFA BASIC program. Use the GFA BASIC statement "Reserve Fre(0)-XXXX" where "XXXX" is the number of bytes to reserve. In the interpreted mode, GFA BASIC will not automatically release this memory for you; each time you run the application your available memory will be reduced unless you restore it using a modified Reserve statement such as "Reserve Fre(0)+XXXX-255". With the ST's huge memory, most programmers won't find this a problem, but you should be aware of it as a potential culpat in case your program suddenly crashes!
While this series has dealt solely with dialog boxes, remember that an RCS utility can also be used to create alert boxes, menus trees, free strings, bit images and icons. In some cases, GFA BASIC's built-in commands, such as the Alert and Menu statements, provide simpler solutions. More often than not, however, you will find that the power of a good RCS utility package will dramatically improve not only your program's appearance, but its ease of use as well.
John L. Hutchinson, currently on a two year tour of duty at the Australian Army War Games Center in Sydney, is the author of Naval Battle in Special Issue #4 of START.
Products Mentioned
GFA BASIC ver. 2.0, $79.95. MichTron, 576 Telegraph, Pontiac, MI 48053, (313) 334-5700
K-Resource, $39.95. Kuma Computers Ltd., Pangbourne, Berkshire, England 07357-4335.
|