Button controls create buttons that respond to simple click events.
Buttons can be defined as simple graphical or textual buttons, or defined as multi-state buttons. Each state can have its own unique look.
The value of a button is a numerical value equal to zero (if simple button) or the state (if multi-state). For multi-state buttons, the order of the state definitions sets the value associated with the state, starting at zero.
- All tags for defining a single state button can be replaced by using a single state tag.
- If at least one state tag is defined, then the icon tag will be ignored.
- If both an icon and text are defined for a given state, then only the icon will be displayed.
- If a tooltip is specified for the first state, it will be used for all states unless overriden.
Definition
|
<buttoncontrol
>
|
|
|
<color
>
...
</color>
|
Override color to be used when displaying text or icons (either single state or multi-state) |
|
<font
>
...
</font>
|
Font resource for displaying text (either single state or multi-state) |
|
<hover
>
...
</hover>
|
Defines appearance of button when mouse hovering over at the current state (for multi-state buttons) This tag supports the same subtags as the state tag. |
|
<icon
>
|
Icon resources to display on control (for single state buttons) (ignored if any state tags defined) |
|
<normal
>
...
</normal>
|
The icon for the normal state |
|
<pressed
>
...
</pressed>
|
The icon for the pressed state |
|
<hover
>
...
</hover>
|
The icon for the hover state |
|
</icon>
|
|
|
<pressed
>
...
</pressed>
|
Defines appearance of button when pressed at the current state (for multi-state buttons). This tag supports the same subtags as the state tag. |
|
<state
>
|
Defines appearance of button at the current state (for multi-state buttons) |
|
<color
>
...
</color>
|
Override color for text/icon display. Supercedes main color tag. |
|
<font
>
...
</font>
|
Font resource for displaying text. Supercedes main font tag. |
|
<frame
>
...
</frame>
|
Frame resource to be displayed as background. |
|
<frameoffset
>
...
</frameoffset>
|
Comma separated list of four numbers specifying the pixel margins applied to the frame. (left, top, right, bottom) |
|
<icon
>
...
</icon>
|
Icon resource to be displayed. |
|
<offset
>
...
</offset>
|
Comma separated list of two numbers specifying the offset applied to the display any resources displayed. (X offset, Y offset) |
|
<text
>
...
</text>
|
Text to be displayed. |
|
<textres
>
...
</textres>
|
String resource to be displayed. |
|
<tooltip
>
...
</tooltip>
|
Text to be displayed when hovering over button. |
|
<tooltipres
>
...
</tooltipres>
|
String resource to be displayed when hovering over button. |
|
</state>
|
|
|
<text
>
...
</text>
|
Text to display on control (either single state or multi-state) |
|
<textres
>
...
</textres>
|
String resource to display on control (either single state or multi-state) |
|
</buttoncontrol>
|
|
Interface
getValue
function getValue()
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Retrieves the value of the control.
Return values
(number)
The value contained in the control
onButtonPress
function onButtonPress()
If present, this function is called when the buttoncontrol is pressed. (i.e. mouse clicked and released on button)
onValueChanged
function onValueChanged()
Is called when the underlying value referenced by the control changes. This may result from changes outside of direct editing by this control. (i.e. via ruleset script or another control accessing same database value)
setColor
function setColor(color)
Sets the color used to draw the button icons or text by default. The color is used to modulate the pixel colors of the bitmap images.
Parameters
color (string)
A color value in the form "AARRGGBB" where the components are hexadecimal digits specifying the alpha (transparency),
red, green and blue channels, respectively, in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
setIcons
function setIcons(normal, pressed, [hover])
Sets the names of the icon resources used for drawing the control. This will override the control definition, and reset button to have a single state.
Parameters
normal (string)
Icon resource for the normal state
pressed (string)
Icon resource for the pressed state
hover (string) [optional]
Icon resource for the hover state
setStateColor
function setStateColor(index, normal, pressed, hover)
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the color used to draw the button icons or text in the specified numeric state. The color is used to modulate the pixel colors of the bitmap images.
Parameters
index (number)
Numerical button value
normal (string)
A color value in the form "AARRGGBB" where the components are hexadecimal digits specifying the alpha (transparency),
red, green and blue channels, respectively, in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
pressed (string)
A color value in the form "AARRGGBB" where the components are hexadecimal digits specifying the alpha (transparency),
red, green and blue channels, respectively, in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
hover (string)
A color value in the form "AARRGGBB" where the components are hexadecimal digits specifying the alpha (transparency),
red, green and blue channels, respectively, in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
setStateIcons
function setStateIcons(index, normal, pressed, [hover])
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the names of the icon resources used for drawing the control in the specified numeric state. This will override the control definition for the specified state (if any). Specifying a numeric index greater than zero will set button to multiple states.
Parameters
index (number)
Numerical button value
normal (string)
Icon resource for the normal state
pressed (string)
Icon resource for the pressed state
hover (string) [optional]
Icon resource for the hover state
setStateText
function setStateText(index, normal, pressed, [hover])
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the text to be used for drawing the control in the specified numeric state. This will override the control definition for the specified state (if any). Specifying a numeric index greater than zero will set button to multiple states.
Parameters
index (number)
Numerical button value
normal (string)
Text for the normal state
pressed (string)
Text for the pressed state
hover (string) [optional]
Text for the hover state
setStateTooltipText
function setStateTooltipText(index, tooltip)
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the tooltip text to be displayed when hovering over the control in the specified numeric state. This will override the control definition for the specified state (if any).
Parameters
index (number)
Numerical button value
tooltip (string)
Tooltip to display on hover
setText
function setText(normal, pressed, [hover])
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the text to be used for drawing the control. This will override the control definition, and reset button to have a single state.
Parameters
normal (string)
Text for the normal state
pressed (string)
Text for the pressed state
hover (string) [optional]
Text for the hover state
setTooltipText
function setTooltipText(tooltip)
Sets the tooltip text to be displayed when hovering over the control. This will override the control definition, and reset all tooltips in a multi state button.
Parameters
tooltip (string)
Tooltip to display on hover
setValue
function setValue(value)
Note: Only available for rulesets with compatibility mode v3.0 or higher.
Sets the value of the button control. If the value specified is greater than the number of button states defined, then the value is set to zero instead.
Parameters
value (number)
The value to set the control to
