buttoncontrol
- Derek Batting
- John Gregory
Inherits | |
Inherited By | buttonfield |
Context | windowinstance |
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 overridden.
Definition
<buttoncontrol >
<allowdoubleclick />
<color > ... </color>
<font > ... </font>
<hover > ... </hover>
<icon >
<normal > ... </normal>
<pressed > ... </pressed>
<hover > ... </hover>
</icon>
<pressed > ... </pressed>
<state >
<color > ... </color>
<font > ... </font>
<frame > ... </frame>
<frameoffset > ... </frameoffset>
<icon > ... </icon>
<offset > ... </offset>
<text > ... </text>
<textres > ... </textres>
<tooltip > ... </tooltip>
<tooltipres > ... </tooltipres>
</state>
<text > ... </text>
<textres > ... </textres>
</buttoncontrol><buttoncontrol > |
|
| If defined, then double clicks will trigger script onDoubleClick events; otherwise, double clicks will be treated as two separate single click events. |
<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
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
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
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
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
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
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
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
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
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
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