# GUMPS.INC help file -v2.2- |
Author: | TJ Houston (Myrathi)
Email: | tjh@myrathi.co.uk

Commands covered in this help file: `(optional parameters are in [ ] brackets)`

F U N C T I O N L I S T | GFSetRef( [x], [y] ) GFSetRefRel( dx, dy ) GFInitGump( [sx], [sy] ) GFPage( page ) GFNoClose( ) GFNoDispose( ) GFNoMove( ) GFExtractData( keyid, keyarray ) GFGetNextIndex( type ) * GFSetNextIndex( type, value ) * GFIncIndex( type ) * GFGetData( index ) * GFSetData( index, text ) * GFGetLayout( index ) * GFSetLayout( index, text ) * | GFGumpPic( x, y, gumpid ) GFResizePic( x, y, gumpid, w, h ) GFTilePic( x, y, tileid ) GFTextLine( x, y, colour, text ) GFTextMid(x, y, w, colour, text ) GFTextRight( rx, y, colour, text ) GFTextCrop( x, y, w, h, colour, text ) GFTextEntry( x, y, w, h, colour, text ) GFButtonPage( x, y, release, press, page ) GFButtonID( x, y, release, press, close ) GFCheckBox( x, y, off, on, state ) GFRadioButton( x, y, off, on, state ) GFSetRadioGroup( group ) GFUser1( line ) GFUser2( l_line, d_pos, d_line )
GFStoreGump( ) GFRestoreGump( gumpvar ) | GFSendGump( who ) GFSendGumpV( who, gumpvar )

Notes:

- This package requires at least core 090 due to its use of the 'struct' type.
- All functions will accept hex values in place of integers and convert them, if necessary, to integer form (gumps crash with hex values! Ugh!)
- Sending negative values to gump functions *will* crash the client!
- Refer to the '`GUMPS.INC`' file for a list of '`BKGND_???????`' constants for use with the GFResizePic( ) function.

(For an example program, see the bottom of this file)

GFSetRef( [x], [y] )
Purpose | Specifies the absolute co-ordinates, from top-left corner of the client window, that any successive controls will use as a reference.
x | Distance in from the left edge of the client-area. (Default: 0)
y | Distance down from the top edge of the client-area. (Default: 0)
Return Value | A structure containing the old absolute reference co-ordinates: `oldref.x oldref.y`
Notes | This can be used more than once within the same gump build to alter the reference-origin. Useful for grouping several controls together from the same point.

GFSetRefRel( dx, dy )
Purpose | Specifies the relative co-ordinates, from the current virtual cursor-position, that any successive controls will use as a reference.
dx | Distance from the current x-position within the client-area. Negative values will move left, instead of right.
dy | Distance from the current y-position within the client-area. Negative values will move upwards, instead of down.
Return Value | A structure containing the old absolute reference co-ordinates: `oldref.x oldref.y`
Notes | This can be used more than once within the same gump build to alter the reference-origin. Useful for placing groups of controls relative to the current origin.

GFInitGump( [sx], [sy] )
Purpose | To initialise the global variables necessary to use GUMPS.INC properly.
sx | Parameter, if given, is sent to GFSetRef( ) as its first parameter. (Default: 0)
sy | Parameter, if given, is sent to GFSetRef( ) as its second parameter. (Default: 0)
Return Value | None.
Notes | Automatically inserts "page 0" into the layout array. You don't need to specify it. Automatically inserts "nodispose" into the layout array. This must be present!

GFPage( page )
Purpose | Specifies that successive controls are to be placed on this page.
page | Page number to use.
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - Page number`
Notes | Use "GFButtonPage( )" to create buttons to flip between pages.

GFNoClose( )
Purpose | Specifies that the Gump cannot be closed by right-clicking on it.
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | Must be closed by pressing an "action button" on one of the pages. This is usually specified directly after initialisation.

GFNoDispose( )
Purpose | Specifies that the Gump cannot be closed by pressing ESCAPE.
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | This MUST be included, otherwise the server is never told the gump has been closed! This is usually specified directly after initialisation.

GFNoMove( )
Purpose | Specifies that the Gump cannot be dragged or moved from it's initial position.
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | This is usually specified directly after initialisation.

GFExtractData( keyid, keyarray )
Purpose | Strips the KeyID prefix ('`nnn:`') from the front of a TextEntry value taken from the specified point in the key-array.
keyid | The element from the `key-array` to use.
keyarray | The array of key-values returned by a gump function (the main return value, NOT the `.keys` member!!)
Return Value | The extracted string.
Notes | The `keyid` specifies both the element of the `keyarray` to extract the string from and the substring ('`nnn:`')that has to be removed from the data to give the final result.

GFGumpPic( x, y, gumpid )
Purpose | Displays a graphic from the "Gumps" section of the InsideUO program on the screen.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
gumppic | ID of the graphic to use (taken from InsideUO)
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | Can be used as a background gump or a control-graphic. Graphic is placed relative to current origin as set by the GFSetRef( ) function.

GFResizePic( x, y, gumpid, w, h )
Purpose | Displays a complex graphic, from the "Gumps" section of the InsideUO program, on the screen by building up the 9 consecutive graphics from #(gumpid) to #(gumpid+8).
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
gumppic | ID of the first of the 9 graphics to use (taken from InsideUO)
w | Total width of the resulting complex-graphic.
h | Total height (down the screen) of the resulting complex-graphic.
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | This is usually used to make up the background graphics for the large majority of Gumps.

GFTilePic( x, y, tileid )
Purpose | Displays a graphic from the "Artwork / Static Tiles" section of the InsideUO program on the screen.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
tileid | ID of the graphic to use (taken from InsideUO)
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | TilePics differ from GumpPics and Resizables in that they use the graphics normally accessed by objects! Be careful if you're switching between GumpPics and TilePics, especially!

GFTextLine( x, y, colour, text )
Purpose | Displays a line of text at a given position and in a given colour, relative to the pre-specified origin.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
colour | Colour of text.
text | Text to display.
Return Value | A structure...
`retv.lytidx retv.dtidx` | `- Layout-array index changed - Data-array index changed (0-based index)`
Notes | This text is static.

GFTextMid( x, y, w, colour, text )
Purpose | Displays a line of text, centred within the region indicated by the leftmost co-ordinates and the width of the region, relative to the pre-specified origin and in a given colour.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
w | Width of the region, relative to the `x` co-ordinate, given.
colour | Colour of text.
text | Text to display.
Return Value | A structure...
`retv.lytidx retv.dtidx` | `- Layout-array index changed - Data-array index changed (0-based index)`
Notes | This text is static.

GFTextRight( rx, y, colour, text )
Purpose | Displays a line of text, right aligned to a given position, in a given colour, relative to the pre-specified origin.
rx | Distance of the right-most edge of the text in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
colour | Colour of text.
text | Text to display.
Return Value | A structure...
`retv.lytidx retv.dtidx` | `- Layout-array index changed - Data-array index changed (0-based index)`
Notes | This text is static.

GFTextCrop( x, y, w, h, colour, text )
Purpose | Display a line of text at a given position and in a given colour, relative to the pre-specified origin, but restricts it to a bounding box.
x | Distance the bounding-box is in from the left edge, relative to the pre-specified origin.
y | Distance the bounding-box is down from the top edge, relative to the pre-specified origin.
w | The width of the bounding box, from the x-position.
h | The height of the bounding box, from the y-position.
colour | Colour of text.
text | Text to display.
Return Value | A structure...
`retv.lytidx retv.dtidx` | `- Layout-array index changed - Data-array index changed (0-based index)`
Notes | This text is static and shows '`...`' if it exceeds the rightmost edge of the bounding box.

GFTextEntry( x, y, w, h, colour, text )
Purpose | Displays a line of text (optional) at a given position and in a given colour, relative to the pre-specified origin which can then be edited by the player and is returned via the keylist (by GFSendGump( ).)
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
w | Width of text-entry area.
h | Height (downwards) of text-entry area.
colour | Colour of text.
text | Text to display.
Return Value | A structure...
`retv.lytidx retv.dtidx retv.keyid` | `- Layout-array index changed - Data-array index changed (0-based index) - KeyID allocated to the text when the Gump returns (This method is DAFT! But hey, I didn't write it! :-P" ) (Returns eg: "Key=2024, Value=2024: This is the text" )`
Notes | Only the text itself is shown... if you want a "background slot" for it to sit in, then you must create it yourself (with GFGumpPic( ), GFResizePic( ) or GFTilePic( ) ) Call GFExtractData( ) with the `retv.keyid` member to extract only the text from the data-array.

GFButtonPage( x, y, release, press, page )
Purpose | Displays a "button" graphic which changes the "page" that the Gump shows.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
release | The Gump graphic ID relating to the "released" state of the button (default position)
press | The Gump graphic ID relating to the "pressed in" state of the button (when the mouse is clicked on it)
page | The page number that the button flicks to.
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - Page number that the button changes to`
Notes | If there is no "pushed in" graphic, then supply the same ID for both release and press. (example: book corner graphics)

GFButtonID( x, y, release, press, close )
Purpose | Displays a "button" graphic which returns a "key value" when pressed.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
release | The Gump graphic ID relating to the "released" state of the button (default position)
press | The Gump graphic ID relating to the "pressed in" state of the button (when the mouse is clicked on it)
close | Does the page close when the button's pressed? (0=No, 1=Yes)
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - KeyID allocated to the button (returned from Gump if pressed) (butid)`
Notes | If there is no "pushed in" graphic, then supply the same ID for both release and press. (example: book corner graphics)

GFCheckBox( x, y, off, on, state )
Purpose | Displays an on/off (yes/no) checkbox which returns its 'state' when the Gump is closed.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
off | The Gump graphic ID relating to the "off/no" state of the checkbox
on | The Gump graphic ID relating to the "on/yes" state of the checkbox
state | Sets the initial state of the checkbox (0=Off/No, 1=On/Yes)
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - KeyID allocated to the checkbox. (cbxid)`
Notes | The state of a checkbox is only returned from the Gump if it's On/Yes; if it's Off/No, then it's not returned.

GFRadioButton( x, y, off, on, state )
Purpose | Displays an on/off (yes/no) radio (option) button which returns its 'state' when the Gump is closed.
x | Distance in from the left edge, relative to the pre-specified origin.
y | Distance down from the top edge, relative to the pre-specified origin.
off | The Gump graphic ID relating to the "off/no" state of the radio-button
on | The Gump graphic ID relating to the "on/yes" state of the radio-button
state | Sets the initial state of the radio-button (0=Off/No, 1=On/Yes)
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - KeyID allocated to the radio-button. (radid)`
Notes | The state of a radio button is only returned from the Gump if it's On/Yes. Only one radio button in a group may be selected! Set up seperate groups of radio buttons with GFSetRadioGroup( ).

GFSetRadioGroup( group )
Purpose | To set which group any future radio-buttons are a part of.
group | The group number
Return Value | A structure...
`retv.lytidx retv.keyid` | `- Layout-array index changed - The group number`
Notes | This has to be used BEFORE the radio buttons are created (default group is 1) I have no idea if the group number is used... tests have been inconclusive. Your call!

GFUser1( line )
Purpose | Appends a user-specified control-line directly onto the end of the layout array.
line | The line of command-text to append
Return Value | A structure...
`retv.lytidx` | `- Layout-array index changed`
Notes | This is not checked for errors! Be careful!

GFUser2( l_line, d_pos, d_line )
Purpose | Appends a user-specified control-line directly onto the end of the layout array and places the other, supplied, text string into the specified location in the data array.
l_line | The line of command-text to append.
d_pos | The position in the data array to place the "text line".
d_line | The text-line to place in the data array.
Return Value | A structure...
`retv.lytidx retv.dtidx` | `- Layout-array index changed - Data-array index changed`
Notes | This is not checked for errors! Be careful!

GFStoreGump( )
Purpose | To store the current gump, that's being worked on, into a structure.
Return Value | A structure that can be sent direct to the GFSendGumpV( ) or GFRestoreGump( ) functions...
`retv.layout retv.data retv.idx` | `- Layout-array - Data-array - Internal index values`
Notes | Store the returned value using something like: `var gump := GFStoreGump( );` Gump Storage-variables can be saved in Global Properties (GProps) :-)

GFRestoreGump( gumpvar )
Purpose | To restore a previously stored gump into the current workspace.
gumpvar | The structure-variable holding the gump details
Return Value | An integer...
`0 1` | `- Failure: Error message printed to console - Success: Gump can be accessed again`
Notes | If you've stored a gump in a variable (using the GFStoreGump( ) function) and need to change the details in it, use this function.

GFSendGump( who )
Purpose | To create and run the gump itself, then return the results to the calling function.
who | The player you want to send the Gump to
Return Value | Returns the exact same type of key-array as the core-function SendDialogGump( ) (see the UO.EM file)
Notes | This function call uses the gump definition that's currently being worked on. See GFSendGumpV( ) for the gump-in-a-box method :-)

GFSendGumpV( who, gumpvar )
Purpose | To create and run the gump stored in the gumpvar variable, then return the results to the calling function.
who | The player you want to send the Gump to
gumpvar | The variable that holds the gump information
Return Value | Returns the exact same type of key-array as the core-function SendDialogGump( ) (see the UO.EM file)
Notes | This function call uses the gump definition that's stored in the gumpvar variable using the GFStoreGump( ) function. Calling this function will not overwrite the gump that's currently being worked on! :-)

Example code

Returns a '1' if you click "Okay", a '0' if you click "Cancel", or '-1' if something weird occurs.

    //
    // Gump which asks "Are you sure?"
    //
    include "include/gumps.inc";

    function gump_areyousure( who )

        GFInitGump();
        GFNoClose();

        GFSetRef( 100, 100 );
        GFGumpPic( 0, 0, 0x816 );
        GFTextLine( 38, 33, 55, "Are you sure?" );
        var okay := GFButtonID( 35, 72, 0x81c, 0x81b, 1 );
        var cancel := GFButtonID( 85, 72, 0x819, 0x818, 1 );

        var retv := GFSendGump( who );

        if ( retv[0] == okay.keyid )
            return 1;
        elseif ( retv[0] == cancel.keyid )
            return 0;
        else
            return -1;
        endif

    endfunction