GFA BASIC TIPS & TRICKS by Richard Karsmakers
Originally published in ST NEWS Volume 1 Issue 5, launched on
October 5th, 1986.
In this issue of ST NEWS, we're going to have a look at some GfA
BASIC commands. I know you are all desperate to learn about the
SPRITE command, but you'll have to wait for the next issue to read
Firstly, we'll have a look at the ERROR command, which format is
The value of 'x' can be between -128 and 127, but has to be
integer. This command simulates the occurance of an error with the
number of 'x'. It can be handy when you are developing error-
handling routines. A command that is very closely related to the
ERROR command is the function ERR. This function gives you the
number of the error code belonging to an error that has just
occured. Also belonging to these is the command ON ERROR. If you
add the line "ON ERROR GOSUB procname" (where procname is the name
of a procedure or subroutine), the program will jump to that
procedure whenever an error might occur during execution of the
program. When it is necessary to jump to that routine a second
time (or more times), you must turn it on again in the error
routine itself (with "ON ERROR GOSUB procname"). When you want to
turn off this function (so that you'd get normal errors), you'll
have to add the line "ON ERROR".
By the way, there is a nice feature about procedures in GfA BASIC:
you can actually define local variables. Have a look at this
PRINT "When back from the subroutine, A=";A
PRINT "In the subroutine, A=";A
You see that A gets the value 7, but if you try to PRINT that same
'A' outside the procedure, you'll get 0 as a result. By the way,
the line with 'END' on it may be left away, because a program end
execution when it runs into a procedure (so through this way you
will never have to annoy yourself agian about "RETURN without
GOSUB errors" at the end of a program. Another thing that might be
handy to know is how you can define variables to be 'local'
without sending them with the GOSUB or receiving them with the
PROCEDURE. You can achieve this by using e.g. 'LOCAL A'. That way,
'A' will be a local variable.
Now, let's have a look at pull down menus etc. In this article, I
will describe the basics of menu programming; you'll have to look
at the listing of "The Ultimate Examining Utility", elsewhere in
this bulletin, for an example of how to use these basics.
Concerning 'menu' functions, GfA BASIC is equiped with several
commands. They are:
ON MENU GOSUB procname
ON MENU KEY GOSUB procname
ON MENU MESSAGE GOSUB procname
ON MENU IBOX a,x,y,w,h GOSUB procname
ON MENU OBOX a,x,y,w,h GOSUB procname
Quite a list, don't you think? Now, let's explain these commands
so you also know how to use them. Here's what you must do to set
up a menu bar with pull-down menus.
Firstly, you must 'DIM' an array, which must be one-dimensional.
It can have any name. The array must have a defined setup. For
example, each menu title with the pull down-titles must be parted
from another one of those lists by an empty string. The first menu
strings might look like this: "Desk", " About Examine","--------",
1,2,3,4,5,6,"". The menu bar title will be "Desk", and when you
touch that name with the mousepointer it will reverse and a pull-
down menu will drop down with the name " About Examine". You won't
find any numbers, nor will you find the "------------" (unless you
have any desk accesories in your system). The six numbers are so
called dummy strings, and the "--------" is necessary to divide
the whole; it will only show when there are any desk accesories.
To close it all, there's the empty string ("") to close this
series. Have a look at "The Ultimate Examining Utility" to see how
we've done it. And don't forget: you'll need to close ALL the
titles (the last pull down menu-name of the last menu bar-title)
with two empty string. You can see those defined after the
FOR....NEXT loop (also, have a look at the technique we used to
leave the loop once there are no strings anymore to be read. This
way, you may add menu entries without altering the loop all the
time. A note on the dummy-strings: their length must be unequal to
After defining the menu, you can turn it on by "MENU array()",
where 'array' is the name of the array you used to put in all the
entries. You must not put anything between the "()"! In the
example, we use Aa$().
Thus, you have created the menubar on the screen. By moving the
mousepointer to a title, the menu will drop down and you can
select an option you programmed. Immediately after you've set up
your menu-bar, you must use a line with "ON MENU GOSUB proc_name".
The 'proc_name' must be the name of the procedure that handles all
the subroutines, etc. After that line, you can create an endless
loop, for example by using the DO...LOOP command. In that loop,
you must use the line "ON MENU". Each time something happens to
that menu, the program will now branch to the routine called
Please have a look at our program now, and you'll see the
structure. Don't forget the line "MENU OFF", otherwise it might be
possible that menu bar titles will stay reverse when you don't
want it. The MENU OFF command takes care that all menu titles that
might have been reversed, are set normally.
There are a few variations to the ON MENU command. For example,
there is the ON MENY KEY GOSUB command. It works just like the ON
MENU GOSUB command, but this time for examining which key is
pressed on the keyboard. The commands ON MENU IBOX GOSUB and ON
MENU OBOX GOSUB are used to determine whether the mouse pointer is
in (IBOX) or out (OBOX) of a certain area on the screen,
determined by the coördinates x and y and the width w and height
h. The a is used to define which of the two boxes you use.
Then there's the ON MENU MESSAGE GOSUB command determines the
handle routines for GEM messages. MENU KILL turns off the whole
menu bar. The command MENU n,x can be used to perform things with
individual menu entries, of which the 'n' must be the index number
in the array of the menu (in our example, ACC$). The 'x' may have
the following values:
0 Removes a sign before the menu entry
1 Places a sign before the menu entry (to use this
succesfully, you must have at least one space
at the start of that menu entry)
2 Makes the menu entry light, so that it cannot be
3 Makes the entry normal, so that it can be choosen
The last command for use with menus is the MENU(x) command. This
enables swapping parameters from the ON MENU GOSUB routines to
your program. 'n' must be an integer value. Below, you'll find a
list of the possible values and the proper functions:
0 Gives the number of a pull-down menu point, when
it happens to be clicked
1-8 Gives the entries of the message-buffer
9 Gives a flag that indicates what has happened,
just like int_out
10,11 Gives the coördinates of the mouse
12 Gives the status of the mouse buttons
13 Gives the status of the keyboard-switchkeys
14 Gives scan code in high byte and ASCII code in low
15 Gives the number of mouseclicks
-1 Gives the address of the menu object tree
Now, let's have a look at the MOUSE command. With the help of
this, it is possible to determine the current x-and y-position of
the mousepointer, as well as the current status of the mouse
buttons. Its format is:
'x', 'y' and 'k' are variables, that will get the appropriate
values for x-and y position and the mouse buttons status. The x-
and y positions speak for theirselves, but the status of the
mousebuttons needs some explanation. It can have the following
values: 0 if no buttons are pressed, 1 if the left button is
pressed, 2 if the right button is pressed and 3 if both buttons
The next command I promised to write about in the previous issue
of ST NEWS was GRAPHMODE. Its format is:
'x' can be a number from 1 to 4. This command determines the
Graphics mode of the ST. Normally (value 1), the old graphics are
replaced by the new graphics. If it is 2, the old image will still
be visible through the new image (the new image is transparent).
Something like that happens when the value of x is 4. But here,
the new image is set there reversely. When x has the value 4, each
dot that was used by the old image will be cleared when it is also
used by the new image, and when the new image uses a dot that
wasn't used before, it will set is.
That's it for the commands I promised to explain. Now, let's have
a look at some of GfA BASIC's special operating system commands.
GfA BASIC enables the programmer to make use of standard OS
routines, implemented in GEMDOS, BIOS or XBIOS.
The formats of these commands are:
BIOS (f [,parameterlist])
XBIOS (f [,paremeterlist])
GEMDOS (f [,parameterlist])
Hereby, 'f' is the number of the function, and the 'parameterlist'
must be included with some functions as well. I think it's best to
just write down some examples here. You will be able to think of
some examples yourself when you have a good look at "ST Intern"
from Data Becker.
This defines a 512 byte long string variable, in which a
disk sector can be read.
4 = Function Number
0 = Flag: 0=read, 1=write, 2=read and ignore media change,
3=write and ignore media change
L:VARPTR(A$) = Determines the address in memory where the
sector contents should be written to
1 = Read one sector
1 = First logical sector to read
0 = Device number (A)
These commands definately widen the range of GfA BASIC's
capabilities. I sure hope to hear from you if you have had some
interesting experience with these commands. Next time, more about
these GfA BASIC commands: SETTIME, SPRITE, UPPER$, GET, PUT and
The text of the articles is identical to the originals like they appeared in old ST NEWS issues. Please take into consideration that the author(s) was (were) a lot younger and less responsible back then. So bad jokes, bad English, youthful arrogance, insults, bravura, over-crediting and tastelessness should be taken with at least a grain of salt. Any contact and/or payment information, as well as deadlines/release dates of any kind should be regarded as outdated. Due to the fact that these pages are not actually contained in an Atari executable here, references to scroll texts, featured demo screens and hidden articles may also be irrelevant.