____ ____ ______ /\ _`\ /\ _`\ /'\_/`\ /'\_/`\/\ _ \ 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

rsrc_rcfix()

WORD rsrc_rcfix( rc_header )

VOID *rc_header;
rsrc_rcfix() fixes up coordinates and memory pointers of raw resource data in memory.
Opcode115 (0x73)
AvailabilityAvailable only in AES versions 4.0 and greater. The presence of this call should also be checked for using appl_getinfo().
Parametersrc_header is a pointer to an Atari Resource Construction Set (or compatible) resource file header in memory.
Binding 
addrin[0] = rc_header;

return crys_if(0x73);
Return Valuersrc_rcfix() returns a non-zero if successful or zero otherwise.
CommentsIf a resource has already been loaded with rsrc_load() it must be freed by rsrc_free() prior to this call. In addition, resources identified with this call must likewise be freed before program termination or another resource file is needed.
See Alsorsrc_obfix()

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