Resource Programming with GFA Basic
                         Part 1
Welcome to a new tutorial, on how to use Resource files with GFA Basic
(versions 2 and 3  Basics will be catered for). Over the next few issues, John
Peters will present programs and advice for the management of Resource files.
A Gentle introduction
Let's assume you have written a program, which requires the user to select
between saving data to Drive A, or B. You could use an Alert box, which most of
you will have seen, or you could draw some boxes for the user to click in, thus
indicating the Drive of their choice; as seen below:
______  ______
| A  |  | B  |
The problem would be, that first you would have to draw these boxes, using a
drawing program, such as Degas etc. and then cut out the bits you want, load
these bits into your program, and now the real fun starts; your program would
have to detect where the mouse is, and if you clicked inside one of the boxes,
which one it was, and then clear up the screen ....., and another problem is
that what you have just written only works in one resolution. Have I convinced
you that a simple thing like just 2 boxes involves an awful lot of hard work?
If I have? Then the answer is to use a Resource file.
Firstly you will need a Resource construction program, such as the one which
comes with GFA Basic V3, or you can buy one, such as K Resource 2 or Wercs,
there are probably a lot more on the market, but those are the leading ones.
There is also a PD editor but it is not as good as the commercial ones. These
programs save a Resource file onto your disk.
A Resource file (usually having the extender .RSC) is a special file which
contains one or more Resources, which are simply a collection of data. This
data when loaded, gives the computer, (using GEM), instructions on putting
'boxes', pictures or text, onto the screen in all resolutions.
Each Resource file contains a TREE, so called because the structure of the data
is arranged like branches coming off a tree's main trunk. The data for this
TREE is kept so that it is translated by the computer to work in the current
resolution that you are in without any extra programming. This file can contain
more than one TREE structure, so you can have may different choices within one
Resource. A tree may be one of 5 different types: FORM, ALERT, MENU, FREE IMAGE
or FREE STRING. Forms and Menus are the most common types, and in turn they may
contain OBJECTS. A good example of this is the GEM desktop, where the grey
(green on colour systems) screen, is the form, and on that form you have the
directories (the parent objects), and within the directories there are further
files (children of the parent objects).Having created a Resource file, you need
to create one of the structures. Let's suppose you choose a FORM. You could
imagine this to be a piece of paper onto which you are going to draw something
(an object). In turn that object may contain objects within itself, thus
becoming the parent of child objects. You can go up to 7 generations deep,
before GEM can't cope and crashes. (ie. an object within an object etc...)
Menus are a type of tree most users will have seen, where the Menu Bar is
created, the Menu Item being the parent, and the items in the dropped down bit,
being its children.
Alerts should be also quite familiar, these are a form with children on it.Free
Strings and Free Images can be TREES in their own right, but the programming to
control these is a little bit complicated, and these are usually seen as
objects within a form.
The Concept Of Trees And Children
If you imagine a box on the screen, (this is the form), a slider bar drawn in
that box would be a child of the form, and a slider within the slider bar would
be the child of the slider bar, and the grandchild of the form. If you now put
other objects on the form, they too would become children of the form and
within those objects other objects would become grandchildren .. and so on.
(Isn't sibling rivalry easy?)
"Why on earth should I bother with all this?", I hear you cry. Simple! The
programming involved to graphically represent multiple choices is minimal, and
works for all resolutions. Imagine having to write a program to draw a box in
all resolutions, then detect whether the mouse was clicked inside it, and if it
was, invert the box's colour, as well as revert back to the original colour if
clicked on a second time. And that's only for ONE box! That's what resources
are all about.
Some  Things To Be Aware Of When Using Resource Files.
Resource files cannot be bigger than 64K (which is quite a size in resource
file terms). You should reserve space for your file, clear that space, prior to
loading, and clear up the space on exit-ing your program. As already mentioned,
your objects should not be nested more than seven deep, so really the command:
~OBJC_DRAW(tree%,0,99,x,y,w,h) where 99 is usually quoted as the depth, need
only be 7. The last object of a tree should not be editable, otherwise you will
crash your program. You should always do a 'sort' of the objects prior to
saving your .RSC file, again the result of not doing so is a crash.
Resource programming is quite straight forward, despite it's outward
appearance, as GEM does most of the work for you. The results can be very good,
and a bit of playing around with icons will result in a nice graphic screen
which leaves the user under no doubt about what he has to do.
Using a Resource file editor.
All the editors I have used, save at least 3 files. One is the resource file
data (extender .RSC), the next is a definition file which is used by the editor
for that resource file, and the last, is an include file for your own programs.
The reason for this include file is that during the construction of a resource,
you should give all the objects names (preferably meaningful ones), so that
when you write your program, you know which object you wish to refer to, rather
than just use it's number. For example if you have a button which has got
"QUIT" in it, give it a name "QUIT".
Basic programming.
The programs that go with this article will work in GFA Basic versions 2 or 3,
however using version 3 makes the program a lot shorter (a good reason to
upgrade). The resource files are also included on the disk. The program that
follows was written in Version 3 Basic, but the explanation should be clear
enough for you to understand the Version 2 listing (on the disk as
RSC_1.BAS).Ok let's make a resource file, and a program to control it. This
first step is a very simple text dialog box, with an exit button. It shows some
important first steps in resource programming.
The first thing to do is to reserve some space for the resource file, so we
drop the memory requirements of Basic, by the length of the resource file.
Next inform the AES (part of GEM) to free some space for a resource data
Now load the resource file. The command RSRC_LOAD loads the resource file,
calculates any reformatting necessary for different screen resolutions, and
returns an error. If the error is 0 then there was an error, non zero = no
If there was an error, try an find the resource file
IF a&=0
  ALERT 1,"Can't find Resource file|Try and select it with|the
  FILESELECT "\rsc_1.rsc","",r$
  IF r$<>""
found the resourec file, load it!
Otherwise end the program
Now set up the variables from the resource file. Remember that I said that the
objects should have meaningful names, which were given  whilst constructing
them. These variable names have been imported into the procedure set_vars from
the resource editor.set_vars
We need to get the start address of the resource structure. The parameters are
passed to the routine in the order; type, index, returned address.Where type in
this case is for an object tree (0), and the array index is for the start of
the whole tree (infobox&).
Now, we ask the AES to calculate the x and y coordinates, so our form will
appear in the centre of the screen.
Get the part of the screen that is going to be over-written by the dialog box,
so you can restore it later on.
GET x&,y&,x&+w&,y&+h&,temp$
Now draw the form, starting at the first object, and going through all possible
Here is the clever bit, instead of having to detect all the possible mouse
positions, you hand over control to the AES, and the computer will now sit in a
loop, until you click on an object that has an exit status. It returns the
object's number that you clicked on in result|.
If you want to re-draw this form at some later date, then you have to reset the
status of the box you clicked on to exit. Otherwise it will be inverted next
time you re-draw the form.
Put the screen back to normal.
PUT x&,y&,temp$
If you have finished with your resource data, before you quit your program,
free up the space used by the resource data.
Put memory back as you found it.
All done, then ..
PROCEDURE set_vars
set up variables from the resource construction program.
  ' (* resource set indicies for RSC_1 *)
  LET infobox&=0    !form/dialog ## Tree Structure ##
  LET paper&=0      !BOX in tree INFOBOX
  LET line1&=1      !STRING in tree INFOBOX
  LET line2&=2      !STRING in tree INFOBOX
  LET line3&=3      !STRING in tree INFOBOX
  LET line4&=4      !STRING in tree INFOBOX
  LET line5&=5      !STRING in tree INFOBOX
  LET exit&=6       !BUTTON in tree INFOBOX
The example is not very exiting, but shows some important first steps in
programming resource files. It has not been my intention to explain all points
about constructing the file in the first place. You should note, that I have
said, that the object you exit the resource by clicking on, must be of exit
This status is one of the flags that an object may have. If you are going to
allow the AES to control your form, and only exit when you click on certain
objects, then these objects, must be capable of telling the AES that you wish
to exit when they are selected. Similarly, they must also be selectable in the
first place, otherwise you would not be able to click on them. (Try selecting
the text within the form, you can't, because these objects are not selectable).
Another point, is that having selected your exit box (OK), this now has become
selected. Next time you display that object, it will be presented inverted
(selected). To overcome this problem, before you carry on with your program,
you should reset that object's status.
To explain a bit more on flags and states of objects, an object may have the
following configurations:
OB_FLAGS            OB_STATE
========            ========
normal              normal
selectable          selected
default             crossed
exit                checked
editable            disabled
radio button        outlined
last object         shadowed
touch exit
hide tree
Taking the exit box in our form, it had the following OB_FLAGS set: selectable,
default, exit. When the program was run, the OB_STATE was normal, when you
click on it, it's OB_STATE became selected. Default means, that if you press
the RETURN key, then that object will behave as though you clicked on it.
Next time I shall introduce some multiple choice into the resource file, and
show the programming for it.


(C) Marko, Suomen Atari-sivut / ArkiSTo 2003