GuiButtonBaseCtrl Class Reference
[Button Controls]

The base class for the various button controls. More...

Inheritance diagram for GuiButtonBaseCtrl:

[legend]

Public Member Functions
string	getText ()
	Get the text display on the button's label (if any).
void	performClick ()
	Simulate a click on the button.
void	resetState ()
	Reset the mousing state of the button.
void	setStateOn (bool isOn=true)
	For toggle or radio buttons, set whether the button is currently activated or not. For radio buttons, toggling a button on will toggle all other radio buttons in its group to off.
void	setText (string text)
	Set the text displayed on the button's label.
void	setTextID (string id)
	Set the text displayed on the button's label using a string from the string table assigned to the control.
Callbacks

void	onClick ()
	Called when the primary action of the button is triggered (e.g. by a left mouse click).
void	onDoubleClick ()
	Called when the left mouse button is double-clicked on the button.
void	onMouseDown ()
	If useMouseEvents is true, this is called when the left mouse button is pressed on an (active) button.
void	onMouseDragged ()
	If useMouseEvents is true, this is called when a left mouse button drag is detected, i.e. when the user pressed the left mouse button on the control and then moves the mouse over a certain distance threshold with the mouse button still pressed.
void	onMouseEnter ()
	If useMouseEvents is true, this is called when the mouse cursor moves over the button (only if the button is the front-most visible control, though).
void	onMouseLeave ()
	If useMouseEvents is true, this is called when the mouse cursor moves off the button (only if the button had previously received an onMouseEvent() event).
void	onMouseUp ()
	If useMouseEvents is true, this is called when the left mouse button is release over an (active) button.
void	onRightClick ()
	Called when the right mouse button is clicked on the button.
Public Attributes
Button

GuiButtonType	buttonType
	Button behavior type.
int	groupNum
	Radio button toggle group number. All radio buttons that are assigned the same groupNum and that are parented to the same control will synchronize their toggle state, i.e. if one radio button is toggled on all other radio buttons in its group will be toggled off.
caseString	text
	Text label to display on button (if button class supports text labels).
string	textID
	ID of string in string table to use for text label on button.
bool	useMouseEvents
	If true, mouse events will be passed on to script. Default is false.

Detailed Description

The base class for the various button controls.

This is the base class for the various types of button controls. If no more specific functionality is required than offered by this class, then it can be instantiated and used directly. Otherwise, its subclasses should be used:

GuiRadioCtrl (radio buttons)
GuiCheckBoxCtrl (checkboxes)
GuiButtonCtrl (push buttons with text labels)
GuiBitmapButtonCtrl (bitmapped buttons)
GuiBitmapButtonTextCtrl (bitmapped buttons with a text label)
GuiToggleButtonCtrl (toggle buttons, i.e. push buttons with "sticky" behavior)
GuiSwatchButtonCtrl (color swatch buttons)
GuiBorderButtonCtrl (push buttons for surrounding child controls)

Member Function Documentation

string GuiButtonBaseCtrl::getText ( )

Get the text display on the button's label (if any).

Returns:: The button's label.

void GuiButtonBaseCtrl::onClick ( )

Called when the primary action of the button is triggered (e.g. by a left mouse click).

void GuiButtonBaseCtrl::onDoubleClick ( )

Called when the left mouse button is double-clicked on the button.

void GuiButtonBaseCtrl::onMouseDown ( )

If useMouseEvents is true, this is called when the left mouse button is pressed on an (active) button.

void GuiButtonBaseCtrl::onMouseDragged ( )

If useMouseEvents is true, this is called when a left mouse button drag is detected, i.e. when the user pressed the left mouse button on the control and then moves the mouse over a certain distance threshold with the mouse button still pressed.

void GuiButtonBaseCtrl::onMouseEnter ( )

If useMouseEvents is true, this is called when the mouse cursor moves over the button (only if the button is the front-most visible control, though).

void GuiButtonBaseCtrl::onMouseLeave ( )

If useMouseEvents is true, this is called when the mouse cursor moves off the button (only if the button had previously received an onMouseEvent() event).

void GuiButtonBaseCtrl::onMouseUp ( )

If useMouseEvents is true, this is called when the left mouse button is release over an (active) button.

Note:: To trigger actions, better use onClick() since onMouseUp() will also be called when the mouse was not originally pressed on the button.

void GuiButtonBaseCtrl::onRightClick ( )

Called when the right mouse button is clicked on the button.

void GuiButtonBaseCtrl::performClick ( )

Simulate a click on the button.

This method will trigger the button's action just as if the button had been pressed by the user.

void GuiButtonBaseCtrl::resetState ( )

Reset the mousing state of the button.

This method should not generally be called.

void GuiButtonBaseCtrl::setStateOn ( bool isOn = true )

For toggle or radio buttons, set whether the button is currently activated or not. For radio buttons, toggling a button on will toggle all other radio buttons in its group to off.

Parameters:

isOn

If true, the button will be toggled on (if not already); if false, it will be toggled off.

Note:: Toggling the state of a button with this method will not not trigger the action associated with the button. To do that, use performClick().

Reimplemented in GuiCheckBoxCtrl.

void GuiButtonBaseCtrl::setText ( string text )

Set the text displayed on the button's label.

Parameters:

text

The text to display as the button's text label.

Note:: Not all buttons render text labels.

See also:: getText; setTextID

void GuiButtonBaseCtrl::setTextID ( string id )

Set the text displayed on the button's label using a string from the string table assigned to the control.

Parameters:

id

Name of the variable that contains the integer string ID. Used to look up string in table.

Note:: Not all buttons render text labels.

See also:: setText; getText; GuiControl::langTableMod; LangTable

Internationalization

Member Data Documentation

GuiButtonType GuiButtonBaseCtrl::buttonType

Button behavior type.

int GuiButtonBaseCtrl::groupNum

Radio button toggle group number. All radio buttons that are assigned the same groupNum and that are parented to the same control will synchronize their toggle state, i.e. if one radio button is toggled on all other radio buttons in its group will be toggled off.

The default group is -1.

caseString GuiButtonBaseCtrl::text

Text label to display on button (if button class supports text labels).

string GuiButtonBaseCtrl::textID

ID of string in string table to use for text label on button.