How to use the TabBar component

The TabBar class displays a set of togglable buttons in a row, where only one button at a time may be selected. The tabs are populated from a data collection.

Live preview of the TabBar component

The Basics

Start by creating a TabBar control, and add it to the display list.

var tabs = new TabBar();
addChild(tabs);

Data provider

To render some data in the tab bar, pass in a collection that contains an object for each tab.

tabs.dataProvider = new ArrayCollection([
    { text: "A" },
    { text: "B" },
    { text: "C" }
]);

Set the itemToText() method to get the text from each item to display in a tab.

tabs.itemToText = function(item:Dynamic):String {
    return item.text;
};

Items in the collection are not required to be anonymous structures, like in the example above. Class instances are allowed too (and encouraged as a best practice; you should prefer classes over anonymous structures).

Selection

Add an event listener for Event.CHANGE to perform an action when the user selects a different tab.

tabs.addEventListener(Event.CHANGE, tabBar_changeHandler);

Check for the new value of the selectedItem property in the listener.

function tabBar_changeHandler(event:Event):Void {
    var tabs = cast(event.currentTarget, TabBar);
    trace("TabBar selectedItem change: " + tabs.selectedItem.text);
}

Alternatively, the value of the selectedIndex property references the index of the items in the tab bar, in the order that they were added.

function tabBar_changeHandler(event:Event):Void {
    var tabs = cast(event.currentTarget, TabBar);
    trace("TabBar selectedIndex change: " + tabs.selectedIndex);
}

Add or remove tabs

To add a new tab at the end, pass an object to the data provider's add() method.

var newItem = { text: "New Tab" };
tabs.dataProvider.add(newItem);

To add a new tab at a specific position, pass an object to the data provider's addAt() method.

var newItem = { text: "First Tab" };
tabs.dataProvider.addAt(newItem, 0);

In the example above, a new tab is added to the beginning.

Similarly, to remove a tab, call remove() or removeAt() on the collection.

tabs.dataProvider.removeAt(0);

Styles

The tabs in a TabBar component may be styled to change its appearance.

Tabs

The tabs in a TabBar component are of type ToggleButton. Their appearance may be customized globally in a theme, or they may be customized outside of a theme on an specific, individual tab bar.

See How to use the ToggleButton component for complete details about which styles are available for the tabs.

Style tabs globally

Use the TabBar.CHILD_VARIANT_TAB constant in a theme to provide a function that globally styles the tabs in all TabBar components.

styleProvider.setStyleFunction(
    ToggleButton,
    TabBar.CHILD_VARIANT_TAB,
    setTabBar_Tab_Styles);

The function should use the following signature.

function setTabBar_Tab_Styles(tab:ToggleButton):Void {
    // ... set styles here
}

Style tabs in a specific TabBar

Customize the tabRecycler property to customize the styles of the tabs in a specific TabBar component.

tabs.tabRecycler = DisplayObjectRecycler.withFunction(() -> {
    var tab = new ToggleButton();
    // ... set styles here
    return tab;
});