GUMPS.INC help file -v2.2-

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.

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! :-)

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