How to use the ButtonGroup component (Starling version)

The ButtonGroup class displays a set of buttons displayed one after the other in a simple horizontal or vertical layout. It is best used for a set of related buttons that generally look the same and are meant to be displayed together meaningfully. For instance, an alert dialog populates its OK/Cancel/Yes/No/etc. buttons using a ButtonGroup.

Screenshot of Feathers a ButtonGroup component — A `ButtonGroup` component skinned with `MetalWorksMobileTheme`

The Basics
Skinning a ButtonGroup

The Basics

First, let's create a ButtonGroup control and add it to the display list:

var group:ButtonGroup = new ButtonGroup();
this.addChild(group);

This won't display anything because we haven't populated the data provider with information about the buttons we want. Let's do that next:

group.dataProvider = new ArrayCollection(
[
    { label: "One", triggered: oneButton_triggeredHandler },
    { label: "Two", triggered: twoButton_triggeredHandler },
    { label: "Three", triggered: threeButton_triggeredHandler },
]);

Like the List or TabBar components, the ButtonGroup uses an implementation of IListCollection, such as ArrayCollection or VectorCollection, as its data provider.

A number of fields in each item from the collection are automatically detected by the button group. For instance, we set the label on each button above. Each of a button's icon states may also be used here, along with isToggle and isSelected to make them into toggling buttons.

For full details about which properties can be set on tabs, see the description of the dataProvider property.

Additionally, we can add a few event listeners to each button, including Event.TRIGGERED and Event.CHANGE (using the String values, triggered and change). In the example above, we add a listener to triggered. The listener on the first item might look something like this:

function oneButton_triggeredHandler( event:Event ):void
{
    var button:Button = Button( event.currentTarget );
    trace( "button triggered:", button.label );
}

Skinning a `ButtonGroup`

A button group's buttons may all be skinned, with the first and last buttons having optional custom styles. A few other properties exist to customize the layout. For full details about which properties are available, see the ButtonGroup API reference. We'll look at a few of the most common ways of styling a button group below.

Layout

The ButtonGroup has a strict horizontal or vertical layout that you can customize using the direction property. Additionally, you can set the gap between buttons, including special gaps for the first and last buttons.

group.direction = Direction.VERTICAL;
group.gap = 10;
group.lastGap = 20;

The firstGap and lastGap are completely optional, and if they are not defined, the regular gap value will be used.

With a vertical layout, each button's width will match the width of the button group. Similarly, with a horizontal layout, the buttons will fill the entire height.

Skinning the Buttons

This section only explains how to access the button sub-components. Please read How to use the Button component for full details about the skinning properties that are available on Button components.

With a Theme

If you're creating a theme, you can target the ButtonGroup.DEFAULT_CHILD_STYLE_NAME_BUTTON style name.

getStyleProviderForClass( Button )
    .setFunctionForStyleName( ButtonGroup.DEFAULT_CHILD_STYLE_NAME_BUTTON, setButtonGroupButtonStyles );

The styling function might look like this:

private function setButtonGroupButtonStyles( button:Button ):void
{
    var skin:ImageSkin = new ImageSkin( texture );
    skin.scale9Grid = new Rectangle( 2, 3, 1, 6 );
    button.defaultSkin = skin;
    button.fontStyles = new TextFormat( "Helvetica", 20, 0x3c3c3c );
}

You can override the default style name to use a different one in your theme, if you prefer:

group.customButtonStyleName = "my-custom-button";

You can set the styling function for the customButtonStyleName like this:

getStyleProviderForClass( Button )
    .setFunctionForStyleName( "my-custom-button", setButtonGroupCustomButtonStyles );

Without a Theme

If you are not using a theme, you can use buttonFactory to provide skins for the buttons:

group.buttonFactory = function():Button
{
    var button:Button = new Button();

    //skin the buttons here, if you're not using a theme
    var skin:ImageSkin = new ImageSkin( texture );
    skin.scale9Grid = new Rectangle( 2, 3, 1, 6 );
    button.defaultSkin = skin;
    button.fontStyles = new TextFormat( "Helvetica", 20, 0x3c3c3c );

    return button;
};

Skinning the First and Last Buttons

This section only explains how to access the first and last button sub-components. Please read How to use the Button component for full details about the skinning properties that are available on Button components.

The button group's first and last buttons will have the same skins as the other buttons by default. However, their skins may be customized separately, if desired.

For the first button, you can customize the style name with customFirstButtonStyleName. If you aren't using a theme, then you can use firstButtonFactory.

For the last button, you can customize the style name with customLastButtonStyleName. If you aren't using a theme, then you can use lastButtonFactory.

Separate skins for the first and last buttons are completely optional.

feathers.controls.ButtonGroup API Documentation