Packagecom.ghostwire.ui.controls
Classpublic class uiButtonGroup
InheritanceuiButtonGroup Inheritance flash.events.EventDispatcher

The 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 ~



Public Properties
 PropertyDefined 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
Public Methods
 MethodDefined by
  
uiButtonGroup(... members)
Constructor - creates a new uiButtonGroup instance.
uiButtonGroup
  
addButton(button:uiButton):void
Adds the indicated uiButton instance to this group.
uiButtonGroup
  
removeButton(button:uiButton):void
Removes the indicated uiButton instance from this group.
uiButtonGroup
Events
 EventSummaryDefined by
   Dispatched when the selected uiButton instance in this group changes.uiButtonGroup
Property detail
membersproperty
members:Array  [read-only]

Returns an array of the uiBbutton instances in this group.

Implementation
    public function get members():Array
selectedButtonproperty 
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.

Implementation
    public function get selectedButton():uiButton
    public function set selectedButton(value:uiButton):void
selectedDataproperty 
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).

Implementation
    public function get selectedData():Object
    public function set selectedData(value:Object):void
selectedIndexproperty 
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.

Implementation
    public function get selectedIndex():int
    public function set selectedIndex(value:int):void
toggleproperty 
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.

Implementation
    public function get toggle():Boolean
    public function set toggle(value:Boolean):void
Constructor detail
uiButtonGroup()constructor
public function uiButtonGroup(... members)

Constructor - creates a new uiButtonGroup instance.

Parameters
... members — A comma-delimited list of uiButton instances, typically but not necessarily uiRadioButton instances, to register as initial members of this uiButtonGroup instance.
Method detail
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.

Parameters
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.

Parameters
button:uiButton
Event detail
changeevent 
Event object type: flash.events.Event

Dispatched when the selected uiButton instance in this group changes.