GUI Controls
|
Each element of the Graphical User Interface is a separate GUI Control. For example, if a popup window appears with a text message and an "OK" button, the window is one control, the part with the text message is another control, and the button is actually several combined controls. There may also be other invisible controls on the window, which affect its appearance and behavior.
Each GUI Control is a node, based on a certain class. When the nodes are created, their fields are configured with certain values, and a callback is made to the script baseGUI:onControlBuild()
.
Controls can be configured to cause certain things to happen, such as when the mouse is used to click on any part of the control. These are called "GUI Events", and are caused by other scripts which were created with functions which take actions based on the desired GUIEvents.
There are 20 or so basic GUI Control Classes. Each of those classes has fields, some of which are subclasses with their own fields. This page is an attempt to document all of the relevant attributes (fields and subclass fields) for each class.
Types of GUI Controls
All of the different pieces that make up a graphical window, are called GUI Controls. A control might be a button, a scrollbar, a checkbox, a text input box, radio button, a panel with several buttons, a displayed text panel, or even an entire window which has several other controls upon it. Some controls are intuitive as to what their function is, such as a "button". Others might be used as stand-alone controls, or as ingredients which add a behavior to a larger collection of Controls. For example, a GUIMovePanel can be added as a child of a window, and configured to specify that the entire Window is click-and-draggable.
Detailed descriptions and fields for each of the controls is available further down on this page. For quick-reference though, a list of available controls is as follows:
Control Class | Description |
GUIControl | The base class which other GUI Controls inherit from |
GUIPanel | A class that inherits directly from GUIControl with no changes |
GUIMovePanel | A movable panel, or Control which specifies the moveability of a parent control |
GUIResizePanel | A panel that can resize other panels |
GUI9Slice | A panel divided into 9 sections, each of which stretches or tiles appropriately |
GUIScaleAndAlphaPanel | A panel which can be resized or have its alpha/transparency modified |
GUILabel | A static area of text |
GUICheckbox | A standard on/off checkbox |
GUITextInputBox | For taking text input |
GUIRadioButton | An on/off radio button |
GUIGraph | Creates a line graph based on specified data |
Scrollbar Controls | |
GUIScrollablePanel | The area which is controlled by the scrollbar |
GUIScrollThumb | the bar on a scrollbar which is clicked and dragged to scroll |
GUIScrollPagePanel | The scrollbar itself (has a scrollthumb inside) |
GUIScrollEndButton | the arrow buttons on either end of a scrollbar |
GUICollection | Maintains an expandable list of items to be scrolled through |
Numeric Field Controls | |
GUINumericField | an input field which allows only numbers |
GUINumericUpDownButtonField | button which changes the numeric field by predefined increments (is this with or without the "Field" suffix?) |
GUINumericUpDownDragZone | slide between numeric field up/down buttons |
Slider Controls | |
GUISlider | a sliding bar which controls the value of another control |
GUISliderEndButton | buttons on either end of a slider to move it in predefined steps |
GUI Control Base Fields
All of the GUI Controls inherit from the GUIControl
class. Some of them also have their own additional fields and subclasses. The GUIControl class contains base fields which are available to all control types.
NOTE: In the following table, under the "Subclass or Datatype" column, a name in italics means that this is a class which has its own subfields. For names and definitions of those fields, please see the appropriate subclass section further down on this page.
Appearance
Field | Subclass or Datatype | Default Settings | Description |
tiling | hv | false/false | Used with the texture system, to determine if the texture should be stretched, or kept as-is and tiled. Tiling can occur horizontally, vertically, or both, depending on how the subfields are set. If a particular direction is set to FALSE, and the size of the Control is different than the size of the texture (larger or smaller), then the texture is stretched or compressed to fit. If !TRUE, then the texture is used as-is. If the texture is larger than the control, then only as much as the normal size texture can be seen is used. If TRUE and the texture is smaller than the control, then it is tiled appropriately to fill the entire control. |
textureFilter | boolean | TRUE | Enables filter sample blending on the image used for the control (linear / linear) |
opacity | float | 1.0 | (0 to 1) opacity of control, 0 is invisible, 1 is fully visible |
texture | string | (none) | Texture FQN of texture file (see State Presentation for more information). If the texture name begins with a colon, the GUI Control will interpret the rest of the name as the name of a Virtual Stage, and will render that stage as the control's texture. If this is done, the uv fields are automatically set to fill the Control without tiling. |
material | string | (none) | No longer used as a field of GUI Control |
additiveblending | boolean | FALSE | When set to TRUE, a GUI Control may pick up (blend with) the colors of other controls behind it, just like normal additive blending (see Google) |
opacityModifier | float | 1.0 | degree (0 to 1) to which opacity adjustment affects this control. 0 means not adjustable, 1 means full control. Example: The "click and drag" in the gem for the Chat Window controls its opacity. |
alphaMask | alphaMask | -- | Specifies non-rectangular clipping for a GUI Control by means of the alpha channel of a texture |
Behavior
Field | Subclass or Datatype | Default Settings | Description |
gotoTopOnMouseDown | boolean | FALSE | If this flag is TRUE, this control will pop ahead of all others owned by its parent whenever the mouse is clicked on it or any of its children. Mostly used for windows. |
IgnoreMouseEvents | boolean | FALSE | Set true for this control to ignore mouse events on this Control only. Does not apply to Children or Parent controls. |
animation | string | null | When it is desired to connect an animation to a GUIControl, this field should be set to the name of the animation. The name will be the same as the GUIAnimation script. For example, if the animation script is GUIA_ButtonClicks.hsl, then this field should be set to "ButtonClicks". |
enabled | boolean | true | If TRUE, enables a control so that it can be activated via events, and state presentations display properly |
selected | boolean | false | |
script | scriptref | (none) | the FQN of the script to call for GUIevents |
visible | boolean | true | Flag which controls whether or not this control is visible on the screen |
ignoreDragDropEvents | boolean | TRUE | When set to TRUE, causes mouse click-and-drag to be ignored |
Data
Field | Subclass or Datatype | Default Settings | Description |
type | string | (empty) | Read-only, internal use field. A string which is the name of the prototype being created from this class |
name | string | (empty) | The unique identifier for this control |
filename | string | <controlname>.xml | This is the name of the file where the raw GUIXML for the GUIControl is stored |
treePath | string | "" | For organizational purposes only. This indicates the location of this control in the GUIXML tab of the Organizer Panel. It currently has no effect. |
Layout
Field | Subclass or Datatype | Default Settings | Description |
anchor | windowSides | top=true bottom=false left=true right=false |
Determines how the control is positioned and sized when its parent is resized. For whichever one is TRUE, resizing the parent will also move or size the child in relation. Having just one of the top/bottom or left/right pairs set to TRUE will move the child, and having both of a pair set to TRUE will cause the child to resize. |
Position | xy | 0.0,0.0 | location of the control relative to its parent, or to the screen. |
minimumSize | xy | 0.0, 0.0 | minimum size of control, when resizing (docking overrides these) |
maximumSize | xy | 0.0, 0.0 | maximum size of control, when resizing |
rotation | float | 0.0 | The value that a texture should be rotated, in degrees, as a relative angle from the non-rotated version. A value of 0 means "no rotation". |
dockMode | enum enum_dockMode | NONE | Determines how the control docks to its parent. Options are NONE (no docking, and position is determined exclusively by the x/y coordinates), LEFT, RIGHT, TOP, BOTTOM and FILL (which uses all available space). Example: If this were set to RIGHT, then the GUIControl would do its best to dock itself flush to the far right of its parent control. |
Size | xy | 0.0, 0.0 | size of the control. This may be overridden by docking or anchoring. |
scale | float | 1.0 | scale of control |
autoCenter | hv | horizontal=false vertical=false |
When true, the corresponding part of its position will always be set so the control is centered in its parent. |
Misc
Field | Subclass or Datatype | Default Settings | Description |
layer | string | "" | The layer the control will be on. Standard code will put non-specified controls in the "default" layer. |
cursorName | string | ARROW | This changes the type of cursor, like a hand, an arrow, etc. Valid names are: ARROW, HAND, IBEAM, WAIT, UPARROW, SIZENWSE, SIZENESW, SIZEWE, SIZENS, SIZEALL, NO, APPSTARTING, CROSS |
gluedtonode | ID | 0 | This is the ID of the node that the GUI Control is connected to. Example: Connecting a chat bubble to a character. See Gluing GUI Controls to Nodes for more information. |
skipTextureAlphaTest | boolean | FALSE | By default, a section of a control with a low alpha (<= 10%) is not sensitive to mouse GUI Events. When this field is set to TRUE, all of the control will always be sensitive to the mouse, regardless of alpha level. |
baseGUIClass | ID | <className> | Read-only. This is the ID of the class from which this control's prototype is made. |
tooltip | string | "" | Text that will appear when the cursor hovers over this control for a few seconds. |
fadeDistance | float | 0 | If gluedToNode is non-zero, this adjusts the opacity of GUI Controls by specifying the distance from the camera at which they become completely transparent. The transition begins at the 50% mark. If fadeDistance is 0, then no fading will occur, and GUI Controls will be visible at any distance as long as the camera has line of sight to its position.
|
inheritedFrom | node of class GUIControl | (for internal use) The prototype that this control's prototype inherits from (if any). | |
popup | boolean | FALSE | A GUIControl will be either in the "regular" layer, or a "popup" layer. If this is TRUE, then it is in the popup layer, which means it will always display above the non-popup controls. Primarily used for menus and confirmation dialogs |
glomClass | string | "" | An optional name of a class that will be glommed onto this control. |
worldspaceoffset | vector3 | null | The direction and distance from the primary node, that the glued GUI Control is positioned |
Presentation States
Field | Subclass or Datatype | Default Settings | Description |
disabledStatePresentation | uv | (see subclass info) | (optional) See State Presentation |
selectedStatePresentation | uv | (see class defaults) | (optional) When the control is selected, this controls how that the texture is displayed. See State Presentation for more information. |
inheritDisabledState | boolean | TRUE | When TRUE, this control inherits its disabled state from its parent, so if its parent control becomes disabled (its ENABLED flag is set to FALSE), then this control becomes disabled too. |
inheritHoveringState | boolean | TRUE | When this is TRUE, then this control will display in the same state as its parent, if the parent is in a Hovering State |
selectedHoverStatePresentation | uv | (class defaults) | ?? |
defaultStatePresentation | uv | (see subclass fields) | See State Presentation for more information |
hoverStatePresentation | uv | (see class defaults) | (optional) See State Presentation |
SelectedDisabledStatePresentation | uv | (see class defaults) | (optional) See State Presentation |
inheritSelectedState | boolean | TRUE | When this is TRUE, then this control will display in the same state as its parent, if the parent is in a Selected State |
Internal Use Fields
Field | Subclass or Datatype | Default Settings | Description |
protoCopiedFrom | node of class GUIControl | for internal use only | |
prototype | node of class GUIControl | Read-only, internal use field. This is a node reference to the prototype that the control was created from | |
oldcrappyscript | string | n/a | No longer used |
copy | boolean | FALSE | (for internal use) |
parent | noderef | (empty) | Set by the system to the node of the parent GUI control |
children | list of node of class GUIControl | empty | List of nodes that are children of the current Control. This list is automatically populated by the XMLChomper in HeroBlade, but it is still possible to add or remove children via script. |
build | boolean | FALSE | Should be set to FALSE while a control is being built or edited, and then toggled to TRUE when it is completed. This prevents certain changes occurring (like an anchoring change) while the control is being built. |
Other GUIControls - Panel Classes
GUIMovePanel
The GUIMovePanel parameters are identical to GUIPanel with the following two exceptions:
Field | Subclass or Datatype | Default Settings | Description |
owner | string | "" | Determines which parent object is the root, in order to decide what gets dragged. |
allowMove | boolean | TRUE | Flag indicating whether the panel should be movable. Setting to false will disable the move functionality of this movepanel |
In its simplest form, this control is a panel which can be clicked and dragged around the screen. However, it also has a very powerful property, which is that it can cause its parent Control(s) to also be draggable. The way to configure this is via this panel's owner
subfield:
- A null value ("") means that nothing is draggable.
- A zero value ("0") means that only the movePanel itself can be moved.
- A string value of a number ("1", "2", etc.) indicates how many levels of parents, with their associated children, can be moved. Setting this to an invalid value (such as "99") would be the same as setting it to null.
- A string with the name of another control will designate that one as the root parent to be dragged, as long as that control is in the direct hierarchy of the MovePanel. A sibling Control could be chosen, as long as it was specified in relation to a valid parent. Attempting to set some other Control would be invalid.
Example:
Suppose there was the following set of Controls:
"Window" control with children: "Panel1" "button1" "button2" "Panel2" "button3" "checkbox1" "movepanel1" "radiobutton" "button4" "UnrelatedScrollablePanel" "movepanel2" "button5"
Then the following results would occur:
value | Result | What Would Be Draggable |
null | Invalid | Nothing |
"0" | Valid | movepanel1 and all of its children |
"movepanel1" | Valid | movepanel1 and all of its children |
"1" | Valid | Panel2 and all of its children |
"Panel2" | Valid | Panel2 and all of its children |
"Window" | Valid | Window and both of its subpanels and their respective children |
"99" | Invalid | Nothing |
"Panel1" | Invalid | Nothing |
"Window.Panel1" | Valid | Panel1 and its children |
"radiobutton" | Valid | Only the radiobutton (and any of its respective children) |
"UnrelatedScrollablePanel" | invalid | Nothing |
GUIResizePanel
When placed on a parent control, this panel allows its parent to be resized via click-and-drag. It uses all the fields of of GUIPanel, plus:
Field | Subclass or Datatype | Default Settings | Description |
Resize | windowSides | top=false bottom=false left=false right=false |
Set these to determine which sides of its parent are resized. Children controls may or may not be resized with the parent, depending on how the docking and anchoring fields are set. For whichever one is TRUE, resizing the parent will also move or size the child in relation. Having just one of the top/bottom or left/right pairs set to TRUE will move the child, and having both of a pair set to TRUE will cause the child to resize. |
owner | string | NULL | Can specify the path to the owning GUI Control, or an integer specifying how many parents to look through, to determine which control this affects |
GUI9Slice
A GUI panel divided by two horizontal lines and two vertical lines into a grid of nine sections. Each section knows how to tile or stretch appropriately. It can be used to create buttons and windows without the need for separate controls for each edge and corner.
GUI9Slice can also be used as a simple blank GUIPanel with margins, simplifying complex layouts.
See GUI9Slice.
GUIScaleAndAlphaPanel
GUI Control which allows scaling a given window via vertical click-and-drag, and alpha (transparency) adjustment via horizontal click-and-drag. Parameters are identical to GUIPanel with the following exception.
Field | Subclass or Datatype | Default Settings | Description |
owner | string | Can specify the path to the owning GUI Control, or an integer specifying how many parents to look through, to determine which control this affects |
GUILabel
This is a static text area. It contains all parameters of GUIPanel, plus:
Field | Subclass or Datatype | Default Settings | Description |
text | string | (empty) | The text to display. |
textFormat | justify | (see subclass fields) | Text formatting flags |
autoSetHeight | boolean | FALSE | If this is TRUE, a label will automatically vertically resize based on its current width, font setting, and text. This is overridden by docking. |
textPadding | integer | 0 | Specifies the minimum number of pixels between the text and the edge of the label |
displayFont | enum font | DEFAULTTEXT | An enumerated value which specifies the font |
fontFace | string | (empty) | If this property is set to either the font name or a valid fqn to a font resource in the repository, this font will be used to render text in the GUILabel (this overrides the displayFont property) |
GUICheckBox
This is a standard "click on, click off" checkbox. It has all the fields of GUIControl, plus:
Field | Subclass or Datatype | Default Settings | Description |
checked | boolean | false | determines current status of control |
GUIRadioButton
A standard radio button, typically seen in groups. All radio buttons within a single immediate parent are considered to be grouped, and will uncheck others of their group if clicked. No other radio buttons not intended for inclusion in that group should be on that parent control. The GUIRadioButton class has all the fields of GUIControl, plus:
Field | Subclass or Datatype | Default Settings | Description |
checked | boolean | false | determines current status of control |
GUIGraph
Fields on this specialized GUI Control are set by the external function, SetGUIGraphData().
GUITextInputBox
An input box where the user can enter text. This structure uses all the parameters of GUIPanel, plus:
Field | Subclass or Datatype | Default Settings | Description |
IsMultiLine | boolean | false | allow wordwrap, vs. all input appearing on a single line |
value | string | (none) | initial text displayed in input box |
maxLen | integer | 0 | Maximum number of characters which can be entered |
historySize | integer | 0 | The "command line history" (measured in number of commands) of a text input box |
textDefaultColor | string | NULL | The default color is black, but with an alpha value of 0, so it therefore appears transparent. For other possible values, use "#r,g,b,a" format, with float values. Example: Black text would be "#0,0,0,1" and red text would be "#1,0,0,1". 50% transparent blue text would be "#0,0,1,.5" |
readOnly | boolean | FALSE | When TRUE, the value in the text input box cannot be changed, but can still be selected |
textDisabledColor | string | NULL | Same as textDefaultColor, except active when the box is disabled (enabled=FALSE) |
See also
Scrollbar Classes
The following few classes are the individual controls required for creating a scrollbar.
GUIScrollablePanel
A GUIPanel which contains an area that can be scrolled via children controls.
Fields: All parameters of GUIPanel, plus:
Field | Subclass or Datatype | Default Settings | Description |
area | xy | 0.0, 0.0 | The actual area in which other controls can be placed. This is different from the Size attribute, which is the displayed size of the control. |
offset | xy | 0.0, 0.0 | The offset at which the area is currently positioned. This value changes when the user manipulates the scrollbar. X can range from 0 to (Area.x - Size.x), y from 0 to (Area.y - Size.y) |
scrollsby | float | 2.0 | Indicates the number of pixels that clicking up/down on the associated scrollbar will cause the panel to move. |
scrollButtonRepeat | boolean | TRUE | When set to TRUE, holding the button down will cause the scroll to continue |
autosetarea | boolean | TRUE | When TRUE, automatically adjusts area of panel based on size and position of the children controls |
allowStickyBottom | boolean | FALSE | When set to TRUE, maintains maximum vertical offset, if and only if the offset was at vertical maximum. In other words, keeps the window scrolled to the bottom, if it was already scrolled to the bottom. |
scrollbarAutoHide | boolean | TRUE | When TRUE, automatically toggles visibility of scrollbar based on whether the scrollable panel's area exceeds its size, as needed. |
GUIScrollPagePanel
This is the scrollbar part of a GUIScrollablePanel
. It is expected that a GUIScrollPagePanel
control have a GUIScrollThumb
control inside it.
Fields: Identical to GUIPanel, plus:
Field | Subclass or Datatype | Default Settings | Description |
isHorizontal | boolean | FALSE | When TRUE, the GUIScrollPagePanel controls horizontal scrolling of the GUIScrollablePanel that owns it. Otherwise, it controls vertical scrolling. |
owner | string | (none) | Can specify the path to the owning GUI Control, or an integer specifying how many parents to look through, to determine which control this affects. Set this to the ScrollablePanel which should be affected.
|
GUIScrollThumb
The bar on a scrollbar which users can drag to scroll a window. The code expects a GUIScrollThumb
to be included inside a GUIScrollPagePanel
. Set Owner and isHorizontal to match the parent GUIScrollPagePanel
.
Fields: identical to GUIScrollPagePanel
.
GUIScrollEndButton
Description: The arrow buttons on either end of a scroll bar
Fields: Identical to GUIScrollPagePanel
, plus:
Field | Subclass or Datatype | Default Settings | Description |
isHorizontal | boolean | false | Set to true if this button scrolls horizontally, otherwise it scrolls vertically. |
scrollDirection | string | (none) | determines this control's specific scroll direction (up, down, left, right) |
owner | string | (none) | Set this to the GUIScrollablePanel which should be affected.
|
GUICollection
Inherits from GUIScrollablePanel. This maintains a scrollable list. Items can be added to the list as "children", via a script.
Field | Subclass or Datatype | Default Settings | Description |
columns | integer | 0 | Specifies the number of columns |
columnWidths | string | Comma separated list of column widths in pixels. Leave the last column unspecified to have it fill the remaining space. |
Numeric Field Control Classes
- Main page: GUI Numeric Fields
GUI Sliders
This is a slider which controls the value of a different Control.
- Main page: GUI Slider Controls
See also
- GUIXML - The language used to create
- GUI Controls
- GUI Editor
- GUI Events
- State Presentation
- Gluing a GUI Control to a node
- Virtual Stage
- Creating a window
- Fonts