This is the first article about Resource Programming with GFA Basic Part 1 Snapped out by Sorcerer of The Digital Dictators! 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.