ToggleButton

A switch button with an on and off state.  The button can toggle independently or be part of a group of ToggleButtons where only one can be on at a time.

See also

BubbleButton, LabelButton, ShapeButton.

Summary
ToggleButtonA switch button with an on and off state.
Public constants
DEFAULT_SIZEDefault button diameter in pixels
defaultColorDefault button base color
Private toggle groups
groupsStatic class level array of toggle groups.
groupIdGroup reference for this button instance, null if independent.
Private state shapes
downOnStateButton shape shown when the button is pressed down and its state is on
upOnStateButton shape shown when the button is not pressed down and its state is on
downOffStateButton shape shown when the button is pressed down and its state is off
upOffStateButton shape shown when the button is not pressed down and its state is off
Private data members
lastStateReference to the last state shape the button has been shown with
callbackFunction called when the button changes state
toggleStateCurrent boolean state of this button
toggleLabelText label shown to convey the function of the button
Constructor
ToggleButtonCreates a switch button that a user can toggle on or off.
Public properties
textChange the text of the button label
stateGet the current state of the toggle button
stateSet the state of the toggle button programmatically.
Internal Group methods
addToGroupAdds a button instance to a group
removeFromGroupRemoves a button instance from a group
propagateToGroupPropagates a state change for a button instance throughout a group
findGroupFinds the internal group instance with the id of the given <groupObj>.
Event handlers
mouseDownHandlerChange state when the button is pressed
mouseUpHandlerChange state when the button is released
mouseClickHandlerButton click handler calls back to user supplied handler if present
WidgetInterface
activeSets the state of the widget to active or inactive.
activateActivates the widget, adds its event listeners
disactivateDisactivates the widget, removes its event listeners
disposeDispose of all resources used or referenced in the instance.
destructorRemoves used resources, references and graphics

Public constants

DEFAULT_SIZE

public static const DEFAULT_SIZE: uint

Default button diameter in pixels

defaultColor

public static const defaultColor: int

Default button base color

Private toggle groups

groups

private static var groups: Array

Static class level array of toggle groups.  Each element is a dynamic object with an id property holding the group object reference and an array of button instance references belonging to the group.

Since there is only one array in an application globally reachable objects such as the stage such not be used to indicate a group.  It is better to use a reference to for example a Label describing the group or if there is only one group in a class then the this reference.

groupId

private var groupId: Object

Group reference for this button instance, null if independent.

Private state shapes

downOnState

private var downOnState: Shape

Button shape shown when the button is pressed down and its state is on

upOnState

private var upOnState: Shape

Button shape shown when the button is not pressed down and its state is on

downOffState

private var downOffState: Shape

Button shape shown when the button is pressed down and its state is off

upOffState

private var upOffState: Shape

Button shape shown when the button is not pressed down and its state is off

Private data members

lastState

private var lastState: DisplayObject

Reference to the last state shape the button has been shown with

callback

private var callback: Function

Function called when the button changes state

toggleState

private var toggleState: Boolean

Current boolean state of this button

toggleLabel

private var toggleLabel: Label

Text label shown to convey the function of the button

Constructor

ToggleButton

public function ToggleButton(owner: String,  
labelText: String,  
color: uint = Color.Grey,
labelColor: uint = defaultColor,
groupObject: Object = null,
clickHandler: Function = null,
initialState: Boolean = false,
size: uint = DEFAULT_SIZE,
customOnShapeFunction: Function = null,
customOffShapeFunction: Function = null)

Creates a switch button that a user can toggle on or off.  The default visual representation is as a small bubble button with a dot in it when it is selected.  Groups of toggles can be created that switches off other buttons in the group when a new is selcted.

Parameters

ownername of registered owner; see WidgetSprite.register
labelTextText indicating the function of the button, null for no label (default)
colorbase theme color for the button
labelColorcolor for the label text
groupObjectreference to an object (such as this or a label) if belonging to a group (default null)
clickHandlera callback function that is called when the button changes state
initialStatetrue if the button is on initially, false otherwise (default false)
sizewidth the button, determines default size and label placement (default 15)
customOnShapeFunctionfunction returning a graphics shape for the button on state (default null)
customOffShapeFunctionfunction returning a graphics shape for the button off state (default null)

Callbacks

clickHandlerfunction onToggleButtonClick(state:Boolean):void

Public properties

text

public function set text(labelText: String):void

Change the text of the button label

Parameters

labelTextnew text to display for the button

state

public function get state():Boolean

Get the current state of the toggle button

Returns

True if on, false if off

state

public function set state(value: Boolean):void

Set the state of the toggle button programmatically.

If the button has a state callback then it is called.  If the button is belongs to a group then the change is propagated throughout the group.

Parameters

valuetrue for on, false for off

Internal Group methods

addToGroup

private function addToGroup(groupObj: Object,
thisInstance: ToggleButton):void

Adds a button instance to a group

Parameters

groupObjreference to a group object
thisInstancereference to this button instance

removeFromGroup

private function removeFromGroup(groupObj: Object,
thisInstance: ToggleButton):void

Removes a button instance from a group

Parameters

groupObjreference to a group object
thisInstancereference to this button instance

propagateToGroup

private function propagateToGroup(groupObj: Object,
thisInstance: ToggleButton):void

Propagates a state change for a button instance throughout a group

Parameters

groupObjreference to a group object
thisInstancereference to this button instance

findGroup

private function findGroup(groupObj: Object):Object

Finds the internal group instance with the id of the given <groupObj>.

It is currently a linear search based on the assumption that there are relatively few groups in an application.

Parameters

groupObjreference to a group object

Returns

a reference to the internal dynamic group if found, null otherwise

Event handlers

mouseDownHandler

private function mouseDownHandler(event: MouseEvent):void

Change state when the button is pressed

Parameters

eventa mouse event

mouseUpHandler

private function mouseUpHandler(event: MouseEvent):void

Change state when the button is released

Parameters

eventa mouse event

mouseClickHandler

private function mouseClickHandler(event: MouseEvent):void

Button click handler calls back to user supplied handler if present

Parameters

eventa mouse event

WidgetInterface

active

public function set active(state: Boolean):void

Sets the state of the widget to active or inactive.

Parameters

stateTrue to activate, false otherwise.

activate

private function activate():void

Activates the widget, adds its event listeners

disactivate

private function disactivate():void

Disactivates the widget, removes its event listeners

dispose

public function dispose():void

Dispose of all resources used or referenced in the instance.

destructor

private function destructor():void

Removes used resources, references and graphics

Widgets are required to implement this interface.
Base class for widgets to enable/disable event listeners and keep a global tab order of all widgets (provided they are created and registered in tab order.
public static const DEFAULT_SIZE: uint
Default button diameter in pixels
public static const defaultColor: int
Default button base color
private static var groups: Array
Static class level array of toggle groups.
private var groupId: Object
Group reference for this button instance, null if independent.
private var downOnState: Shape
Button shape shown when the button is pressed down and its state is on
private var upOnState: Shape
Button shape shown when the button is not pressed down and its state is on
private var downOffState: Shape
Button shape shown when the button is pressed down and its state is off
private var upOffState: Shape
Button shape shown when the button is not pressed down and its state is off
private var lastState: DisplayObject
Reference to the last state shape the button has been shown with
private var callback: Function
Function called when the button changes state
private var toggleState: Boolean
Current boolean state of this button
private var toggleLabel: Label
Text label shown to convey the function of the button
public function ToggleButton(owner: String,  
labelText: String,  
color: uint = Color.Grey,
labelColor: uint = defaultColor,
groupObject: Object = null,
clickHandler: Function = null,
initialState: Boolean = false,
size: uint = DEFAULT_SIZE,
customOnShapeFunction: Function = null,
customOffShapeFunction: Function = null)
Creates a switch button that a user can toggle on or off.
public function set text(labelText: String):void
Change the text of the button label
public function get state():Boolean
Get the current state of the toggle button
private function addToGroup(groupObj: Object,
thisInstance: ToggleButton):void
Adds a button instance to a group
private function removeFromGroup(groupObj: Object,
thisInstance: ToggleButton):void
Removes a button instance from a group
private function propagateToGroup(groupObj: Object,
thisInstance: ToggleButton):void
Propagates a state change for a button instance throughout a group
private function findGroup(groupObj: Object):Object
Finds the internal group instance with the id of the given groupObj.
private function mouseDownHandler(event: MouseEvent):void
Change state when the button is pressed
private function mouseUpHandler(event: MouseEvent):void
Change state when the button is released
private function mouseClickHandler(event: MouseEvent):void
Button click handler calls back to user supplied handler if present
public function set active(state: Boolean):void
Sets the state of the widget to active or inactive.
private function activate():void
Activates the widget, adds its event listeners
private function disactivate():void
Disactivates the widget, removes its event listeners
public function dispose():void
Dispose of all resources used or referenced in the instance.
private function destructor():void
Removes used resources, references and graphics
An action button drawn as a bubble with an optional symbol on top.
A button widget with a slightly raised look and a label text on it.
A button widget with a slightly raised look and an optional graphics shape placed above an optional label text.
A static text label.
public function register(owner: String):void
Register the owner of a widget.
Close