GuiControl
Base class for all Gui control objects.
Layout
Point2I
The position relative to the parent control.
Point2I
The width and height of the control.
Point2I
The minimum width and height of the control. The control will not be resized smaller than this.
The horizontal resizing behavior.
The vertical resizing behavior.
Control
The control profile that determines fill styles, font settings, etc.
bool
Whether the control is visible or hidden.
bool
Whether the control is enabled for user interaction.
deprecated
deprecated
string
Name of the variable to which the value of this control will be synchronized.
string
Command to execute on the primary action of the control.
string
Command to execute on the secondary action of the control.
string
Key combination that triggers the control's primary action when the control is on the canvas.
ToolTip
Control profile to use when rendering tooltips for this control.
string
String to show in tooltip for this control.
int
Time for mouse to hover over control until tooltip is shown (in milliseconds).
Editing
bool
If true, the control may contain child controls.
Localization
string
Name of string table to use for lookup of internationalized text.
Callbacks
void
onAdd()
Called when the control object is registered with the system after the control has been created.
void
onRemove()
Called when the control object is removed from the system before it is deleted.
void
onWake()
Called when the control is woken up.
void
onSleep()
Called when the control is put to sleep.
void
Called when the control gains first responder status on the GuiCanvas.
void
Called when the control loses first responder status on the GuiCanvas.
void
onAction()
Called when the control's associated action is triggered and no 'command' is defined for the control.
void
onVisible(bool state)
Called when the control changes its visibility state, i.e. when going from visible to invisible or vice versa.
void
onActive(bool state)
Called when the control changes its activeness state, i.e. when going from active to inactive or vice versa.
void
Called when the control is pushed as a dialog onto the canvas.
void
Called when the control is removed as a dialog from the canvas.
void
onControlDragEnter(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has entered the control. This is only called for topmost visible controls as the GuiDragAndDropControl moves over them.
void
onControlDragExit(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has exited the control and moved over a different control. This is only called for topmost visible controls as the GuiDragAndDropControl moves off of them.
void
onControlDragged(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl is moving across the control after it has entered it. This is only called for topmost visible controls as the GuiDragAndDropControl moves across them.
void
onControlDropped(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has completed and is dropping its payload onto the control. This is only called for topmost visible controls as the GuiDragAndDropControl drops its payload on them.
Public Functions
void
addGuiControl(GuiControl control)
Add the given control as a child to this control.
void
clearFirstResponder(bool ignored)
Clear this control from being the first responder in its hierarchy chain.
bool
controlIsChild(GuiControl control)
Test whether the given control is a direct or indirect child to this control.
findHitControl(int x, int y)
Find the topmost child control located at the given coordinates.
string
findHitControls(int x, int y, int width, int height)
Find all visible child controls that intersect with the given rectangle.
float
Get the aspect ratio of the control's extents.
Point2I
Get the coordinate of the control's center point relative to its parent.
Point2I
Get the width and height of the control.
Get the first responder set on this GuiControl tree.
Point2I
Get the coordinate of the control's center point in coordinates relative to the root control in its control hierarchy.
Point2I
Get the position of the control relative to the root of the GuiControl hierarchy it is contained in.
Point2I
Get the minimum allowed size of the control.
Get the immediate parent control of the control.
Point2I
Get the control's current position relative to its parent.
string
getValue()
Get the value associated with the control.
bool
isActive()
Check if this control is active or not.
bool
isAwake()
Test whether the control is currently awake.
bool
Test whether the control is the current first responder.
bool
Indicates if the mouse is locked in this control.
bool
Test whether the control is currently set to be visible.
void
makeFirstResponder(bool isFirst)
Make this control the first responder.
bool
pointInControl(int x, int y)
Test whether the given point lies within the rectangle of the control.
void
resize(int x, int y, int width, int height)
Resize and reposition the control using the give coordinates and dimensions. Child controls will resize according to their layout behaviors.
void
setActive(bool state)
Set the control as active or inactive.
void
setCenter(int x, int y)
Set the control's position by its center point.
void
setExtent(Point2I p)
Resize the control to the given dimensions.
void
setExtent(S32 width, S32 height)
Resize the control to the given dimensions.
void
Make this control the current first responder.
void
setPosition(int x, int y)
Position the control in the local space of the parent control.
void
setPositionGlobal(int x, int y)
Set position of the control relative to the root of the GuiControl hierarchy it is contained in.
void
setProfile(GuiControlProfile profile)
Set the control profile for the control to use.
void
setValue(string value)
Set the value associated with the control.
void
setVisible(bool state)
Set whether the control is visible or not.
Detailed Description
Base class for all Gui control objects.
GuiControl is the basis for the Gui system. It represents an individual control that can be placed on the canvas and with which the mouse and keyboard can potentially interact with.
Control Hierarchies
GuiControls are arranged in a hierarchy. All children of a control are placed in their parent's coordinate space, i.e. their coordinates are relative to the upper left corner of their immediate parent. When a control is moved, all its child controls are moved along with it.
Since GuiControl's are SimGroups, hierarchy also implies ownership. This means that if a control is destroyed, all its children are destroyed along with it. It also means that a given control can only be part of a single GuiControl hierarchy. When adding a control to another control, it will automatically be reparented from another control it may have previously been parented to.
Control Profiles
Common data accessed by GuiControls is stored in so-called "Control Profiles." This includes font, color, and texture information. By pooling this data in shared objects, the appearance of any number of controls can be changed quickly and easily by modifying only the shared profile object.
If not explicitly assigned a profile, a control will by default look for a profile object that matches its class name. This means that the class GuiMyCtrl, for example, will look for a profile called 'GuiMyProfile'. If this profile cannot be found, the control will fall back to GuiDefaultProfile which must be defined in any case for the Gui system to work.
In addition to its primary profile, a control may be assigned a second profile called 'tooltipProfile' that will be used to render tooltip popups for the control.
First Responders
At any time, a single control can be what is called the "first responder" on the GuiCanvas is placed on. This control will be the first control to receive keyboard events not bound in the global ActionMap. If the first responder choses to handle a particular keyboard event,
Layout
Point2I position
The position relative to the parent control.
Point2I extent
The width and height of the control.
Point2I minExtent
The minimum width and height of the control. The control will not be resized smaller than this.
GuiHorizontalSizing horizSizing
The horizontal resizing behavior.
GuiVerticalSizing vertSizing
The vertical resizing behavior.
Control
GuiControlProfile profile
The control profile that determines fill styles, font settings, etc.
bool visible
Whether the control is visible or hidden.
bool active
Whether the control is enabled for user interaction.
deprecated modal
Deprecated: This member is deprecated and its value is always undefined.
deprecated setFirstResponder
Deprecated: This member is deprecated and its value is always undefined.
string variable
Name of the variable to which the value of this control will be synchronized.
string command
Command to execute on the primary action of the control.
note:Within this script snippet, the control on which the command is being executed is bound to the global variable $ThisControl.
string altCommand
Command to execute on the secondary action of the control.
note:Within this script snippet, the control on which the altCommand is being executed is bound to the global variable $ThisControl.
string accelerator
Key combination that triggers the control's primary action when the control is on the canvas.
ToolTip
GuiControlProfile tooltipProfile
Control profile to use when rendering tooltips for this control.
string tooltip
String to show in tooltip for this control.
int hovertime
Time for mouse to hover over control until tooltip is shown (in milliseconds).
Editing
bool isContainer
If true, the control may contain child controls.
Localization
string langTableMod
Name of string table to use for lookup of internationalized text.
Callbacks
onAdd()
Called when the control object is registered with the system after the control has been created.
onRemove()
Called when the control object is removed from the system before it is deleted.
onWake()
Called when the control is woken up.
onSleep()
Called when the control is put to sleep.
onGainFirstResponder()
Called when the control gains first responder status on the GuiCanvas.
onLoseFirstResponder()
Called when the control loses first responder status on the GuiCanvas.
onAction()
Called when the control's associated action is triggered and no 'command' is defined for the control.
onVisible(bool state)
Called when the control changes its visibility state, i.e. when going from visible to invisible or vice versa.
Parameters:
| state | The new visibility state. |
onActive(bool state)
Called when the control changes its activeness state, i.e. when going from active to inactive or vice versa.
Parameters:
| stat | The new activeness state. |
onDialogPush()
Called when the control is pushed as a dialog onto the canvas.
onDialogPop()
Called when the control is removed as a dialog from the canvas.
onControlDragEnter(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has entered the control. This is only called for topmost visible controls as the GuiDragAndDropControl moves over them.
Parameters:
| control | The payload of the drag operation. |
| dropPoint | The point at which the payload would be dropped if it were released now. Relative to the canvas. |
onControlDragExit(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has exited the control and moved over a different control. This is only called for topmost visible controls as the GuiDragAndDropControl moves off of them.
Parameters:
| control | The payload of the drag operation. |
| dropPoint | The point at which the payload would be dropped if it were released now. Relative to the canvas. |
onControlDragged(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl is moving across the control after it has entered it. This is only called for topmost visible controls as the GuiDragAndDropControl moves across them.
Parameters:
| control | The payload of the drag operation. |
| dropPoint | The point at which the payload would be dropped if it were released now. Relative to the canvas. |
onControlDropped(GuiControl control, Point2I dropPoint)
Called when a drag&drop operation through GuiDragAndDropControl has completed and is dropping its payload onto the control. This is only called for topmost visible controls as the GuiDragAndDropControl drops its payload on them.
Parameters:
| control | The control that is being dropped onto this control. |
| dropPoint | The point at which the control is being dropped. Relative to the canvas. |
Public Functions
addGuiControl(GuiControl control)
Add the given control as a child to this control.
This is synonymous to calling SimGroup::addObject. Parameters:
| control | The control to add as a child. |
note:The control will retain its current position and size.
SimGroup::addObject Control Hierarchies
clearFirstResponder(bool ignored)
Clear this control from being the first responder in its hierarchy chain.
Parameters:
| ignored | Ignored. Supported for backwards-compatibility. |
controlIsChild(GuiControl control)
Test whether the given control is a direct or indirect child to this control.
Parameters:
| control | The potential child control. |
True if the given control is a direct or indirect child to this control.
findHitControl(int x, int y)
Find the topmost child control located at the given coordinates.
note:Parameters:Only children that are both visible and have the 'modal' flag set in their profile will be considered in the search.
| x | The X coordinate in the control's own coordinate space. |
| y | The Y coordinate in the control's own coordinate space. |
The topmost child control at the given coordintes or the control on which the method was called if no matching child could be found.
findHitControls(int x, int y, int width, int height)
Find all visible child controls that intersect with the given rectangle.
note:Parameters:Invisible child controls will not be included in the search.
| x | The X coordinate of the rectangle's upper left corner in the control's own coordinate space. |
| y | The Y coordinate of the rectangle's upper left corner in the control's own coordinate space. |
| width | The width of the search rectangle in pixels. |
| height | The height of the search rectangle in pixels. |
A space-separated list of the IDs of all visible control objects intersecting the given rectangle.
// Lock all controls in the rectangle at x=10 and y=10 and the extent width=100 and height=100. foreach$( %ctrl in %this.findHitControls( 10, 10, 100, 100 ) ) %ctrl.setLocked( true );
getAspect()
Get the aspect ratio of the control's extents.
The width of the control divided by its height.
getCenter()
Get the coordinate of the control's center point relative to its parent.
The coordinate of the control's center point in parent-relative coordinates.
getExtent()
Get the width and height of the control.
A point structure containing the width of the control in x and the height in y.
getFirstResponder()
Get the first responder set on this GuiControl tree.
The first responder set on the control's subtree.
getGlobalCenter()
Get the coordinate of the control's center point in coordinates relative to the root control in its control hierarchy.
@Return the center coordinate of the control in root-relative coordinates.
getGlobalPosition()
Get the position of the control relative to the root of the GuiControl hierarchy it is contained in.
The control's current position in root-relative coordinates.
getMinExtent()
Get the minimum allowed size of the control.
The minimum size to which the control can be shrunk.
getParent()
Get the immediate parent control of the control.
The immediate parent GuiControl or 0 if the control is not parented to a GuiControl.
getPosition()
Get the control's current position relative to its parent.
The coordinate of the control in its parent's coordinate space.
getRoot()
Get the canvas on which the control is placed.
The canvas on which the control's hierarchy is currently placed or 0 if the control is not currently placed on a GuiCanvas.
GuiControl_Hierarchy
getValue()
Get the value associated with the control.
value for the control.
isActive()
Check if this control is active or not.
True if it's active, false if not.
isAwake()
Test whether the control is currently awake.
If a control is awake it means that it is part of the GuiControl hierarchy of a GuiCanvas.
True if the control is awake.Waking and Sleeping
isFirstResponder()
Test whether the control is the current first responder.
True if the control is the current first responder.
isMouseLocked()
Indicates if the mouse is locked in this control.
True if the mouse is currently locked.
isVisible()
Test whether the control is currently set to be visible.
True if the control is currently set to be visible.
note:Visibility and ActivenessThis method does not tell anything about whether the control is actually visible to the user at the moment.
makeFirstResponder(bool isFirst)
Make this control the first responder.
Parameters:
| isFirst | True to make first responder, false to not. |
pointInControl(int x, int y)
Test whether the given point lies within the rectangle of the control.
Parameters:
| x | X coordinate of the point in parent-relative coordinates. |
| y | Y coordinate of the point in parent-relative coordinates. |
True if the point is within the control, false if not.
resize(int x, int y, int width, int height)
Resize and reposition the control using the give coordinates and dimensions. Child controls will resize according to their layout behaviors.
Parameters:
| x | The new X coordinate of the control in its parent's coordinate space. |
| y | The new Y coordinate of the control in its parent's coordinate space. |
| width | The new width to which the control should be resized. |
| height | The new height to which the control should be resized. |
setActive(bool state)
Set the control as active or inactive.
Parameters:
| state | True to set the control as active, false to set it as inactive. |
setCenter(int x, int y)
Set the control's position by its center point.
Parameters:
| x | The X coordinate of the new center point of the control relative to the control's parent. |
| y | The Y coordinate of the new center point of the control relative to the control's parent. |
setExtent(Point2I p)
Resize the control to the given dimensions.
Child controls with resize according to their layout settings. Parameters:
| p | The new ( width, height ) extents of the control. |
setExtent(S32 width, S32 height)
Resize the control to the given dimensions.
Child controls will resize according to their layout settings. Parameters:
| width | The new width of the control in pixels. |
| height | The new height of the control in pixels. |
setFirstResponder()
Make this control the current first responder.
note:Only controls with a profile that has canKeyFocus enabled are able to become first responders.
setPosition(int x, int y)
Position the control in the local space of the parent control.
Parameters:
| x | The new X coordinate of the control relative to its parent's upper left corner. |
| y | The new Y coordinate of the control relative to its parent's upper left corner. |
setPositionGlobal(int x, int y)
Set position of the control relative to the root of the GuiControl hierarchy it is contained in.
Parameters:
| x | The new X coordinate of the control relative to the root's upper left corner. |
| y | The new Y coordinate of the control relative to the root's upper left corner. |
setProfile(GuiControlProfile profile)
Set the control profile for the control to use.
The profile used by a control determines a great part of its behavior and appearance. Parameters:
| profile | The new profile the control should use. Control Profiles |
setValue(string value)
Set the value associated with the control.
Parameters:
| value | The new value for the control. |
setVisible(bool state)
Set whether the control is visible or not.
Parameters:
| state | The new visiblity flag state for the control. Visibility and Activeness |