GUI Controls

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(changed links to GUI_Editor#Presentation_States)
(GUILabel)
Line 355: Line 355:
 
|-
 
|-
 
| displayFont||enum font ||DEFAULTTEXT  || An enumerated value which specifies the font
 
| 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)
 
|}
 
|}
  

Revision as of 16:27, 25 January 2012

Contents

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 This is an anti-aliasing filter. When set to TRUE, anti-aliasing is turned on.
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 tree directory view of the GUI Editor

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:


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

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox