ButtonBar and ToggleButtonBar controls -- Flex 2.01

The ButtonBar and ToggleButtonBar controls define a horizontal or vertical row of related buttons with a common appearance. The controls define a single event, the itemClick event, that is dispatched when any button in the control is selected.

The ButtonBar control defines group of buttons that do not retain a selected state. When you select a button in a ButtonBar control, the button changes its appearance to the selected state; when you release the button, it returns to the deselected state.

The ToggleButtonBar control defines a group buttons that maintain their state, either selected or deselected. Only one button in the ToggleButtonBar control can be in the selected state. That means when you select a button in a ToggleButtonBar control, the button stays in the selected state until you select a different button.

If you set the toggleOnClick property of the ToggleButtonBar control to true, selecting the currently selected button deselects it. By default the toggleOnClick properties false.

The following image shows an example of a ButtonBar control that defines a set of buttons:

The following image shows an example of a ToggleButtonBar control that defines a set of buttons, where the Dreamweaver button is the currently selected button in the control:

Property	Default value
Preferred size	Wide enough to contain all buttons with their label text and icons, if any, plus any padding and separators, and high enough to accommodate the button height.
Control resizing rules	The controls do not resize by default. Specify percentage sizes if you want your ButtonBar to resize based on the size of its parent container.
Padding	0 pixels for the `top`, `bottom`, `left`, and `right` properties.

Subtopics

Creating a ButtonBar control

You create a ButtonBar control in MXML using the <mx:ButtonBar> tag, as the following example shows:

<?xml version="1.0"?>
<!-- controls\bar\BBarSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >

    <mx:ButtonBar borderStyle="solid" horizontalGap="5">
        <mx:dataProvider>
            <mx:String>Flash</mx:String>
            <mx:String>Director</mx:String>
            <mx:String>Dreamweaver</mx:String>
            <mx:String>ColdFusion</mx:String>
        </mx:dataProvider>
    </mx:ButtonBar>
</mx:Application>

To create a ToggleButtonBar control, replace the <mx:ButtonBar> tag with the <mx:ToggleButtonBar> tag. Otherwise, the syntax is the same for both controls.

You use the dataProvider property to specify the labels of the four buttons. You can also populate the dataProvider property with an Array of Objects; where each object can have up to three fields: label, icon, and tooltip.

In the following example, you use an Array of Objects to specify a label and icon for each button:

<?xml version="1.0"?>
<!-- controls\bar\BBarLogo.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:ButtonBar borderStyle="solid" horizontalGap="5">
        <mx:dataProvider>
            <mx:Object label="Flash" 
                icon="@Embed(source='assets/Flashlogo.gif')"/>
            <mx:Object label="Director" 
                icon="@Embed(source='assets/Dirlogo.gif')"/>
            <mx:Object label="Dreamweaver" 
                icon="@Embed(source='assets/Dlogo.gif')"/>
            <mx:Object label="ColdFusion" 
                icon="@Embed(source='assets/CFlogo.gif')"/>
        </mx:dataProvider>
    </mx:ButtonBar>
</mx:Application>

A ButtonBar or ToggleButtonBar control creates Button controls based on the value of its dataProvider property. Even though ButtonBar and ToggleButtonBar are subclasses of Container, do not use methods such as Container.addChild() and Container.removeChild() to add or remove Button controls. Instead, use methods such as addItem() and removeItem() to manipulate the dataProvider property. A ButtonBar or ToggleButtonBar control automatically adds or removes the necessary children based on changes to the dataProvider property.

Handling ButtonBar events

The ButtonBar and ToggleButtonBar controls dispatch a itemClick event when you select a button. The event object passed to the event listener is of type ItemClickEvent. From within the event listener, you can access properties of the event object to determine the index of the selected button, where the first button is at index 0, and other information. For more information on the event object, see the description of the ItemClickEvent class in Adobe Flex 2 Language Reference.

The ButtonBar control in the following example defines an event listener for the itemClick event:

<?xml version="1.0"?>
<!-- controls\bar\BBarEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >

    <mx:Script>
        <![CDATA[            
            import mx.events.ItemClickEvent;    
            
            private function clickHandler(event:ItemClickEvent):void {
                myTA.text="Selected button index: " + 
                    String(event.index) + "\n" + 
                    "Selected button label: " + 
                    event.label;
            }
        ]]>
    </mx:Script>

    <mx:TextArea id="myTA" width="200" height="100"/>

    <mx:ButtonBar 
        borderStyle="solid" 
        horizontalGap="5" 
        itemClick="clickHandler(event);">
        <mx:dataProvider>
            <mx:String>Flash</mx:String>
            <mx:String>Director</mx:String>
            <mx:String>Dreamweaver</mx:String>
            <mx:String>ColdFusion</mx:String>
        </mx:dataProvider>
    </mx:ButtonBar>
</mx:Application>

In this example, the event listener displays the index and label of the selected button in a TextArea control in response to a itemClick event.