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:


    (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