******************************* HeliOS GADGET accessory library ******************************* ------------------------------ HeliOS gadget library routines ------------------------------ Here is the list of functions in the HeliOS Gadget Library, with library call numbers and stack diagrams. See below for documentation on each function. GADGETS 0 GWIN(l),G#(w),GADGLIST(l) - - - GADGLIST(l) GADGET 1 G#(w),GADGLIST(l) - - - GADGLIST(l) ADDGADGET 2 G#(w),GADGLIST(l) - - - REMGADGET 3 G#(w),GADGLIST(l) - - - MOVEGADGET 4 X,Y,W,H,G#(w),GADGLIST(l) - - - GVECTOR 5 G#(w),GADGLIST(l) - - - GVECTPTR(l) GKEY 6 G#(w),GADGLIST(l) - - - GKEYPTR(l) ALLOFF 7 GADGLIST(l) - - - ALLON 8 GADGLIST(l) - - - INITGADS 9 GADGLIST(l) - - - RESETGADS 10 GADGLIST(l) - - - RELINKGADS 11 GADGLIST(l) - - - INSTALLGLIST 12 GWIN(l),GADGLIST(l) - - - REMOVEGLIST 13 GADGLIST(l) - - - SWAPGLIST 14 GWIN(l),GADGLISTNEW(l),GADGLISTOLD(l) - - - LINKGLIST 15 GWIN(l),GADGLIST(l) - - - UNLINKGLIST 16 GADGLIST(l) - - - SWAPLINKGLIST 17 GWIN(l),GADGLISTNEW(l),GADGLISTOLD(l) - - - MAKEPROP 18 PINF(l),G#(w),GADGLIST(l) - - - MAKESTRING 19 STRING(l),SINF(l),G#(w),GADGLIST(l) - - - MAKELONGINT 20 PRES(l),SINF(l),G#(w),GADGLIST(l) - - - MAKEBOOL 21 G#(w),GADGLIST(l) - - - MAKEPROPINFO 22 BODY(w),FLAG(w) [hor=1,vert=0] - - - PROPINFO(l) MAKESTRINGINFO 23 CHAR#(w) - - - STRINFO(l) GETPROPPOT 24 G#(w),GADGLIST(l) - - - PROPPOT(w) SIZESLIDER 25 PART(w),FULL(w),G#(w),GADGLIST(l) - - - GETSTRING 26 G#(w),GADGLIST(l) - - - STRING(l) KEYCHECK 27 GADGLIST(l) - - - GADGACT 28 GADGLIST(l) - - - REFRESHGLIST 29 GADGLIST(l) - - - MOVESLIDER 30 HPOT(w),VPOT(w),G#(w),GADGLIST(l) - - - INPUTACT 31 GADGLIST(l) KEY(w) - - - SETPIX 32 PIXMODE(w) - - - RENDERDISPLAY 33 DISPLAYSTRUCTURE(l) - - - CLEARDUMMY 34 - - - DRAWDUMMY 35 - - - SETBOX 36 0., or VARIOUS.... - - - SETIMAGE 37 0., or VARIOUS.... - - - SETTEXT 38 0., or VARIOUS.... - - - SETBORDER 39 0., or VARIOUS.... - - - PLACEGADGET 40 X,Y,W,H,G#(w),GADGLIST(l) - - - ADDGADGETNOREF 41 G#(w),GADGLIST(l) - - - MOVEGADGETNOREF 42 X,Y,W,H,G#(w),GADGLIST(l) - - - GMCVECTOR 43 G#(w),GADGLIST(l) - - - GMCVECTPTR(l) KEYACTION 44 GADGLIST(l), INPUTCODE(w) - - - INPUTCODE(w) Note: The names of the routines are for reference in this documentation only, and are NOT used as HeliOS Words. The routines are all called by using the KeyWord GADGETLIB along with the routine number. ************************************************************************* ---------------- HeliOS GadgetLib ---------------- This library of routines implements several useful functions for handling Intuition gadgets and performing gadget imagery rendering. -------------------------------------- Calling HeliOS GADGET Library routines -------------------------------------- As with all HelIOS internal libraries, each GADGET library routine has an associated reference number. In this documentation the functions are all given names for ease of reference, but you must remember that the names used here are NOT HeliOS command names, and all these functions are accessed from HeliOS by their library number alone. To call any routine simply use the command GADGETLIB preceded by the reference number of the routine you want to call. The calling parameters for any routine should be placed on the stack immediately before the reference number of the routine. For example, ADDGADGET is routine number "2" in the HeliOS GADGET library, and requires the following parameters: ADDGADGET ( GADGET(w), GADGLIST(l) - - - ) where GADGET is the number of the gadget you want to add, and GADGLIST is a pointer to a GADGETLIST. So, to call ADDGADGET you simply say: GADGET GADGLIST 2 GADGETLIB which expression is constructed as follows: GADGET GADGLIST 2 GADGETLIB ^^^^^^^^^^^^^^^ ^ ^^^^^^^^^ Parameters Routine number HeliOS internal library call ------------------------------- The HeliOS GADGETLIST structure ------------------------------- Most of the routines in this library work by manipulating a "list" of GADGET structures which we will refer to as a GADGETLIST. A GADGETLIST is a linked set of Intuition gadget structures with each gadget structure having additional fields specifying: a HeliOS command word CFA execution-vector 2 bytes a command key store 1 byte a flag store 1 byte a machine code execution-vector 4 bytes a reserved field used internally by HeliOS 4 bytes So each HeliOS GADGET structure = 56 bytes 44 bytes for the Intuition Gadget structure + bytes 45/46 = GADGET VECTOR + byte 47 = COMMAND KEY + byte 48 = STATUS FLAG + bytes 49-52 = M/C VECTOR + bytes 53-56 = RESERVED In other words: The size of an Intuition gadget structure = 44 bytes HeliOS gadgets have extra fields: Gadget Vector offset = 44 Command Key offset = 46 Status Flag offset = 47 M/C Vector offset = 48 Reserved offset = 52 So the size of a HeliOS gadget structure = 56 bytes The GADGETLIST itself has a small header specifying the number of gadgets in the list and the window to which the list is attached (if any). GADGETLIST header: Window pointer 4 bytes Number of Gadgets 2 bytes So the first gadget starts after the header at an offset of 6 bytes. WINDOW -> GADGETLIST + 0 (l) GADGET# -> GADGETLIST + 4 (w) 1st GADGET = GADGETLIST + 6 Gadget numbering within a GADGETLIST goes from 1 to GMAX# ------------------------- Installing HeliOS Gadgets ------------------------- There are two main strategies for setting up GADGETLISTS: -------- Method 1 -------- The first strategy is to set up a GADGETLIST, attach it to a window, switch in and out, or modify, individual gadgets, then detach the list complete in its current state. In this case the attachment and detachment routines do not alter the actual gadget data or SPECINFO allocations. This method allows complete initialised gadget lists to be transferred from window to window. For this method use LINKGLIST, SWAPLINKGLIST and UNLINKGLIST -------- Method 2 -------- The second strategy is to attach and detach gadget lists undefined but "complete", with the attachment procedure automatically setting all gadgets to BOOLEAN and relinking the whole list as initially created. After installation all gadgets will be linked into the window and switched off ready for individual setting up. Any extra SPECINFO structures still attached to an old list which is being re-attached will be de-allocated automatically. You must set up any new SPECINFOS etc which you require AFTER installing the GLIST. This method requires initialisation of gadget lists after installation. For this method use INSTALLGLIST, SWAPGLIST and REMOVEGLIST ------------------------------- HeliOS Gadget Graphic Rendering ------------------------------- HeliOS does not generally make use if Intuition graphic rendering routines, although you can easily use these with HeliOS gadgets if you want to do so. HeliOS has its own powerful graphic rendering functions which allow you to build structured graphical routines for comprehensive gadget imagery and other "rectangular " graphics. HeliOS graphic routines can be preset to work with "tall" or "square" aspect ratio pixels. These two options allow "bevel boxes" to be drawn correctly in different display modes. The graphical routines allow virtually any complex display including text, rectangular areas, and bevel boxes to be created and associated with linked structures which support positional relativity. The use of linked display structures with relative coordinates allows predefined displays to be rendered with with a single function call, and graphics can easily be repositioned in groups. These routines replace all "drawing" parameters in the target RastPort when they exit, and are generally very "clean and tidy": they do not in any way conflict with Intuition or any other Amiga system routines. The highest level HeliOS graphic rendering control structure is the DISPLAYSTRUCT, and several of these can be linked together and then rendered in one very efficient function. Each DISPLAYSTRUCT controls sub-linked-lists of BOXSTRUCT, IMAGESTRUCT, TEXTSTRUCT, and BORDERSTRUCT types. All sub-elements not only have their own position coordinates, but also take relative offsets from the DISPLAYSTRUCT structure which spawned them. This feature allows excellent relocatability of display elements. The TEXT and BORDER operations are rather like the INTUITION ones, but more efficient and powerful. The BEVEL BOX operation is rather interesting, and worthy of special discussion here. Each individual bevel box structure rendering routine draws: 1. An optional monochrome box outline in a chosen colour. 2. An optional bevel box with sides of two chosen colours, and of definable "bevel-wall" width. 3. An optional inner rectangular area with chosen colour, which can also have an optional outline of any chosen colour. 4. The inner rectangle has totally definable left, right, top, and bottom offsets, for totally flexible adjustment. So, in one call, and one control structure, you can render something quite complex like this: "A single pixel black outlined bevel box with background filled centre and dark/light shaded bevels, with an additional white text box with a black outline positioned within the main box." The IMAGE operator uses BltBitMap to blit between a source BitMap and the target RastPort's BitMap. All parameters to BltBitMap are definable. -------------------------- The DUMMY display routines -------------------------- To save your having to allocate structures for simple graphic renders HeliOS provides one example of each structure pre-allocated and pre- linked together. These are referred to as the "DUMMY" graphic rendering structures, and there is a set of rendering routines which set up these structures to do quick rendering of a single display. These routines are very useful for rendering any single graphic element because you can simply call a routine with parameters to define the graphic required, then call the DRAWDUMMY function. You do not need to bother with allocating structures at all. --------------------------------- The display structure definitions --------------------------------- Here are the graphic rendering structure definitions: DISPLAYSTRUCT = 28 bytes 0 NextDisplay(l) Pointer to next DISPLAYSTRUCT 4 RastPort(l) Pointer to target RastPort 8 FirstBox(l) Pointer to first BOX structure 12 FirstImage(l) Pointer to first IMAGE structure 16 FirstText(l) Pointer to first TEXT structure 20 FirstBorder(l) Pointer to first BORDER structure 24 LeftEdge(w) Origin X pixel position 26 TopEdge(w) Origin Y pixel position BOXSTRUCT = 32 bytes 0 NextBox(l) Pointer to next BOX structure 4 LeftEdge(w) Left edge box offset 6 TopEdge(w) Top edge box offset 8 Width(w) Box width 10 Height(w) Box height 12 HiPen(w) Highlight bevel colour 14 LoPen(w) LowLight bevel colour 16 Outline Colour(w) Outline colour (-1 = No Outline) 18 Bevel Width(w) Bevel pixel width (-1 = No Bevel) 20 InnerRectColour(w) Inner rect. colour (-1 = No Inner Rect) 22 InnerRectOutColour(w) Inner rect. outline col (-1 = No Outline) 24 InnerRect X-Inset -> (w) Inner rectangle left edge inset 26 InnerRect X-Inset <- (w) Inner rectangle right edge inset 28 InnerRect Y-Inset ^ (w) Inner rectangle lower edge inset 30 InnerRect Y-Inset Down (w) Inner rectangle upper edge inset IMAGESTRUCT = 22 bytes 0 NextImage(l) Pointer to next IMAGE structure 4 SrcLeftEdge(w) Image source left edge 6 SrcTopEdge(w) Image source top edge 8 TgtLeftEdge(w) Image target left edge 10 TgtTopEdge(w) Image target top edge 12 Width(w) Image width 14 Height(w) Image height 16 Minterm(b) Blitter minterm 17 Mask(b) Plane mask 18 SrcBmap(l) Source bitmap pointer TEXTSTRUCT = 20 bytes 0 FPen(b) Text foreground pen colour 1 BPen(b) Text background pen colour 2 DrMode(b) Text draw mode 3 Kludge(b) Spare 4 LeftEdge(w) Text left edge 6 TopEdge(w) Text top edge 8 Font(l) Pointer to font 12 Text(l) Pointer to (uncounted) text string 16 NextText(l) Pointer to next TEXT structure BORDERSTRUCT = 16 bytes 0 LeftEdge(w) Border left edge 2 TopEdge(w) Border top edge 4 FPen(b) Border foreground pen 5 BPen(b) Border background pen 6 DrMode(b) Border draw mode 7 Count(b) Border coordinate count 8 Coords(l) Coordinate array pointer 12 NextBorder(l) Pointer to next border structure *************************************************************************** ************************************************ A detailed description of the GADGETLIB routines ************************************************ Below is a detailed description of all the GADGETLIB routines. At the start of each description is the routine number followed by the documentation name for the function. **************************************************************************** [ 0 ] ------- GADGETS ( GWIN(l), G#(w), GADGLIST(l) - - - GADGLIST(l) ) ------- Where: GWIN = Pointer to window structure for new gadgets, or null G# = Number of new gadgets to create GADGLIST = Pointer to old gadget list for removal, or null This is a versatile "universal" gadget setup and removal function. It sets up, adjusts, and/or removes a complete GADGETLIST structure for a specified number of gadgets. The behaviour of GADGETS depends on the calling parameters, as follows: If GADGLIST <> 0 In this case GADGLIST is assumed to be a GADGETLIST in use, and GADGETS will: 1. Remove the gadget list from its window 2. Deallocate the gadget list memory If GADGLIST = 0 Nothing is removed If G# <> 0 A GADGETLIST is created, containing G# gadgets. If G# = 0 Nothing is created If GWIN = 0 The new gadget list is left unattached If GWIN <> 0 The new gadget list is attached to the specified window and all gadgets are switched off GADGETS returns a pointer to the new GADGETLIST if one is successfully created, or null in all other circumstances. -------- Examples -------- : OPENGADGETS 0. GADGET# 0. 0 GADGETLIB GADGLIST D! ; ^^ ^^^^^^^ ^^ ^^^^^^^^^^^ No Number of No Store new window new gadgets deallocation list pointer This will simply allocate and initialise a new gadget list with GADGET# gadgets, which you can later attach to any window. : CLOSEGADGETS 0. 0 GADGLIST D@ 0 GADGETLIB DDROP ; ^^ ^ ^^^^^^^^^^^ No No gadgets Gadget list window to create to deallocate This will simply deallocate the gadget list stored in GADGLIST. **************************************************************************** [ 1 ] ------ GADGET ( GADGET(w), GADGLIST(l) - - - GADGET(l) ) ------ Where: GADGET = Number of gadget required GADGLIST = Pointer to GADGETLIST This function: * Returns a pointer to the gadget structure for gadget number supplied **************************************************************************** [ 2 ] --------- ADDGADGET ( GADGET(w), GADGLIST(l) - - - ) --------- Where: GADGET = Number of gadget to activate GADGLIST = Pointer to GADGETLIST in use This function: * Switches on a gadget, making it active under Intuition control * Does not affect gadget settings * Performs an Intuition RefreshGlist function on all non-boolean gadgets. See also ADDGADGETNOREF **************************************************************************** [ 3 ] --------- REMGADGET ( GADGET(w), GADGLIST(l) - - - ) --------- Where: GADGET = Number of gadget to de-activate GADGLIST = Pointer to GADGETLIST in use This function: * Switches off a gadget, making it inactive under Intuition control * Does not affect gadget settings **************************************************************************** [ 4 ] ---------- MOVEGADGET ( X(w), Y(w), WID(w), HGT(w), GADGET(w), GADGLIST(l) - - - ) ---------- Where: X = Gadget top left corner X pixel position Y = Gadget top left corner Y pixel position WID = Gadget pixel width HGT = Gadget pixel height GADGET = Number of gadget to position GADGLIST = Pointer to GADGETLIST in use This function: * Sets up gadget dimension and position parameters * Switches on a gadget, making it active under Intuition control * Performs an Intuition RefreshGlist function on all non-boolean gadgets. See also MOVEGADGETNOREF and PLACEGADGET **************************************************************************** [ 5 ] ------- GVECTOR ( GADGET(w), GADGLIST(l) - - - GVECTPTR(l) ) ------- Where: GADGET = Number of gadget to activate GADGLIST = Pointer to GADGETLIST in use GVECTPTR = Pointer to HeliOS command CFA This function: * Returns 32-bit pointer to gadget field containing the CFA of the HeliOS command which is executed when the gadget is activated. **************************************************************************** [ 6 ] ---- GKEY ( GADGET(w), GADGLIST(l) - - - GKEYPTR(l) ) ---- Where: GADGET = Number of gadget to activate GADGLIST = Pointer to GADGETLIST in use GKEYPTR = Pointer to gadget shortcut key field This function: * Returns 32-bit pointer to gadget field containing the ASCII code of the keypress which activates the gadget **************************************************************************** [ 7 ] ------ ALLOFF ( GADGLIST(l) - - - ) ------ Where: GADGLIST = Pointer to GADGETLIST in use This function: * Implements Intuition's "RemoveGadget" routine on all gadgets in a list. * Switches OFF all the gadgets in the specified gadget list * Use this function when gadgets ARE attached to a window **************************************************************************** [ 8 ] ----- ALLON ( GADGLIST(l) - - - ) ----- Where: GADGLIST = Pointer to GADGETLIST in use This function: * Implements Intuition's "AddGadget" routine on all gadgets in a list. * Switches ON all the gadgets in the specified gadget list * Use this function when gadgets ARE attached to a window **************************************************************************** [ 9 ] -------- INITGADS ( GADGLIST(l) - - - ) -------- Where: GADGLIST = Pointer to GADGETLIST to initialise This function: * Initialises gadgets when NOT attached to window * Re-links all gadgets * Resets all gadget fields * Switches all gadgets ON * Deallocates any SPECINFO structures * Sets type of all gadgets to BOOLEAN **************************************************************************** [ 10 ] --------- RESETGADS ( GADGLIST(l) - - - ) --------- Where: GADGLIST = Pointer to GADGETLIST to reset This function: * Is used to initialise gadgets when list IS ALREADY LINKED into window * Switches all gadgets to OFF * Re-links all gadgets * Resets all gadget fields * Deallocates any SPECINFO structures * Sets type of all gadgets to BOOLEAN **************************************************************************** [ 11 ] ---------- RELINKGADS ( GADGLIST(l) - - - ) ---------- Where: GADGLIST = Pointer to GADGETLIST to re-link This function: * Re-links all gadgets into full list * Only alters links **************************************************************************** [ 12 ] ------------ INSTALLGLIST ( GWIN(l), GADGLIST(l) - - - ) ------------ Where: GWIN = Pointer to window structure to receive new gadgets GADGLIST = Pointer to GADGETLIST to install This function: * Removes the gadget list from any previous attachment * Initialises all gadgets and re-links the complete gadget list * Removes and de-allocates any SPECINFO structures already set up as part of the gadget list from any previous application. * Sets all gadgets to BOOLEAN * Resets all gadget dimensions, flags etc. * Switches all gadgets off * Sets the gadget list window pointer to specify the new window * Installs the gadget list into the new window See also SWAPLIST and REMOVEGLIST **************************************************************************** [ 13 ] ----------- REMOVEGLIST ( GADGLIST(l) - - - ) ----------- Where: GADGLIST = Pointer to GADGETLIST to remove This function: * Removes gadget list only if it exists (!) * Sets the gadget list window pointer to null * Relinks and switches ON all gadgets * Re-initialises full gadget list See also SWAPLIST and INSTALLGLIST **************************************************************************** [ 14 ] --------- SWAPGLIST ( GWIN(l), GADGLIST_NEW(l), GADGLIST_OLD(l) - - - ) --------- Where: GWIN = Pointer to window structure to receive new gadgets GADGLIST_NEW = Pointer to GADGETLIST to install GADGLIST_OLD = Pointer to GADGETLIST to remove This function: * Swaps gadget lists attached to window * Sets the new gadget list window pointer to specify the new window * Sets the removed gadget list window pointer to null * Installs the new gadget list into the new window * Initialises all gadgets and re-links both complete gadget lists * Removes and de-allocates any SPECINFO structures already set up as part of the gadget lists from any previous application. * Sets all gadgets to BOOLEAN * Resets all gadget dimensions, flags etc. * Re-links and switches all gadgets OFF in installed gadget list * Re-links and switches all gadgets ON in removed gadget list * Effectively does a REMOVEGLIST and INSTALLGLIST See also REMOVEGLIST and INSTALLGLIST **************************************************************************** [ 15 ] --------- LINKGLIST ( GWIN(l), GADGLIST(l) - - - ) --------- Where: GWIN = Pointer to window structure to receive new gadgets GADGLIST = Pointer to GADGETLIST to link in This function: * Removes the gadget list from any previous attachment * Sets the gadget list window pointer to specify the new window * Links in all gadgets in gadget list * Alters none of the gadget structures * Installs the gadget list into the new window * Switches all gadgets off See also UNLINKGLIST and SWAPLINKGLIST **************************************************************************** [ 16 ] ----------- UNLINKGLIST ( GADGLIST(l) - - - ) ----------- Where: GADGLIST = Pointer to GADGETLIST to unlink This function: * Removes gadget list only if it exists (!) * Sets the gadget list window pointer to null * Relinks and switches ON all gadgets * Does NOT re-initialise gadget list See also LINKGLIST and SWAPLINKGLIST **************************************************************************** [ 17 ] ------------- SWAPLINKGLIST ( GWIN(l), GADGLIST_NEW(l), GADGLIST_OLD(l) - - - ) ------------- Where: GWIN = Pointer to window structure to receive new gadgets GADGLIST_NEW = Pointer to GADGETLIST to install GADGLIST_OLD = Pointer to GADGETLIST to remove This function: * Swaps gadget lists attached to window * Sets the new gadget list window pointer to specify the new window * Sets the removed gadget list window pointer to null * Installs the new gadget list into the new window * Alters none of the gadget structures * Re-links and switches all gadgets OFF in installed gadget list * Re-links and switches all gadgets ON in removed gadget list * Effectively does a UNLINKGLIST and LINKGLIST See also UNLINKGLIST and LINKGLIST **************************************************************************** [ 18 ] -------- MAKEPROP ( PROPINFO(l), GADGET(w), GADGLIST(l) - - - ) -------- Where: PROPINFO = Pointer to a PropInfo structure GADGET = Number of gadget to modify GADGLIST = Pointer to GADGETLIST in use This function: * Sets up the specified gadget to make it a proportional gadget N.B. The HeliOS system automatically initialises a proportional gadget to have an "AutoKnob", and this requires that the "gg_GadgetRender" field of the gadget must point to an "Image" structure. The HeliOS system automatically allocates and initialises all this for you, and this means that you need to be careful not to write into the "gg_GadgetRender" field of the proportional gadget yourself. For example, you should not replace this field with an imagery structure of your own unless you first deallocate the structure provided by HeliOS. Failure to observe this will mean that the image structure provided by HeliOS will be "lost" and its memory will not be deallocated by HeliOS automatic gadget deallocation routines. In general you should not use the "gg_GadgetRender" of a proportional gadget for your own imagery.... **************************************************************************** [ 19 ] ---------- MAKESTRING ( STRING(l), STRINFO(l), GADGET(w), GADGLIST(l) - - - ) ---------- Where: STRING = Pointer to associated (uncounted) string STRINFO = Pointer to a StringInfo structure GADGET = Number of gadget to modify GADGLIST = Pointer to GADGETLIST in use This function: * Sets up the specified gadget to make it a string gadget **************************************************************************** [ 20 ] ----------- MAKELONGINT ( PRESET(l), STRINFO(l), GADGET(w), GADGLIST(l) - - - ) ----------- Where: PRESET = Numeric long integer value to be preset into gadget STRINFO = Pointer to a StringInfo structure GADGET = Number of gadget to modify GADGLIST = Pointer to GADGETLIST in use This function: * Sets up the specified gadget to make it a long integer string gadget **************************************************************************** [ 21 ] -------- MAKEBOOL ( GADGET(w), GADGLIST(l) - - - ) -------- Where: GADGET = Number of gadget to modify GADGLIST = Pointer to GADGETLIST in use This function: * Sets up the specified gadget to make it a Boolean gadget **************************************************************************** [ 22 ] ------------ MAKEPROPINFO ( BODY(w), FLAG(w) - - - PROPINFO(l) ) ------------ Where: BODY = WholeLength/KnobLength FLAG = Select horizontal (=1) or vertical (=0) PROPINFO = Pointer to new PropInfo structure This function: * Allocates a PropInfo structure * Initialises the PropInfo structure as horizontal or vertical **************************************************************************** [ 23 ] -------------- MAKESTRINGINFO ( CHAR#(w) - - - STRINGINFO(l) ) -------------- Where: CHAR# = WholeLength/KnobLength STRINGINFO = Pointer to new StringInfo structure This function: * Allocates a StringInfo structure * Initialises the StringInfo structure to supplied string size **************************************************************************** [ 24 ] ---------- GETPROPPOT ( GADGET(w), GADGLIST(l) - - - PROPPOT(w) ) ---------- Where: GADGET = Number of gadget to test GADGLIST = Pointer to GADGETLIST in use PROPPOT = Proportional gadget "pot" value This function: * Gets the "pot" value of a proportional gadget **************************************************************************** [ 25 ] ---------- SIZESLIDER ( PARTSIZE(w), FULLSIZE(w), GADGET(w), GADGLIST(l) - - - ) ---------- Where: PARTSIZE = Size of proportional partial value FULLSIZE = Size of proportional full value GADGET = Number of gadget to test GADGLIST = Pointer to GADGETLIST in use This function: * Sets PROP gadget knob size **************************************************************************** [ 26 ] --------- GETSTRING ( GADGET(w), GADGLIST(l) - - - STRING(l) ) --------- Where: GADGET = Number of gadget to test GADGLIST = Pointer to GADGETLIST in use STRING = Pointer to string This function: * Returns string gadget's string buffer pointer **************************************************************************** [ 27 ] -------- KEYCHECK ( GADGLIST(l) - - - ) -------- Where: GADGLIST = Pointer to GADGETLIST to check This function: * Waits for ANY user input event (key, gadget, menu etc.) * Converts user input code to lower case if it is an ASCII code * Runs the standard HeliOS key filter routine, which you can set up to perform your own function using KEYFILTER * Checks all gadgets to see if that gadget was activated or an associated gadget command hotkey was pressed * Carries out any HeliOS or machine code functions associated with any activated gadget * Loops around and repeats user input poll until any function returns the value 1030, which is the exit code for KEYCHECK. * KEYCHECK calls command routines with the user input code on the stack, and all functions should NOT affect the stack unless you want to set up exit from the KEYCHECK loop. * KEYCHECK uses GADGACT to perform gadget actions: please read the GADGACT doc and take care over stack parameters when your gadget action code is called for STRING/LONGINT and PROPORTIONAL gadgets. * To set up exit from KEYCHECK you need to DROP the input code from the stack and replace it with the KEYPRESS exit code "1030". **************************************************************************** [ 28 ] ------- GADGACT ( GADGLIST(l) - - - ) ------- Where: GADGLIST = Pointer to GADGETLIST to check This function: * Interprets HeliOS GadgetNumber store * Locates gadget in list associated with current GadgetNumber value * Carries out action appropriate to gadget * BOOLEAN -> Action carried out once * PROPORTIONAL -> Loops while GADGET pressed Puts proportional Pot(w) on stack each time action routine is called, so your action routine must remember to handle and remove this value. * STRING -> Action carried out after GADGET is released Puts String(l) on stack when action routine is called so your action routine must remember to handle and remove this value. * LONG INT STRING -> Action carried out after GADGET is released Puts Long Integer numeric value on stack when action routine is called so your action routine must remember to handle and remove this value. **************************************************************************** [ 29 ] ------------ REFRESHGLIST ( GADGLIST(l) - - - ) ------------ Where: GADGLIST = Pointer to GADGETLIST to refresh This function: * Carries out Intuition RefreshGlist for whole of specified gadget list **************************************************************************** [ 30 ] ---------- MOVESLIDER ( HPOT(w), VPOT(w), GADGET(w), GADGLIST(l) - - - ) ---------- Where: HPOT = Horizontal proportional gadget "pot" value VPOT = Vertical proportional gadget "pot" value GADGET = Number of gadget to modify GADGLIST = Pointer to GADGETLIST in use This function: * Sets proportional gadget knob position **************************************************************************** [ 31 ] -------- INPUTACT ( GADGLIST(l), INPUTCODE(w) - - - ) -------- Where: GADGLIST = Pointer to GADGETLIST to check INPUTCODE = User input code as returned by HeliOS command KEY This function: * This function is rather specialised and you will probably never need to use it: if you do so, take care to read these notes carefully! INPUTACT basically runs a very simple quick gadget interpreter for applications which only operate via a few gadgets and use no hotkeys. There is no key filter provision, and all key presses by the user are routed via a "dummy" gadget number 1. * Processes gadget actions based on INPUTCODE and HeliOS GadgetNumber, in a similar fashion to GADGACT * Gadget 1 has a special function in that it is used as a "dummy" gadget to process all keyboard input via its action fields. Do not use this gadget as an ordinary gadget * If INPUT is a gadget press, uses GadgetNumber to select gadget action * If INPUT is any key press, processes action for gadget number 1 * Does NOT convert user input code to lower case as KEYCHECK does * Does NOT run the standard HeliOS key filter routine as KEYCHECK does * Checks all gadgets to see if that gadget was activated directly, but does not allow hotkey gadget selection * Carries out any HeliOS or machine code functions associated with an activated gadget * Uses GADGACT to perform gadget actions: please read the GADGACT doc and take care over stack parameters when your gadget action code is called for STRING/LONGINT and PROPORTIONAL gadgets. * Does NOT loop **************************************************************************** [ 32 ] ------ SETPIX ( PIXMODE(w) - - - ) ------ Where: PIXMODE = Automatic pixel aspect ratio correction setting This function: * Sets automatic pixel aspect ratio (1=square/lores, 0=tall/hires) **************************************************************************** [ 33 ] ------- DISPLAY ( DISPLAYSTRUCT(l) - - - ) ------- Where: DISPLAYSTRUCT = Pointer to display definition structure This function: * Renders a full set of graphics defined by the display structure **************************************************************************** [ 34 ] ---------- CLEARDUMMY ( - - - ) ---------- This function: * Clears all DUMMY display structures **************************************************************************** [ 35 ] --------- DRAWDUMMY ( - - - ) --------- This function: * Draws DUMMY display **************************************************************************** [ 36 ] ------ SETBOX ( Various [see below] - - - ) ------ With a single 32-bit null value (0.) on stack this routine clears the DUMMY BOX structure. With a full parameter set as defined below this routine sets the parameter values into the DUMMY BOX structure. Here is the full list of stack parameters in the order in which you supply them. This means that when the stack is configured ready for calling this routine the RPort value will be on the top of the stack. LeftEdge(w) TopEdge(w) Width(w) Height(w) HiPen(w) LoPen(w) Outline Colour(w) (-1 = No Outline) Bevel Width(w) (-1 = No Bevel) Inner Rectangle Colour(w) (-1 = No Inner Rectangle) Inner Rectangle Outline Colour(w) (-1 = No Outline) Inner Rectangle X-Inset ->(w) Inner Rectangle X-Inset <-(w) Inner Rectangle Y-Inset ^ (w) Inner Rectangle Y-Inset Down(w) RPort(l) This function: * Sets up the DUMMY BOX structure **************************************************************************** [ 37 ] -------- SETIMAGE ( Various [see below] - - - ) -------- With a single 32-bit null value (0.) on stack this routine clears the DUMMY IMAGE structure. With a full parameter set as defined below this routine sets the parameter values into the DUMMY IMAGE structure. Here is the full list of stack parameters in the order in which you supply them. This means that when the stack is configured ready for calling this routine the RPort value will be on the top of the stack. SrcLeftEdge(w) SrcTopEdge(w) TgtLeftEdge(w) TgtTopEdge(w) Width(w) Height(w) Minterm(w) Mask(w) SrcBmap(l) RPort(l) This function: * Sets up the DUMMY IMAGE structure **************************************************************************** [ 38 ] ------- SETTEXT ( Various [see below] - - - ) ------- With a single 32-bit null value (0.) on stack this routine clears the DUMMY TEXT structure. With a full parameter set as defined below this routine sets the parameter values into the DUMMY TEXT structure. Here is the full list of stack parameters in the order in which you supply them. This means that when the stack is configured ready for calling this routine the RPort value will be on the top of the stack. FPen(w) BPen(w) DrMode(w) LeftEdge(w) TopEdge(w) Font(w) Text(l) RPort(l) This function: * Sets up the DUMMY TEXT structure **************************************************************************** [ 39 ] --------- SETBORDER ( Various [see below] - - - ) --------- With a single 32-bit null value (0.) on stack this routine clears the DUMMY BORDER structure. With a full parameter set as defined below this routine sets the parameter values into the DUMMY BORDER structure. Here is the full list of stack parameters in the order in which you supply them. This means that when the stack is configured ready for calling this routine the RPort value will be on the top of the stack. LEdge(w) TEdge(w) FPen(w) BPen(w) DrMode(w) Count(w) Coords(l) RPort(l) This function: * Sets up the DUMMY BORDER structure **************************************************************************** [ 40 ] ----------- PLACEGADGET ( X(w), Y(w), WID(w), HGT(w), GADGET(w), GADGLIST(l) - - - ) ----------- Where: X = Gadget top left corner X pixel position Y = Gadget top left corner Y pixel position WID = Gadget pixel width HGT = Gadget pixel height GADGET = Number of gadget to position GADGLIST = Pointer to GADGETLIST in use This function: * Sets up gadget dimension and position parameters * Does NOT activate gadget See also MOVEGADGET and MOVEGADGETNOREF **************************************************************************** [ 41 ] -------------- ADDGADGETNOREF ( GADGET(w), GADGLIST(l) - - - ) -------------- Where: GADGET = Number of gadget to activate GADGLIST = Pointer to GADGETLIST in use This function: * Switches on a gadget, making it active under Intuition control * Does not affect gadget settings * Does NOT perform an Intuition RefreshGlist function on ANY gadgets. See also ADDGADGET **************************************************************************** [ 42 ] --------------- MOVEGADGETNOREF ( X(w), Y(w), WID(w), HGT(w), GADGET(w), GADGLIST(l) - - - ) --------------- Where: X = Gadget top left corner X pixel position Y = Gadget top left corner Y pixel position WID = Gadget pixel width HGT = Gadget pixel height GADGET = Number of gadget to position GADGLIST = Pointer to GADGETLIST in use This function: * Sets up gadget dimension and position parameters * Switches on a gadget, making it active under Intuition control * Does NOT perform an Intuition RefreshGlist function on ANY gadgets. See also MOVEGADGET and PLACEGADGET **************************************************************************** [ 43 ] --------- GMCVECTOR ( GADGET(w), GADGLIST(l) - - - GMCVECTPTR(l) ) --------- Where: GADGET = Number of gadget to activate GADGLIST = Pointer to GADGETLIST in use GMCVECTPTR = Pointer to gadget machine code command vector This function: * Returns 32-bit pointer to gadget field containing the pointer to the machine code routine which is executed when the gadget is activated. **************************************************************************** [ 44 ] --------- KEYACTION ( GADGLIST(l), INPUTCODE(w) - - - INPUTCODE(w) ) --------- Where: GADGLIST = Pointer to GADGETLIST to check INPUTCODE = User input code as returned by HeliOS command KEY This function: * Checks all gadgets to see if that gadget was activated or an associated gadget command hotkey was pressed * Converts user input code to lower case if it is an ASCII code * Runs the standard HeliOS key filter routine, which you can set up to perform your own function using KEYFILTER * Carries out any HeliOS or machine code functions associated with any activated gadget KEYACTION calls command routines with the user input code on the stack. *----------------------------------------------------------------------- ************************************************************************