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 property is 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:

Creating a ButtonBar control

You create a ButtonBar control in MXML by 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>
The executing SWF file for the previous example is shown below:

This example creates a row of four Button controls, as shown in the image in ButtonBar and ToggleButtonBar controls.

To create a ToggleButtonBar control, replace the <mx:ButtonBar> tag with the <mx:ToggleButtonBar> tag. For the ToggleButtonBar control, the selectedIndex property determines which button is selected when the control is created. The default value for selectedIndex is 0 and selects the leftmost button in the bar. Setting the selectedIndex property to -1 deselects all buttons in the bar. Otherwise, the syntax is the same for both controls.

The dataProvider property specifies 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, an Array of Objects specifies 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>
The executing SWF file for the previous example is shown below:

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 the methods Container.addChild() and Container.removeChild() to add or remove Button controls. Instead, use methods addItem() and removeItem() to manipulate the dataProvider property. A ButtonBar or ToggleButtonBar control automatically adds or removes children based on changes to the dataProvider property.

Handling ButtonBar events

The ButtonBar and ToggleButtonBar controls dispatch an 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 access properties of the event object to determine the index of the selected button and other information. The index of the first button is 0. For more information about the event object, see the description of the ItemClickEvent class in the Adobe Flex Language Reference.

The ToggleButtonBar control in the following example defines an event listener, named clickHandler(), 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 var savedIndex:int = 99999;
            
            private function clickHandler(event:ItemClickEvent):void {
                if (event.index == savedIndex) {
                    myTA.text=""
                }
                else {
                    savedIndex = event.index;
                    myTA.text="Selected button index: " +
                    String(event.index) + "\n" +
                    "Selected button label: " +
                    event.label;
                }    
            }
        ]]>
    </mx:Script>
    
    <mx:ToggleButtonBar
        borderStyle="solid"
        horizontalGap="5"
        itemClick="clickHandler(event);"
        toggleOnClick="true"
        selectedIndex="-1">
        
        <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:ToggleButtonBar>

    <mx:TextArea id="myTA" width="250" height="100"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, the click handler displays the index and label of the selected button in a TextArea control in response to an itemClick event. If you press the selected button a second time, the button is deselected, and the sample click handler clears the text area.