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.
                     
RESERVE -362
                     
                     
                     
Next inform the AES (part of GEM) to free some space for a resource data
                     
block.
                     
~RSRC_FREE()
                     
                     
                     
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
                     
error.
                     
a&=RSRC_LOAD("rsc_1.rsc")
                     
                     
                     
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
                     
fileselector",1,"OK",v|
                     
  FILESELECT "\rsc_1.rsc","",r$
                     
  IF r$<>""
                     
found the resourec file, load it!
                     
    a&=RSRC_LOAD(r$)
                     
  ELSE
                     
Otherwise end the program
                     
    END
                     
  ENDIF
                     
ENDIF
                     
                     
                     
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&).
                     
~RSRC_GADDR(0,infobox&,tree%)
                     
                     
                     
Now, we ask the AES to calculate the x and y coordinates, so our form will
                     
appear in the centre of the screen.
                     
~FORM_CENTER(tree%,x&,y&,w&,h&)
                     
                     
                     
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
                     
generations.
                     
~OBJC_DRAW(tree%,0,7,x&,y&,w&,h&)
                     
                     
                     
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|.
                     
result|=FORM_DO(tree%,0)
                     
                     
                     
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.
                     
OB_STATE(tree%,result|)=BCLR(OB_STATE(tree%,result|),0)
                     
                     
                     
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.
                     
~RSRC_FREE()
                     
                     
                     
Put memory back as you found it.
                     
RESERVE
                     
                     
                     
All done, then ..
                     
END
                     
'
                     
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
                     
RETURN
                     
                     
                     
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
                     
status.
                     
                     
                     
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
                     
indirect
                     
                     
                     
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.
                     
                     

Takaisin

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