GfA Basic II

 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 
about that.

Firstly,  we'll have a look at the ERROR command,  which format is 
as follows:

             ERROR x

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 
example program:

     GOSUB Subroutine(7)
     PRINT "When back from the subroutine, A=";A
     END
     PROCEDURE Subroutine(A)
       PRINT "In the subroutine, A=";A
     RETURN

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:

         MENU array()
         MENU KILL
         MENU OFF
         MENU n,x
         ON MENU GOSUB procname
         MENU (x)
         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
         ON MENU

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 
zero.
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 
'proc_name'.
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
                 choosen anymore
      3         Makes the entry normal, so that it can be choosen
                 again

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[0]
     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
                 byte
     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:

                MOUSE x,y,k

'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 
are pressed.
The  next command I promised to write about in the previous  issue 
of ST NEWS was GRAPHMODE. Its format is:

                GRAPHMODE x

'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.

   a=XBIOS(20)              Hardcopy

   A$=SPACE$(512)
   a=BIOS(4,0,L:VARPTR(A$),1,1,0)
        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 
PSAVE.