The GUIObject class provides a JavaScript wrapper around GUI objects, allowing their properties to be manipulated.

GUIObject Methods

getByName

• Overview:
  • Returns another GUIObject, matching a specific name.
• Syntax:
  • var newguiobject = oldguiobject.getByName("objectname");
• Parameters:
  • objectname: A string that corresponds to the name given in the GUI XML file. Case sensitive.
• Returns:
  • A new GUIObject, or null if no match was found.Notes:
  • Has the same effect as the global getGUIObjectByName(name) function.

toString (Implicit)

• Overview:
  • Overrides the default string conversion to include the name of this GUI object.
• Syntax:
  • var name = "The name is " + guiobject;
• Parameters:
  • None.
• Returns:
  • A string of the form '[GUIObject: objectname]'
• Notes:
  • This function is called implicitly by the JavaScript engine to convert this object to a string.

GUIObject Properties

parent

• Overview:
  • The GUIObject corresponding to the parent of this object.
• Type:
  • GUIObject
• Notes:
  • Has the value null if the object has no parent. Read-only.

anything else

• Overview:
  • Read/write access to object-type specific settings.
• Type:
  • boolean / integer / double / string / GUIColor / GUISize
• Notes:
  • Unrecognised parameters are passed to the GUI system as object-specific settings. The valid settings are documented in the GUI TDD, with the addition of 'caption'. If the object does not recognise the setting, an error is reported and a JS exception is thrown.
  • These data types are used to pass data in and out of GUI objects. All have constructors (with parameters in the same order as the properties described below) and toString methods.

GUIMouse Properties

x, y

• Overview:
  • The coordinates of the mouse, measured in pixels from the top-left corner of the screen.
• Type:
  • integer
• Notes:
  • Read-only. mouse.x and mouse.y also seem to work.

buttons

• Overview:
  • Indicates the state of the mouse buttons.
  • Bit 0 = LMB, bit 1 = RMB, bit 2 = MMB.
• Type:
  • integer
• Notes:
  • If the mouse buttons are read by code inside a mouse-related event handler, mouse-down events set the appropriate bit of 'buttons' high before executing the code, while mouse-up events clear the appropriate bit of 'buttons' to zero after running the code.

GUISize Properties

left, top, right, bottom

• Overview:
  • The absolute components of a rectangle, measured in pixels from the top-left corner of the parent object.
• Type:
  • integer

rleft, rtop, rright, rbottom

• Overview:
  • The relative components of a rectangle, measured in percentages of the width/height of the parent object.
• Type:
  • integer
• Notes:
  • The absolute and relative components are added to compute the final size of a GUI object. Either can be negative.

GUIColor Properties

r, g, b, a

• Overview:
  • The red/green/blue/alpha components of a colour, in the range 0.0 to 1.0.
• Type:
  • double

GUI Global Functions

getGUIObjectByName

• Overview:
  • Look up a GUI object, given name.
• Syntax:
  • object = getGUIObjectByName(name)
• Parameters:
  • name [string]
• Returns:
  • object
• Notes:

getGUIGlobal

• Overview:
  • Returns the sort-of-global object associated with the current GUI.
• Syntax:
  • global = getGUIGlobal()
• Parameters:
• Returns:
  • global object
• Notes:
  • Useful for accessing an object from another scope.

GUI JS Functions

Utility functions that have been written in JS, rather than being exposed from the engine.

List functions

These are functions for all the controls using the list property, i.e. The List and the Drop-down.

addItem

• Overview:
  • Inserts an item to an object's list, and updates the selection accordingly.
• Syntax:
  • addItem(objectName, pos, value)
• Parameters:
  • objectName: Name of the object.
  • pos: index position in the list, 0 inserts it before the first item.
  • value: string value of the new item.
• Returns:

removeItem

• Overview:
  • Removes an item from an object's list, and updates the selection accordingly.
• Syntax:
  • removeItem(objectName, pos)
• Parameters:
  • objectName: Name of the object.
  • pos: index position in the list, 0 removes the first item.
• Returns:

pushItem

• Overview:
  • Adds an item to the end of the list.
• Syntax:
  • pushItem(objectName, value)
• Parameters:
  • objectName: Name of the object.
  • value: The string value you would like to input.
• Returns:

popItem

• Overview:
  • Removes the last item from a list.
• Syntax:
  • popItem(objectName)
• Parameters:
  • objectName: Name of the object.
• Returns:

getNumItems

• Overview:
  • Retrieves the number of items in a list.
• Syntax:
  • getNumItems(objectName)
• Parameters:
  • objectName: Name of the object.
• Returns:
  • Number of items in the list.

getItemValue

• Overview:
  • Retrieves the item value at given position.
• Syntax:
  • getItemValue(objectName, pos)
• Parameters:
  • objectName: Name of the object.
  • pos: Position of item you would like to retrieve, the first one is 0.
• Returns:
  • The value as string.

getCurrItemValue

• Overview:
  • Retrieves the item value of the currently selected item.
• Syntax:
  • getCurrItemValue(objectName)
• Parameters:
  • objectName: Name of the object.
• Returns:
  • The value as string.