
 ____    ____                      ______     
/\  _`\ /\  _`\   /'\_/`\  /'\_/`\/\  _  \  v1.02. The GEMMA 
\ \ \L\_\ \ \L\_\/\      \/\      \ \ \L\ \  extension for STOS. 
 \ \ \L_L\ \  _\L\ \ \__\ \ \ \__\ \ \  __ \  The power of GEM in 
  \ \ \/, \ \ \L\ \ \ \_/\ \ \ \_/\ \ \ \/\ \  the power of STOS.
   \ \____/\ \____/\ \_\\ \_\ \_\\ \_\ \_\ \_\
    \/___/  \/___/  \/_/ \/_/\/_/ \/_/\/_/\/_/
   
 1997 The GEMMA programming team. All rights reserved. Command list.

Anything with a asterisk by it ("*") represents that the command 
differs from Atari standard. As STOS extensions are limited to a 
number of commands, some SUBs had to be converted to FUNCTIONs and 
vice versa.

NB: a command which has a varptr() in it MUST have the varptr command. 
If you don't pass the variables through a varptr, then your system 
might crash!

The GEM commands
----------------

--------------------------------------------------------------------------
                            Message Passing
--------------------------------------------------------------------------

SUB appl_read ()
	Syntax: appl_read ap_id, length, varptr(message)
	
This reads LENGTH bytes from the program identifier AP_ID message 
pipeline, into the buffer at MESSAGE.

FUNCTION appl_write *
	Syntax: dummy=appl_write (ap_id, length, varptr(message))
	
This does the opposite of the above command. It writes LENGTH bytes in 
the message pipeline of the program identifier AP_ID from MESSAGE. 
The AP_ID should be the identifier of an accessory, found by the 
appl_find command.

FUNCTION appl_find
	Syntax: number=appl_find (name$)
	
NUMBER will contain the accessory number which has the name NAME$. 
This is for use of the appl_write command. NAME$ should be null 
terminated and should be 8 characters long (excluding the NULL)

FUNCTION appl_init
	Syntax: num=appl_init
	
Tells GEM you want to start using the GEM commands. This is not need 
for your STOS programs, since STOS automatically has one in it's 
compiler code on start up. Returned is your application id.

SUB appl_exit *
	Syntax: appl_exit (id)

Tells GEM you've finished using GEM. WARNING: Don't use this command 
in STOS! id is the application id returned from appl_init.

SUB appl_tplay (eventrec, num)

Plays back a series of actions recorded by appl_record, at the address 
EVENTREC, and NUM events should be played back.

FUNCTION appl_trecord (eventrec, num)

Records a series of users actions. EVENTREC& is an address of where 
the details are to be stored. 4 words (a word is two numbers long) are 
required for each event. NUM is how many events to record. 

The first word is 0, the second the type and the next two the data for 
that type:                   

 --------------------------------------------------------------------
| Type | Description    | Event-specific information                 |
 --------------------------------------------------------------------|
|   0  |   timer event  | Give the elapsed time in 200th of a second |
|   1  |  button event  | First data word is the button state, and   |
|      |                | the last for the number of clicks.         |
|   2  |   mouse event  | First data word is the x-codinate and the  |
|      |                | final the y.                               |
|   3  | keyboard event | The first data word is the key code and    |
|      |                | the final the key shift state.             |
 --------------------------------------------------------------------

FUNCTION appl_getinfo
	Syntax: info=appl_getinfo (type, varptr(out1), varptr(out2), 
			varptr(out3),varptr(out4))

This returns information about the AES, but is only available from AES 
v4.0.

TYPE specifies the results in OUT1, OUT2, OUT3 and OUT4

 --------------------------------------------------------------------
|      Name     | Value | Returns                                    |
 --------------------------------------------------------------------
| AES_LARGEFONT |   0   | Information about the AES Large Font. OUT1 |
|               |       | contains the AES font's point size. OUT2 is|
|               |       | the supported type of font, SYSTEM_FONT (0)| 
|               |       | is the system font or OUTLINE_FONT (1) if  |
|               |       | a outline font is being used. OUT4 is not  |
|               |       | used.                                      |
| AES_SMALLFONT |   1   | Returns information on the AES Small Font, |
|               |       | parameters the same as AES Large Font.     |
|  AES_SYSTEM   |   2   | Returns info on AES System Specifics. OUT1 |
|               |       | contains the res type (as in Getrez). OUT2 |
|               |       | contains the number of colours that the    |
|               |       | object library supports. OUT3 says 0 if    |
|               |       | colour icons are not supported, 1 if they  |
|               |       | are. If OUT4=0 then the extended resource  |
|               |       | file format is not supported, 1 if it is.  |
| AES_LANGUAGE  |   3   | Returns information about the langauge.    |
|               |       | OUT1 tells the language being used:        |
|               |       | 0=English, 1=German, 2=French, 3=reserved, |
|               |       | 4=Spanish, 5=Italian, 6=Swedish. OUT2, OUT3| 
|               |       | and OUT4 are not used.                     |
|  AES_PROCESS  |   4   | Returns information about the "AES Multiple|
|               |       | Process Support". If OUT1=0 then there is  |
|               |       | no pre-emptive multitasking, 1 if there is.| 
|               |       | If OUT2=0 then appl_find cannot convert the| 
|               |       | appl_init's between MiNT and AES, 1 if it  |
|               |       | can. If OUT3=0 then appl_search does not   |
|               |       | exist on this computer, 1 if it is. If     |
|               |       | OUT4=0, rsrc_rcfix is not implemented, 1 if| 
|               |       | it is.                                     |
|  AES_PCGEM    |   5   | Returns info about the AES's PC-GEM        |
|               |       | Features. If OUT1=0 then objc_xfind is not |
|               |       | available, 1 if it is. OUT2 is unused. If  |
|               |       | OUT3=0 then menu_click is not implimented, |
|               |       | 1 if it is. If OUT4=0 then shel_rdef and   |
|               |       | shel_wdef are not supported, 1 if they are.|
|               |       | NB: None of these commands are implimented |
|               |       | in this version of GEMMA.                  |
| AES_INGUIRE   |   6   | Returns information about the AES's Inquiry|
|               |       | Functions. If OUT1=0 then -1 is not a valid| 
|               |       | ap_id parameter to appl_read, 1 if it is.  |
|               |       | If OUT2=0 then -1 is not a valid length    |
|               |       | parameter to shel_get, 1 if it is. If      |
|               |       | OUT3=0 then -1 is not a valid mode         |
|               |       | parameter to menu_bar, 1 if it is. If      |
|               |       | OUT4=0 then MENU_INSTL is not a valid mode |
|               |       | parameter to menu_bar, 1 if it is.         |
|      -        |   7   | Reserved.                                  |
|  AES_MOUSE    |   8   | Returns info about the AES mouse. If OUT1=0|
|               |       | then mode parameters of 258-260 are not    |
|               |       | supported by graf_mouse, 1 if they are. If |
|               |       | OUT2=0 then the application has control    |
|               |       | over the mouse form, and 1 to indicate that| 
|               |       | the mouse form is maintained by the AES on |
|               |       | a per-application basis. OUT3 and OUT4 are |
|               |       | not used.                                  |
|  AES_MENU     |   9   | Returns info on the AES Menu Support. If   |
|               |       | OUT1=0 then sub-menus are not supported and| 
|               |       | 1 if MultiTOS style sub-menus are. If      |
|               |       | OUT2=0 then popup menus are not supported  |
|               |       | (by a single GEM command), 1 if they are.  |
|               |       | If OUT3=0 then scrollable menus are not    |
|               |       | supported and 1 if MultiTOS style          |
|               |       | scrollable menus are. If OUT4=0 then the   |
|               |       | MN_SELECTED message does not contain object| 
|               |       | tree information in msg+57 and 1 to        |
|               |       | indicate that it does.                     |
|  AES_SHELL    |   10  | Returns info on the AES Shell Support. OUT1| 
|               |       | and $ff indicates the highest legal value  |
|               |       | for the mode of shel_write. OUT1 and $ff00 | 
|               |       | indicate which extended shel_write mode    |
|               |       | bits are supported. If OUT2=0 then         |
|               |       | shel_write with a mode of 0 launches an    |
|               |       | application or 1 if it cancels the previous| 
|               |       | shel_write. If OUT3=0 then shel_write with |
|               |       | a mode of 1 launches an application        |
|               |       | immediately or 1 if it after the current   |
|               |       | program quits. If OUT4=0 then ARGV style   |
|               |       | parameter passing is not supported, 1 if it| 
|               |       | is.                                        |
| AES_WINDOW    |   11  | Returns info on the AES's window features. | 
|               |       | OUT1 will contain a bit mask of the modes  | 
|               |       | supported by wind_set and wind_get, if a   |
|               |       | bit is 1, it is supported. The mask is:    |
|               |       | 0=also returns windows below the top one   | 
|               |       | (WF_TOP), 1=WF_NEWDESK supported,          |
|               |       | 2=WF_COLOR supported, 3=WF_DCOLOR          |
|               |       | supported, 4=WF_OWNER supported,           |
|               |       | 5=WF_BEVENT supported, 6=WF_BUTTOM         |
|               |       | supported, 7=WF_ICONIFY supported,         |
|               |       | 8=WF_UNICONIFY supported, 9-15 unused. OUT2| 
|               |       | is unused. OUT3 is a bit mask of window    |
|               |       | types, 0=Iconify button present, 1=buttomer| 
|               |       | button present, 2=shift+mouse click on     |
|               |       | window send it to the button, 3="hot" close| 
|               |       | box supported, 4-15 unused. OUT4 is unused.|
| AES_MESSAGE   |   12  | Returns info on the AES's extended         |
|               |       | messages. OUT1 contains a bit map of       |
|               |       | supported messages, 0=WM_NEWTOP supported, |
|               |       | 1=WN_UNTOPPED supported, 2=WM_ONTOP        |
|               |       | supported, 3=AP_TERM supported, 4=Shutdown | 
|               |       | and res changes supported, 5=CH_EXIT will  |
|               |       | be sent, 6=WM_BOTTOMED will be sent,       |
|               |       | 7=WN_ICONIFY will be sent, 8=WN_UNICONIFY  |
|               |       | will be sent, 9=WM_ALLICONIFY will be sent,| 
|               |       | 10-15 unused. OUT2 is a bit mask of extra  | 
|               |       | messages supported, which is unused. OUT3  |
|               |       | is a bit mask of supported message         |
|               |       | behaviour: 0=WN_ICONIFY messages give      |
|               |       | co-ordinates, 1-15 not used. OUT4 is       |
|               |       | unused.                                    |
|  AES_OBJECT   |  13   | Returns info on the AES's extended objects.| 
|               |       | If OUT1=0 then 3D objects are not          |
|               |       | supported, 1 if they are. If OUT2=0 then   | 
|               |       | objc_sysvar is not present, 1 if it is. If | 
|               |       | OUT3=0 then just the system font is        |
|               |       | supported, 1 if others are available (eg   |
|               |       | GDOS is installed). OUT4 is reserved for OS| 
|               |       | extensions.                                |
|  AES_FONT     |  14   | Returns info on the AES's form support. If |
|               |       | OUT1=0 then 'flying dialogs' are not       |
|               |       | supported, 1 if they are. If OUT2=0 then   |
|               |       | keyboard tables are not supported, or 1 if | 
|               |       | MagiC style keyboard tables are supported. | 
|               |       | If OUT3=0 then the last cursor position    |
|               |       | from objc_edit is not returned or 1 if it  |
|               |       | is. OUT4 is reserved.                      |
 --------------------------------------------------------------------

Returns 1 if an error occurred or 0 otherwise.

NB: A value type above 4 is only supported from AES version 4.1.

--------------------------------------------------------------------------
                                Events
--------------------------------------------------------------------------

FUNCTION evnt_keybd
	Syntax: key=evnt_keybd
	
This returns the next KEY pressed. The low byte is the ASCII code and 
the high byte is the scan code for a special key.

                   ----------------------------------
                  |       Special key        | Value |
                   ----------------------------------
                  |  [control]+cursor left   |  115  |
                  | [control]+cursor right   |  116  |
                  |   [control]+clr/home     |  119  |
                   ----------------------------------

FUNCTION evnt_button
	Syntax: action=evnt_button (clicks, mask, state, varptr(xout), 
					varptr(yout), varptr(button), 
					varptr(kstate))

Waits for a particular mouse button state. CLICKS is a variable that 
contains the maximun number of mouse clicks that the application is 
waiting for. The number of mouse clicks is returned in ACTION. MASK, 
STATE and BUTTON use a bit mask for the state of the button: bit 0 is 
the left button and bit 1 is the right. A value of 0 means the button 
is up and 1 pressed down. The state of all buttons is returned in 
BUTTON. XOUT and YOUT are the position of the mouse when the state 
occurred and KSTATE give the state of the [shift] keys. With the 
following bits giving the state:

                      --------------------------
                     |    Mask    | Key         | 
                      --------------------------
                     |     1      | right shift |
                     |     2      | left shift  |
                     |     4      | Control     |
                     |     8      | Alt         |
                      --------------------------

FUNCTION evnt_mouse *
	Syntax: dummy=evnt_mouse (flag, x, y, w, h, varptr(xout), 
				varptr(yout), vartpr(button), 
				varptr(kstate))

X, Y, Width and Height give a rectangle, which this routine waits for 
the mouse to enter or leave. If FLAG=0 then the routine will return 
when the mouse comes in, or FLAG=1 to exit. The position of the mouse 
when the event occurred is in XOUT and YOUT and the state and shift 
keys in BUTTON and KSTATE as defined above.

SUB evnt_mesag
	Syntax: evnt_mesag varptr(message)

Waits for a message in the applications pipeline and puts this in the 
butter at MESSAGE. The buffer should be at least 16 bytes.

Eg

10 DIM mess(16)
20 evnt_mesag vartpr(mess(0))
30 TYPE=deek (varptr(mess(0))

SUB evnt_timer
	Syntax: evnt_timer time
	
Waits for TIME milliseconds to pass.

FUNCTION evnt_multi
	Syntax: mask=evnt_multi (eflags, clicks, mask, state, flag1, 
				x1, y1, w1, h1, flag2, x2, y2, w2, h2, 
				varptr(message), time, varptr(xout), 
				varptr(yout), varptr(button), 
				varptr(kstate), varptr(key_pressed), 
				varptr(gotclicks))

This waits for a number of events to happen (a combination of the 
events commands). EFLAGS contains which events to look for, each in a 
bit:

                -------------------------------------
               | Mask |     Name      |    Alias     |
                -------------------------------------
               |  1   |    MU_KEYBD   |  evnt_keybd  |
               |  2   |    MU_BUTTON  | evnt_button  |
               |  4   |     MU_M1     |  evnt_mouse  |
               |  8   |     MU_M2     |  evnt_mouse  |
               | 16   |    MU_MESAG   |  evnt_mesag  |
               | 32   |    MU_TIMER   |  evnt_timer  |
                -------------------------------------

KEY_PRESSED is the same returned value as evnt_keybd. CLICKS, MASK, 
STATE, XOUT, YOUT, BUTTON and KSTATE are defined in evnt_button. 
GOTCLICKS is the same return output as evnt_button. MESSAGE is defined 
in evnt_mesag and TIME in evnt_timer. FLAG1 to H2 of the parameters 
are for the evnt_mouse features.

The return value is a mask of the above table, saying which events 
occured. NB: with this evnt_multi command you can watch for more than 
one event.

Eg

10 dim MESS(16)
20 EV=evnt_multi (MU_KEYBD+MU_BUTTN+MU_MESAG,258,3,0,0,0,0,0,0,0,0,0,0,0,
varptr(MESS(0)),0,varptr(XOUT),varptr(YOUT),varptr(BUT),varptr(KSTATE),
varptr(KEY),varptr(CLICKS))
30 if EV and MU_BUTTN then...


If you AND the result with a message number type, and the result is 1, 
then there is a message from GEM about that type in your variables.

Note that GEM will only return to your program when a message in 
EFLAGS has been found.

FUNCTION evnt_dclick
	Syntax: click_speed=evnt_dclick(newvalue, setorget)
	
Sets or gets the mouse double click speed, if SETORGET=1 then the 
speed is set to whatever NEWVALUE is, and the double click speed is 
returned if SETORGET=0. These are the same values from the Control 
Panel, ranging from 0 to 4.

--------------------------------------------------------------------------
                                Menus
--------------------------------------------------------------------------

FUNCTION menu_bar *
	Syntax: dummy=menu_bar (tree, flag)

Displays or removes a menu bar. If FLAG is 1 it is shown, and 0 to be 
removed. The menu should be created in a Resource Construction Kit, 
such as WERCS or Interface. TREE is an address to a valid menu (found 
by rsrc_load and rsrc_gaddr). The menu bar should be removed before 
quiting. NB: Removing an item does not cause the menu bar to be 
cleared.

SUB menu_icheck
	Syntax: menu_icheck tree, item, flag
	
Displays a tick (a check mark) by the item numbered ITEM if FLAG=1, 
else removes it is FLAG=0. TREE is the address of a valid menu.

SUB menu_ienable
	Syntax: menu_ienable tree, item, flag
	
Fades the item numbered ITEM if FLAG=0 (this also means you can't 
click on it), and FLAG=1 when the item is to be retained at full 
brightness (and meaning you can select it). TREE is the address of a 
valid menu.

SUB menu_tnormal
	Syntax: menu_tnormal tree, title, flag

This can display a title numbered TITLE in normal video if FLAG=1, 
else in reverse if FLAG=0. TREE is the address of a valid menu. This 
is needed to unhighlight a title when an item is clicked on when it's 
displayed.

SUB menu_text
	Syntax: menu_text tree, item, text$
	
Modifies the text in item number ITEM to TEXT$. TEXT$ should be null 
terminated. TREE is the address of a valid menu. TEXT$ shouldn't be 
longer than the orginal string text.

FUNCTION menu_register
	Syntax: error=menu_register (id, title$)

This command will register the title TITLE$ in the 'Desk' menu if 
under a multitasking environment.

ID is the identification number of the application, and TITLE$ is a 
string which is null terminated.

TITLE$ should be 8 characters long, padded with spaces if nessesary, 
and after these 8 characters there *MUST* be a chr$(0)

This returns a -1 if an error occurred or the menu identifier 
otherwise.

You should not call this unless you are creating an accessory (in 
STOS?) or MultiTOS is loaded.

FUNCTION menu_popup
	Syntax: error=menu_pop (menu, xpos, ypos, mdata)
	
This displays a popup menu. Note this is only available as of AES 
v3.30

MENU is the address of a menu structure (see menu_attach), XPOS and 
YPOS being co-ordinates of the most left position of the menu.

The state of the menu will be filled in the address of MDATA if the 
function returns a value of 1. This also contains which button the 
user pressed.

Returns 0 if an error occurred or 1 if successful.

SUB menu_attach *
	Syntax: menu_attach flag, tree, item, mdata

This allows the programmer to attach a menu to another menu creating a 
sub-menu. This is available from AES v3.30 and above. In AES v4.0 and 
beyond, an appl_getinfo call should be used to find what this command 
does.

FLAG sets the mode.

 -----------------------------------------------------------------
| FLAG |    Name    | Function                                    | 
------------------------------------------------------------------
|   0  | ME_INQUIRE | Returns info on a sub-menu which it puts    |
|      |            | into MDATA.                                 |
|   1  | ME_ATTACH  | Attachs or changes a sub-menu. TREE is the  |
|      |            | address of the menu to attach (or remove)   |
|      |            | and ITEM is which item the menu will be     |
|      |            | assigned (or removed) to.                   |
|   2  | ME_REMOVE  | Removes a sub-menu, same parameters as      |
|      |            | ME_ATTACH (1) except that MDATA should be 0.|
 -----------------------------------------------------------------

MDATA should always point to a structure as follows (except 
ME_REMOVE):

LONG  mn_tree     - the address of a tree menu.
WORD  mn_menu     - index to a parent object of the menu items.
WORD  mn_item     - the starting menu item.
WORD  mn_scroll   - if 0 the menu will not scroll, if 1 and the number 
                    of menu item exceed the menu scroll heigh, up and 
                    down arrows will appear which allow the user to 
                    scroll up and down respectively through the 
                    choices.
WORD  mn_keystate - unused and should be 0.

Example creating a structure:

10 dim MENSTRUCT (12)
20 A=varptr(MENSTRUCT(0))
30 loke A+0,TREE
30 doke A+4,MENU
40 doke A+6,ITEM
50 doke A+8,0
60 doke A+10,0

...A will contain the stucture pointer.

NB: AES versions less than 4.1 have a bug which causes the AES to 
crash when changing or removing a sub-menu!!!

The menu items should be created with G_STRING's in your Resource 
Construction Set.

Hints: 1) Pad the sub-menu with spaces to the end of the menu. 2) Do 
not attach a sub-menu to itself! 3) menu_istart only works with 
sub-menus created with menu_attach.

FUNCTION menu_istart
	Syntax: result=menu_istart (flag, tree, imenu, item)

This command will shift a sub-menu that is already attached to a menu, 
and align it vertically with the specified object in the sub-menu. 
This is available from AES v3.30 and above.

The object will be modified is FLAG=1, and not if 0, however the 
already sub-menu item index (which is already aligned) will be 
returned with it's item.

TREE is the address of the menu to alter. IMENU specifies the object 
which the AES will align the menu item ITEM with.

Returns 0 if an error occurred or the index which is now aligned if it 
worked.

SUB menu_settings *
	Syntax: menu_settings flag, set

This sets the global settings for both popup and scrollable menus 
created by menu_popup and menu_attach. Available as of AES v3.30.

If FLAG=0 then the values will be returned at the address SET 
(stucture follows). If FLAG=1 then the values are set, again SET is 
the address of the stucture.

LONG display - Sub-menu display delay in milliseconds
LONG drag    - Sub-menu drag delay in milliseconds
LONG delay   - the single click delay while scrolling scrollable menus 
               in milliseconds
LONG speed   - a continous scroll delay in milliseconds
WORD height  - menu scroll height (in items)

Note that this is a global setting, and not just localised to the 
application. So, use sparingly, or only use to get the variables.

--------------------------------------------------------------------------
                                  Objects
--------------------------------------------------------------------------

SUB objc_add *
	Syntax: objc_add tree, parent, child
	
Adds an object numbered CHILD in the object PARENT at the address of 
the tree at TREE.

FUNCTION objc_delete
	Syntax: error=objc_delete (tree, object)
	
Deletes the object numbered OBJECT from the tree TREE and also 
removes the link from the parent to the OBJECT. Returns 0 if there was 
an error, or non-zero if no error occured.

SUB objc_draw *
	Syntax: objc_draw tree, object, depth, x, y, w, h
	
Draws part or all of the tree TREE starting at OBJECT with a depth of 
DEPTH, using a clipping rectangle X, Y, W, H. If DEPTH=0 then only the 
start OBJECT is drawn; if DEPTH=1 then only the first generation are 
drawn... and so on.

FUNCTION objc_find
	Syntax: error=objc_find (tree, object, depth, x, y)
	
Returns the OBJECT number of an item in the tree TREE which is a 
point X,Y. The search begins at OBJECT and to a depth of DEPTH 
(explained above). If the point is not under any object, then -1 is 
returned.

FUNCTION objc_offset
	Syntax: error=objc_offset (tree, object, varptr(x), varptr(y))
	
Returns in X and Y the co-ordinates of OBJECT in the tree at TREE 
relative to the screen. Returns 0 if there was an error, else anything 
else if there wasn't an error.

SUB objc_order *
	Syntax: objc_order tree, object, newpos
	
Moves the object OBJECT in the tree TREE to a different position to 
its parents list of children.

 -----------------------------------------
| Newpos |         Function               |
 -----------------------------------------
|  -1    | Moved to the front of the list |
|   0    |  Moved to the end of the list  |
|   1    |   Moved to 1 from the end      |
|   2    |   Moved to 2 from the end...   |
 -----------------------------------------
 
FUNCTION objc_edit
	Syntax: error=objc_edit (tree, object, char, index, kind, 
				varptr(newindex))

This is the low-editing of the object OBJECT in tree TREE, of which 
the object must be G_TEXT or G_BOXTEXT. The operation depends on KIND:

 ---------------------------------------------------------------------
| KIND |  Name   | Function                                          | 
 ---------------------------------------------------------------------
|  1   | ED_INIT | combine string from te_ptext and te_ptmplt of the | 
|      |         | TEDINFO structure into a formatted string and     |
|      |         | display it with the text cursor on                |
|  2   | ED_CHAR | Check if the character CHAR is valid against      |
|      |         | te_pvalid and update te_ptext and re-display the  |
|      |         | string. The orginal index in the string to use is |
|      |         | INDEX and the updated value is stored in NEWINDEX |
|  3   | ED_END  | Removes the text cursor                           |
 --------------------------------------------------------------------

This returns 0 if there was a error, anything else if there wasn't.

SUB objc_change *
	Syntax: objc_change tree, object, x, y, w, h, newstate, 
			    flag

Changed the ob_state field of the object OBJECT in the tree TREE to 
be NEWSTATE. If FLAG=1, then the object is redrawn with a rectangle 
clip of X,Y,W,H. If FLAG=0 then the object is not redrawn.

FUNCTION objc_sysvar
	Syntax: error=objc_sysvaR (mode, which, in1, in2, 
	varptr(out1), varptr(out2))

This sets or changes the colours in 3D objects. Available from AES 
v3.40.

If MODE=0 then the values will be read, but 1 will set the values. 
WHICH is which button/object wish to change. If MODE=0 then IN1 and 
IN2 are unused, if MODE=1 then OUT1 and OUT2 are not used.

 --------------------------------------------------------------------
|  Name     | WHICH | Function                                       |
 --------------------------------------------------------------------
|  LK3DIND  |   1   | If IN1/OUT1=1 then the text in indicators moves|
|           |       | when selected, 0 if is doesn't. If IN2/OUT2=1  |
|           |       | then the colour in a indicator object changes  |
|           |       | when selected, 0 if not.                       |
|  LK3DACT  |   2   | Same as LK3DIND but for activator objects.     |
| INDBUTCOL |   3   | IN1/OUT1 is the default colour for indicator   |
|           |       | objects. IN2/OUT2 unused.                      |
| ACTBUTCOL |   4   | IN1/OUT1 is the default colour for activator   |
|           |       | objects. IN2/OUT2 unused.                      |
| BACKGRCOL |   5   | IN1/OUT1 is the default colour for background  |
|           |       | objects. IN2/OUT2 unused.                      |
|  AD3DVAL  |   6   | OUT1 contains the number of pixels which will  |
|           |       | be added to each horizontal side of an         |
|           |       | indicator or activator object. OUT2 contains   |
|           |       | the number the same as OUT1 except for the     |
|           |       | vertical. This cannot to set, only read.       |
 --------------------------------------------------------------------
 
Returns 0 if unsuccessful or non-zero otherwise.

Again like menu_settings the setting are global, so should not really 
be set in a program, only read.

--------------------------------------------------------------------------
                                  Forms
--------------------------------------------------------------------------

FUNCTION form_do
	Syntax: index=frm_do (tree, object)
	
After the form has been drawn, this will let the user fill it in. 
TREE is the address of a valid dialog box, and OBJECT is where the 
interaction starts. OBJECT is the first number to a editable text 
field, 0 if there isn't one.

Note that you should have drawn the tree first with objc_draw.

The return value is the object selected (such as a button).

SUB form_dial
	Syntax: frm_dial flag, x1, y1, w1, h1, x2, y2, w2, h2
	
The function of this command depends on the status of FLAG

 ---------------------------------------------------------------------
| FLAG |   Name     |                  Function                      |
 ---------------------------------------------------------------------
|   0  | FMD_START  | Doesn't do anything on current verions, but    |
|      |            | should ALWAYS be used when starting a load of  |
|      |            | frm_dial calls.                                |
|   1  | FMD_GROW   | Draws a box expanding from x1, y1, w1, h1 to   |
|      |            | x1, y2, w2, h2.                                |
|   2  | FMD_SHRINK | Draws a shinking box from x2, y2, w2, h2 to    |
|      |            | x1, y1, w1, h1.                                | 
|   3  | FMD_FINISH | Sends a message to redraw the screen of which  |
|      |            | is in 8the rectangle x2, y2, w2, h2            |
 --------------------------------------------------------------------
 
FUNCTION form_alert
	Syntax: number=frm_alert (default, text$)
	
This brings up a GEM alertbox. TEXT$ must be a string containing no 
more then 255 characters. text$ is made by of three parts, the icon 
number, the message and the button names:

The format for text$ is [icon number][message][button names].

Icon number 1 is an '!" symbol. Icon 2 is a '?' and icon 3 is a 'Stop 
message'. 'message' and 'button names' are best used by having a space at 
the start and end of the text. In 'message' having a '|' character will 
separate the text onto another line. A '|' in 'button names' will create 
another button. Thus...

[1][ Hello | there | World! ][ Ok | Cancel | Info ]

...would produce an alert box like...

 ______________________________________
|                                      |
|  !!!    Hello                        |
|  !!!    there                        |
|  !!!    World!                       |
|  !!!                                 |
|          ____   ________   ______    |
|  !!!    [ Ok ] [ Cancel ] [ Info ]   |
|                    |
 

There should be a maximum of 3 buttons, and the length of each should 
not exceed 20.

DEFAULT is the button to be highlighted, and if the user presses 
[return] when the alert is up, that button number is chosen. If it's 1 
the first button will be selected, 2 for the second etc. 0 if there is 
to be no default button.

Returned is the button number the user clicked on.

Check the ALERGRAF.ASC for an example of alertboxes, gemmaver$, 
graf_growbox and graf_shrinkbox.

SUB form_error *
	Syntax: frm_error errorcode
	
Brings up a alertbox corresponding to the 'PCDOS error code'. Anything 
above 64 (really -64) is ignored. Not all of the errors are recoginised, 
but here are the ones that are:

 ----------------------------------------------------------------------
|  Code   |  Error produced                                            |
 ---------|------------------------------------------------------------
|         |                                                            |
| 2,3,18  | "This application cannot find the folder or file that you  |
|         | tried to access."                                          |
|         |                                                            |
|   4     | "This application does not have room to open another       |
|         | document. To make room, close any document that you do not |
|         | need."                                                     |
|         |                                                            |
|   5     | "An item with this name already exists in the directory, or|
|         | this item is set to read-only status."                     |
|         |                                                            |
| 8,10,11 | "There is not enough memory for the application you tried  |
|         | to run."                                                   |
|         |                                                            |
|   15    | "The drive you specified does not exist."                  |
 ----------------------------------------------------------------------
 
Check FRMALERT.ASC for an example.

SUB form_center
	Syntax: frm_center tree, varptr(x), varptr(y), varptr(w), 
	varptr(h)

This centers the tree TREE and returns its co-ordinates in X, Y, W 
and H. The tree is modified.

SUB form_keybd *
	Syntax: frm_keybd tree, obj, nextobj, kc, varptr(newobj), 
		varptr(keyout)

This command is only really useful if you are creating your own 
form_do routine.

TREE is the address of a tree (from rsrc_gaddr) which you want to use. 
OBJ is the default edit field you wish to edit (0 if none). NEXTOBJ is 
currently reserved and should be passed as 1. NEWOBJ is an address to 
an variable. This is the last object to be edited. KC is a value from 
evnt_keybd or evnt_multi which represents a keyboard scan code (and 
ASCII value). KEYOUT is a value which was passed to objc_edit is the 
key needed processing, 0 if not.

FUNCTION form_button
	Syntax: status=frm_buttn (tree, obj, clicks, varptr(newobj))

This is to be used with form_keybd in creating your own form_do 
handler.

TREE is the address of a tree which you wish to use (from rsrc_gaddr) 
to process button events for. OBJ is the object selected which needs 
processing. CLICKS is the number of times the mouse button was 
clicked. NEWOBJ is the next object which is to be edited (or 0 if 
none) - if the top bit is set then a touchexit object was 
double clicked on.

Returns a 0 if it finds a EXIT or TOUCHEXIT, else 1.

To make your own form_do handler:

1) Check out for mouse clicks
2) When the user clicks, use objc_find to find the object that was 
   clicked on
3) If a real button was clicked on, do a form_button with the need 
values.

--------------------------------------------------------------------------
                                 Graphics
--------------------------------------------------------------------------

SUB graf_rubberbox
	Syntax: graf_rubberbox x, y, minw, minh, varptr(outw), 
	varptr(outh)
	
Lets a rubberbox (such as when selecting multiple files on the 
desktop) starting at X,Y with a minimum width and height MINW and 
MINH. The size of the box after the user lets go is returned in OUTW 
and OUTH.

SUB graf_dragbox
	Syntax: graf_dragbox w, h, startx, starty, boxx, boxy, boxw, 
			     boxh, varptr(outx), varptr(outy)

Lets the user drag a box of size W,H starting at STARTX, STARTY, with 
the final position in OUTX, OUTY. The box will always be contained in 
the rectangle BOXX, BOXY, BOXW, BOXH.

SUB graf_movebox
	Syntax: graf_movebox w, h, x1, y1, x2, y2

This draws a box of width W and height H moving from x1, y1 to x2, y2

SUB graf_growbox
	Syntax: graf_growbox x1, y1, h1, w1, x2, y2, h2, w2

Graf_growbox calls GEM to draw a number of boxes growing from x1,y1 of 
size h1,h1 to x2,y2 to the size h2,w2.

Check ALERGRAF.ASC for an example of alertboxes, gemmaver$, graf_growbox 
and graf_shrinkbox.

SUB graf_shrinkbox
	Syntax: graf_shrinkbox x1, y1, h1, w1, x2, y2, h2, w2

Does the same as graf_growbox but instead shrinks.

Check ALERGRAF.ASC for an example of alertboxes, gemmaver$, graf_growbox 
and graf_shrinkbox.

FUNCTION graf_watchbox
	Syntax: return=graf_watchbox (tree, object, instate, 
		       outstate)

This changes a box while the user is in or out of the box specified by 
OBJECT in the tree TREE. The mouse *MUST* be down when this is called. 
It returns 0 if the mouse is outside the box when the user released 
the button, and 1 if it's inside. INSTATE and OUTSTATE give the box's 
ob_state when the pointer is inside and outside of the box 
respectively.

FUNCTION graf_slidebox
	Syntax: postion=graf_slidebox (tree, parent, object, 
			vertical)

Lets the user move the box of the object OBJECT from the tree TREE 
within its parent box given by PARENT. If VERTICAL=1 then the movement 
is vertical, if it's 0 then it's horizontal. The returned value is the 
position of in inner box when the mouse is released, ranging from 0 to 
1000 with 0 being top or left (depending on VERTICAL). The mouse MUST 
be down when this is called.

FUNCTION graf_handle
	Syntax: dummy=graf_handle (vaprtr(wcell), varptr(hcell), 
	varptr(wbox), varptr(hbox))
	
Returns the current GEM VDI handle, with the height and width of the 
current character cell in HCELL and WCELL respectively, with the 
minimum size of a box large enough to enclose a character in WBOX and 
HBOX.

FUNCTION graf_mouse *
	Syntax: dummy=graf_mouse flag, varptr(user_form)

Flag is what to change the GEM mouse pointer to:

 ----------------------------------------------------------------------
|  Code  |  Arrow form                                                 |
 ----------------------------------------------------------------------
|   0    | Arrow                                                       |
|   1    | Text cursor                                                 |
|   2    | Busy bee                                                    |
|   3    | Pointing finger                                             |
|   4    | Exended fingers                                             |
|   5    | Thin cross hair                                             |
|   6    | Thick cross hair                                            |
|   7    | Outline cross hair                                          |
|  255   | User defined. user_form is the address of the new pointer.  |
|  256   | Hide mouse                                                  |
|  257   | Show mouse                                                  |
 ----------------------------------------------------------------------

user_form can be an array, with the following structure:

       -----------------------------------------------------------
      | Byte | Function                                           |
       -----------------------------------------------------------
      |  1   | x co-ordinate of hot spot                          |
      |  2   | y co-ordinate of hot spot                          |
      |  3   | should be 1                                        |
      |  4   | mask colour                                        |
      |  5   | data colour                                        |
      | 6-22 | bits of mask                                       |
      |22-38 | bits of data                                       |
       -----------------------------------------------------------
 
For example:

arrow(1)=1
arrow(2)=1
arrow(3)=1
arrow(4)=0
arrow(5)=1
arrow(6)=%10110100...

etc.

SUB graf_mkstate
	Syntax: graf_mkstate varptr(x), varptr(y), varptr(state), 
	varptr(kstate)
	
This returns the current mouse position in X and Y, the mouse button 
state in STATE and the state of the shift, alt and control keys in 
KSTATE. If bit 0 of STATE is set, the left button is pressed, and if 
bit 1, the right button. If the value of any bit is 0 then the button 
is up, while 1 means it's down.


                      --------------------------
                     |    Mask    | Key         | 
                      --------------------------
                     |     1      | right shift |
                     |     2      | left shift  |
                     |     4      | Control     |
                     |     8      | Alt         |
                      --------------------------

If a bit equals 0 then the button is up, and if 1 pressed down.

--------------------------------------------------------------------------
                            Scrap Directory
--------------------------------------------------------------------------

SUB scrp_read *
	Syntax: scrp_read directory_name$
	
Reads the current scrap directory into the string variable 
DIRECTORY_NAME$.

SUB scrp_write *
	Syntax: scrp_write directory_name$
	
Sets the scrap directory to DIRECTORY_NAME$.

--------------------------------------------------------------------------
                            File Selector
--------------------------------------------------------------------------


SUB fsel_input
	Syntax: ok=0 : fsel_input path$,name$,varptr(ok)

Brings up the GEM fileselector, or another replacement one such as 
Selectric.

PATH$ contains the path. PATH$ should be *128* characters long, this 
is the Atari defined maximum.

path$="C:\STOS\*.EX?"+string$(chr$(0),115)

This will have 115 zeros on the end, plenty of space for folders. 
Remember to put a chr$(0) on the end if not using the above method! 
PATH$ after the call will contain the path of the file, so it's 
modified. PATH$ should be *valid*, and have a file mask.

NAME$ will contain the name of the file selected. It can contain a 
name at the start, which like with Selectric, is automatically found 
and highlighted for you. You'll have to make sure that the string is 
13 characters long, even though it shouldn't matter if it's longer, 
but you will be wasting memory:

name$="GEMMA.EXZ"+string$(chr$(0),4)

OK is a address to which will contain the status of the fileselector, 
ie if the 'ok' or 'cancel' button was pressed. This should be four 
bytes long. OK will contain will be 0 if canceled, 1 if ok pressed.

SUB fsel_exinput
	Syntax: ok=0 : fsel_exinput path$, name$, varptr(ok), prompt$

In the second filselector (which was added in the AES v1.3 - Rainbow 
TOS) the PROMT$ string contains a message when the selector appears:

promt$="Please select file to view..."+chr$(0)

PROMT$ should be null terminated, as above, for example. It should 
also be less than 30 characters long.

The PROMT$ will not change after the command has been issued.

--------------------------------------------------------------------------
                                Windows
--------------------------------------------------------------------------

FUNCTION wind_create
	Syntax: id=wind_create (kind, x, y, w, h)
	
This creates a window with the maximum size given by the rectangle of 
width W and height H with top left X,Y, and returns the handle (id in 
the syntax) for later window commands. NB: A negitive number is 
returned if no windows and available.

KIND is a number which relates to the type of window used, multiple 
types can be used:

            -------------------------------------------------
           | KIND |   Name  | Function                       |
            -------------------------------------------------
           |  1   | NAME    | Title bar with name            |
           |  2   | CLOSE   | Close box                      |
           |  4   | FULL    | Full box                       |
           |  8   | MOVE    | Can be moved                   |
           |  16  | INFO    | Information line (below title) |
           |  32  | SIZE    | Sizer box                      |
           |  64  | UPARROW | Upwards arrow                  |
           | 128  | DNARROW | Down arrow                     |
           | 256  | VSLIDE  | Vertical slider                |
           | 512  | FLARROW | Left arrow                     |
           | 1024 | RTARROW | Right arrow                    |
           | 2046 | HSLIDE  | Horizontal slider              |
            -------------------------------------------------

This call DOES NOT display the window. The window SHOULD be deleted 
before your program quits.

SUB wind_open *
	Syntax: wind_open handle, x, y, w, h
	
Displays the window number HANDLE at the position of X,Y, with width W 
and height H.

FUNCTION wind_close
	Syntax: wind_close (handle)
	
Closes the window number HANDLE. The window is not deleted, and can be 
shown again using wind_open.

Returns 0 if there was an error, 1 otherwise.

SUB wind_delete *
	Syntax: wind_delete handle
	
Deletes the window number HANDLE. Memory from this window is freed, if 
window is displayed, you MUST close it using wind_close first.

SUB wind_get *
	Syntax: wind_get handle, sort, varptr(x), varptr(y), 
	varptr(w), varptr(h)
	
This returns information on the window number HANDLE, depending on 
what SORT is.

NB: X, Y, W and H mosty are the information from commands which return 
co-ordinates.

 --------------------------------------------------------------------
| SORT |   Name   |                  Function                        |
 --------------------------------------------------------------------
|  4   | WORKXYWH | the current work area of the window is returned. |
|  5   | CURRXYWH | the current size of the window including borders.|
|  6   | PREVXYWH | the co-ordinates of the previous window inlcuding| 
|      |          | borders.                                         |
|  7   | FULLXYWH | the maximum size of the current window including |
|      |          | borders                                          |
|  8   |  HSLIDE  | x will contain the current position of the       |
|      |          | horizontal slider (between 1 and 1000 - 1 being  | 
|      |          | the left most position).                         |
|  9   |  VSLIDE  | x will contain the current position of the       |
|      |          | vertical slider between 1 and 1000 - 1 being the |
|      |          | top most position.                               |
|  10  |   TOP    | x will contain the handle of the top (active)    |
|      |          | window.                                          |
|  11  | FIRSTXYWH| the co-ordinates of the first rectangle in the   |
|      |          | window's rectangle list.                         |
|  12  | NEXTXYWH | the co-ordinates of the next rectangle in the    |
|      |          | window's rectangle list.                         |
|  15  | HSLSIZE  | x contains the size of the horizontal slider     |
|      |          | relative to the horizontal scrool bar (1 to 1000)| 
|      |          | or -1 if the default square box.                 |
|  16  | VSLSIZE  | x contains the size of the vertical slider       |
|      |          | relative to the vertical scroll bar (1 to 1000)  |
|      |          | or -1 if the default square box.                 |
|  17  |  SCREEN  | x and y give the address of the internal to the  |
|      |          | AES alert buffer and w and h give the length of  |
|      |          | this buffer, x and w are the most significant    |
|      |          | words.                                           |
 --------------------------------------------------------------------
 
SUB wind_set *
	Syntax: wind_set handle, sort, x, y, w, h
	
Sets various attributes of the window HANDLE according to SORT. The 
following values of soft are the same as wind_get: CURRXYWH, HSLIDE, 
VSLIDE, TOP, HSLSIZE, VSLSIZE. In attition:

 -------------------------------------------------------------------
| SORT |   Name  |                  Function                        |
 -------------------------------------------------------------------
|  2   |   NAME  | x, y are the address of the name of the window.  |
|      |         | x is the most signficant word of the address.    |
|  3   |   INFO  | x,y are the address of the text in the           |
|      |         | information line of the window. x is the most    |
|      |         | significant word of the address.                 |
|  14  | NEWDESK | x,y are the address of an object tree containing | 
|      |         | the new GEM desktop for the AES to draw. w is    |
|      |         | the first object to draw in the tree. If x and y |
|      |         | are both 0 then the desktop is reset to the      |
|      |         | default one.                                     |
 -------------------------------------------------------------------

Be careful when passing strings to the AES using NAME and INFO as 
above, because these are not copied by the AES, so if the STOS program 
moves, the window names will be changed too.

Eg

...
60 A$=" Window title "+chr$(0)
70 A=vaprtr(A$)
80 A1=deek (varptr(A)) : A2=deek (varptr(A)+2)
90 wind_set H,2,A1,A2,0,0
...

Note that for name and info, the string should be null terminated.

FUNCTION wind_find
	Syntax: handle=wind_find (x, y)
	
Returns the handle of which window is under the co-ordinate X,Y. 0 is 
returned if there is no window under X,Y.

SUB wind_update *
	Syntax: wind_update sort
	
This can stop the user using menu, moving windows etc. whilst the 
application is outputting to the screen - or when it wants to do its 
own tracking of the mouse:

 ------------------------------------------------------------------
|  SORT |   Name     | Function                                    |
 ------------------------------------------------------------------
|   0   | END_UPDATE | tells the Operating System the windows have |
|       |            | been updated and the user may continue. This|
|       |            | should be called after BEG_UPDATE.          |
|   1   | BEG_UPDATE | tells the Operating System the window will  |
|       |            | be updated. This should be called before    |
|       |            | writing to a window with the AES.           |
|   2   | END_MCTRL  | tells the Operating System the application  |
|       |            | has finished doing its own mouse control,   |
|       |            | and the user can select thing again. Must   |
|       |            | be called after BEG_MCTRL.                  |
|   3   | BEG_MCTRL  | tells the Operating System that application | 
|       |            | is doing its own mouse control, and not let |
|       |            | the user click on any ull down menus or     |
|       |            | windows                                     |
 ------------------------------------------------------------------

FUNCTION wind_calc
	Syntax: error=wind_calc (type, kind, x, y, w, h, varptr(xout), 
			varptr(yout), varptr(wout), varptr(hout))

Calculates the work area of a window, which the command puts in XOUT, 
YOUT, WOUT and HOUT given a border X, Y, W, H and the sort of window 
KIND if TYPE=1. If TYPE=0 then the border area is calculated given the 
work area. KIND is defined under wind_create. Returns 0 if there was 
an error, 1 otherwise.

SUB wind_new
	Syntax: wind_new
	
Closes and deletes all windows, flushes all window buffers and returns 
to standard mouse usage.

This call is only available on the AES v1.3 (Rainbow TOS) and above, 
so no, you can't use it in all your programs... ;-)

--------------------------------------------------------------------------
                             Resource Files
--------------------------------------------------------------------------
	
FUNCTION rsrc_load
	Syntax: error=rsrc_load (file_name$)
	
Loads the resource file names FILE_NAME$ into memory. The filename 
should be null terminated. Returns 0 if there was an error, non-zero 
otherwise.

SUB rsrc_free *
	Syntax: rsrc_free
	
Frees the memory used by rsrc_load.

FUNCTION rsrc_gaddr *
	Syntax: address=rsrc_gaddr (type, index)

(This function differs from the Atari standard, since the result is 
the address of the object/tree.)

Returns the address of a type of data structure from the loaded 
resource via rsrc_load in ADDR. INDEX is the index of the data 
structure and TYPE is one of the following:

 -------------------------------------------------------------------
| TYPE |    Name    | Comments                                      |
 -------------------------------------------------------------------
|   0  |   Tree     |                                               |
|   1  |   OJECT    |                                               |
|   2  |  TEDINFO   |                                               |
|   3  |  ICONBLK   |                                               |
|   4  |   BITBLK   |                                               |
|   5  |  string    |                                               |
|   6  | image data |                                               |
|   7  |  ob_spec   |                                               |
|   8  | te_ptext   |                                               |
|   9  | te_ptmplt  |                                               |
|  10  | te_pvalid  |                                               |
|  11  | ib_pmask   |                                               |
|  12  | ib_pdata   |                                               |
|  13  | ib_ptext   |                                               |
|  14  | bi_pdata   |                                               |
|  15  | ad_frstr   | the address of a pointer to a free string (i.e| 
|      |            | with INDIRECT set in its ob_flags field).     |
|  16  | ad_frimg   | the address if a pointer to a free image (i.e |
|      |            | with INDIRECT set in its ob_flags field).     |
 -------------------------------------------------------------------

SUB rsrc_saddr *
	Syntax: rsrc_saddr type, index, varptr(addr)
	
Finds the address of free string or image given TYPE and INDEX. TYPE 
must be 15 or 16. The address is put into ADDR.

SUB rsrc_obfix
	Syntax: rsrc_obfix tree, object
	
Converts the OBJECT in TREE location from character co-ordinates to 
pixel co-ordinates. This is automatically performed by rsrc_load.

FUNCTION rsrc_rcfix

<a name=rsrcrcfix2><H3>rsrc_rcfix()</H3>

<P>
<B>WORD rsrc_rcfix( <I>rc_header</I> )</B>
<P>
<B>VOID *<I>rc_header</I>;</B>
<TABLE BORDER=1>

<TR><TH></TH><TD><B>rsrc_rcfix()</B> fixes up coordinates and memory pointers of raw resource data in memory. 
</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Opcode</B></TH><TD>115 (0x73)</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Availability</B></TH><TD>Available only in <B>AES</B> versions 4.0 and greater. The presence of this call should also be checked for using <B>appl_getinfo()</B>.
</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Parameters</B></TH><TD><I>rc_header</I> is a pointer to an Atari Resource Construction Set (or compatible) resource file header in memory.
</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Binding</B></TH><TD>
<PRE>
addrin[0] = rc_header;

return crys_if(0x73);
</PRE>

</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Return Value</B></TH><TD><B>rsrc_rcfix()</B> returns a non-zero if successful or zero otherwise.
</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>Comments</B></TH><TD>If a resource has already been loaded with <B>rsrc_load()</B> it must be freed by <B>rsrc_free()</B> prior to this call. In addition, resources identified with this call must likewise be freed before program termination or another resource file is needed.
</TD></TR>

<TR><TH></TH><TD></TD></TR>

<TR><TH><B>See Also</B></TH><TD><B>rsrc_obfix()</B></TD></TR>

</TABLE>

<P>

<HR>

--------------------------------------------------------------------------
                               Shell Routines
--------------------------------------------------------------------------

SUB shel_read *
	Syntax: shel_read cmd$, tail$
	
Gets the file that the application was loaded from in CMD$, with the 
command line tail in TAIL$.

Make sure there is 13 bytes for the filename and plenty of space for 
the command line:

10 CMD$=string$(chr$(0),13)
20 TAIL$=string$(chr$0),50)
30 shel_read CMD$,TAIL$

FUNCTION shel_find
	Syntax: error=shel_find (file$)

Searches for a file named FILE$ (which must be null terminated) in the 
current directory and the search path and returns this directory in 
FILE$, so it's modified by the call. FILE$ should then be a long 
string to cope with the path.

Returns 0 if there was an error, non-zero otherwise.

FUNTION shel_get *
	Syntax: dummy=shel_get (buff, length)
	
Reads the AES's internal shell buffer (a RAM version of the 
DESKTOP.INF or NEWDESK.INF) in the buffer at BUFF, and LENGTH bytes 
will be read. This buffer should be at least 4192 bytes long to 
accommodate for TOS version later than AES version 1.40 (Rainbow TOS).

SUB shel_put
	Syntax: shel_put buff, length
	
This does the opposite to the above command. BUFF is where the data 
is, and LENGTH says how many bytes should go to the AES buffer. If you 
write a new buffer to the AES, there must be a single Control-Z (26 
decimal) to indicate the end of buffer.

FUNCTION shel_write
	Syntax: dummy=shel_write (ex, gr, over, commandname$, 
		      commandline$)

After this program has finished another is executed. EX and OVER must 
be 1 in all current version of the operation system. If GR=0 then the 
program will be ran as a TOS (or TTP) program, and 1 for a GEM program 
(PRG, APP etc.).

COMMANDNAME$ is the complete filename (null terminated) of the program 
to be ran. COMMANDLINE$ specifies (null terminated) the command tail.

SUB shel_envrn
	Syntax: shel_envrn env$, name$
	
Seaches the GEMDOS environment string for a variable and puts the 
result in ENV$. ENV$ must be quite long then. NAME$ should include the 
"=" sign. However, you cannot set the variables this way.

The VDI commands
----------------

--------------------------------------------------------------------------
                          Drawing Primitives
--------------------------------------------------------------------------

FUNCTION v_bar *
	Syntax: dummy=v_bar (x1, y1, x2, y2)

This draws a rectangle and fills it in. The rectangle's co-ordinates 
being X1,Y1 to X2,Y2. Note that if you want to use this with GEM (for 
example filling in a blank window) that v_bar's last parameters use X 
and Y, not W and H like GEM. 

You can calculate W and H into X and Y by adding X1 to your Width, and 
putting this variable as X2, and adding Y1 to Height and putting this 
as Y2.

--------------------------------------------------------------------------
                              Attributes
--------------------------------------------------------------------------

SUB vsf_interior
	Syntax: svf_interior (fill_interior)
	
This sets the fill pattern to what FILL_INTERIOR is:

                     -----------------------------
                    | Style | Effect              |
                     -----------------------------
                    |   0   | Hollow              |
                    |   1   | Solid               |
                    |   2   | Pattern             |
                    |   3   | Hatch               |
                    |   4   | User-defined style  |
                     -----------------------------

Use vsf_style for fill type 2 and 3. The default pattern is the Atari 
logo.
 
FUNCTION vsf_color *
	Syntax: dummy=vsf_colr (colour)
	
This sets the fill colour to COLOUR. Note that the name is different 
to the Atari standard.

--------------------------------------------------------------------------
                      Mouse & Keyboard State Functions
--------------------------------------------------------------------------

FUNCTION v_show_c *
	Syntax: dummy=v_show_c
	
This VDI command will display the mouse. If you have removed the mouse 
x number of times before, you will need to call this x number of 
times. Use this instead of graf_mouse for displaying/removing the 
mouse.

SUB v_hide_c
	Syntax: v_hide_c
	
Removes the mouse from the screen, unless v_show_c has been called x 
number of times, in which case this routines should be called x times 
to remove the pointer.

Misc. commands
--------------

FUNCTION gemmaver$
	Syntax: ver$=gemmaver$
                                                                    
This function returns the current GEMMA version in VER$.

Check ALERGRAF.ASC for an example of alertboxes, gemmaver$, graf_growbox 
and graf_shrinkbox.

