GUI Controls

From HEWIKI

(Redirected from Technical:Graphical Controls)

Jump to: navigation, search

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)

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