Package | com.ghostwire.ui.controls |
Class | public class uiButtonGroup |
Inheritance | uiButtonGroup ![]() |
uiButtonGroup
class represents a set of mutually exclusive uiButton
choices. When you create a set of buttons with their group
property set to the same
uiButtonGroup
object, only one of those buttons can be selected at any one time. When you
assign a uiButton
instance to a uiButtonGroup
(via its group
property) its toggle
property will be set to true
automatically.
Typically, this class is used to group a set of uiRadioButton
objects, but you can
actually set up a group using any uiButton
instances.
Note that uiButtonGroup
is a logical group; it is not a physical container and therefore
does not have a visual representation (you still need to add the uiButton
members to the
display list). Example:
// create the uiRadioButton instances var rb1:uiRadioButton = new uiRadioButton("choice 1"); var rb2:uiRadioButton = new uiRadioButton("choice 2"); var rb3:uiRadioButton = new uiRadioButton("choice 3"); // register the uiRadioButton instances to a uiButtonGroup instance var rbGroup:uiButtonGroup = new uiButtonGroup(rb1,rb2,rb3); // make choice 2 the initial choice rbGroup.selectedButton = rb2; // add the uiRadioButton instances to a uiBox layout container vertically aligned var rbList:uiBox = new uiBox(); rbList.addChild(rb1); rbList.addChild(rb2); rbList.addChild(rb3); rbList.vertical = true;
Tab Focus
Where tab focus management is concerned, only the selected button will be included in the tab order.
Once the selected button has focus, the user can use the UP
, DOWN
,
LEFT
and RIGHT
arrow keys to select another button (moving the focus via
the arrow keys selects the focused button). A disabled button cannot be focused/selected.
Note that if your application disables a button that is already selected, the whole group will not
be accessible via the TAB
key but still accessible via the mouse. This is considered an
application design error rather than a framework bug because it is illogical to disable a selected
button on its own. If you want the button group to be disabled, you should disable the container
containing the buttons thereby disabling all the buttons within. If you need to disable a choice
that is already selected, consider setting the selection to another button or clearing the
selection.
If none of the members are selected, the first member in the group will be included in the tab focus chain, or in the case whereby a member was previously selected and the selection is subsequently cleared, the last member selected will be included in the tab focus chain.
~ This class is available in Aspire UI Components Lite Edition ~
Property | Defined by | ||
---|---|---|---|
members : Array [read-only]
Returns an array of the
uiBbutton instances in this group. | uiButtonGroup | ||
selectedButton : uiButton
Indicates the currently selected
uiButton instance. | uiButtonGroup | ||
selectedData : Object
Indicates the data associated with the currently selected
uiButton instance. | uiButtonGroup | ||
selectedIndex : int
Indicates the index position of the selected button in the group.
| uiButtonGroup | ||
toggle : Boolean
By default, a selected member in the group will stay selected when it is clicked (ie it will not toggle between
selected and deselected states, which means that once a member is selected, at least one member will be selected
at any one time).
| uiButtonGroup |
Method | Defined by | ||
---|---|---|---|
uiButtonGroup(... members)
Constructor - creates a new
uiButtonGroup instance. | uiButtonGroup | ||
Adds the indicated
uiButton instance to this group. | uiButtonGroup | ||
removeButton(button:uiButton):void
Removes the indicated
uiButton instance from this group. | uiButtonGroup |
Event | Summary | Defined by | ||
---|---|---|---|---|
Dispatched when the selected uiButton instance in this group changes. | uiButtonGroup |
members | property |
members:Array
[read-only]
Returns an array of the uiBbutton
instances in this group.
public function get members():Array
selectedButton | property |
selectedButton:uiButton
[read-write]
Indicates the currently selected uiButton
instance. To clear the selection in the
group such that no button is selected, set this property to null
.
public function get selectedButton():uiButton
public function set selectedButton(value:uiButton):void
selectedData | property |
selectedData:Object
[read-write]
Indicates the data associated with the currently selected uiButton
instance. If no
button is currently selected, or the currently selected button does not have its
data
property defined, this property returns null
.
Setting this property to value
will select the button whose data
property
has been set to value
. If no such button exists, nothing happens (currently selected
button, if any, remains selected).
public function get selectedData():Object
public function set selectedData(value:Object):void
selectedIndex | property |
selectedIndex:int
[read-write]Indicates the index position of the selected button in the group. This is the logical index position in the group, not necessarily the same as the physical index in the container.
A value of -1
indicates that no button is selected.
The default value is -1
.
public function get selectedIndex():int
public function set selectedIndex(value:int):void
toggle | property |
toggle:Boolean
[read-write]
By default, a selected member in the group will stay selected when it is clicked (ie it will not toggle between
selected and deselected states, which means that once a member is selected, at least one member will be selected
at any one time). Set this property to true
if the intended behavior is for a member to toggle between
selected and deselected states when clicked (which means it is possible for none of the members to be selected).
Required: Version 1.0.10
The default value is false
.
public function get toggle():Boolean
public function set toggle(value:Boolean):void
uiButtonGroup | () | constructor |
public function uiButtonGroup(... members)
Constructor - creates a new uiButtonGroup
instance.
... members — A comma-delimited list of uiButton instances, typically but not
necessarily uiRadioButton instances, to register as initial members of this
uiButtonGroup instance.
|
addButton | () | method |
public function addButton(button:uiButton):void
Adds the indicated uiButton
instance to this group. You do not need to call this
method directly; it is done automatically when you set the group
property of the
uiButton
instance.
button:uiButton |
removeButton | () | method |
public function removeButton(button:uiButton):void
Removes the indicated uiButton
instance from this group. You do not need to call this
method directly; it is done automatically when you set the group
property of the
uiButton
instance.
button:uiButton |
change | event |
flash.events.Event
Dispatched when the selected uiButton
instance in this group changes.