GuiControl

consoledoc.h

Base class for all Gui control objects.

More...

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

Called when the control object is registered with the system after the control has been created.

void

Called when the control object is removed from the system before it is deleted.

void

Called when the control is woken up.

void

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

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

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

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.

Get the canvas on which the control is placed.

string

Get the value associated with the control.

bool

Check if this control is active or not.

bool

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

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.

Layout System

GuiControls have a two-dimensional position and are rectangular in shape.

Event System

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.

Triggered Actions

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,

Waking and Sleeping

Visibility and Activeness

By default, a GuiControl is active which means that it

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.

Waking and Sleeping

onSleep()

Called when the control is put to sleep.

Waking and Sleeping

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.

Triggered Actions

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.

see:

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.

return:

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:

Only children that are both visible and have the 'modal' flag set in their profile will be considered in the search.

Parameters:
x

The X coordinate in the control's own coordinate space.

y

The Y coordinate in the control's own coordinate space.

return:

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:

Invisible child controls will not be included in the search.

Parameters:
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.

return:

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.

return:

The width of the control divided by its height.

getCenter()

Get the coordinate of the control's center point relative to its parent.

return:

The coordinate of the control's center point in parent-relative coordinates.

getExtent()

Get the width and height of the control.

return:

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.

return:

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.

return:

The control's current position in root-relative coordinates.

getMinExtent()

Get the minimum allowed size of the control.

return:

The minimum size to which the control can be shrunk.

getParent()

Get the immediate parent control of the control.

return:

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.

return:

The coordinate of the control in its parent's coordinate space.

getRoot()

Get the canvas on which the control is placed.

return:

The canvas on which the control's hierarchy is currently placed or 0 if the control is not currently placed on a GuiCanvas.

see:

GuiControl_Hierarchy

getValue()

Get the value associated with the control.

return:

value for the control.

isActive()

Check if this control is active or not.

return:

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.

return:

True if the control is awake.Waking and Sleeping

isFirstResponder()

Test whether the control is the current first responder.

return:

True if the control is the current first responder.

isMouseLocked()

Indicates if the mouse is locked in this control.

return:

True if the mouse is currently locked.

isVisible()

Test whether the control is currently set to be visible.

return:

True if the control is currently set to be visible.

note:

This method does not tell anything about whether the control is actually visible to the user at the moment.

Visibility and Activeness

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.

return:

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