How to use the MenuBar component

The MenuBar class displays a row of top-level menu items that, when triggered, display pop-up menus.

The Basics

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

var menuBar = new MenuBar();
addChild(menuBar);

Data provider

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

var collection = new ArrayHierarchicalCollection([
    {
        text: "File",
        children: [
            { text: "New" },
            { text: "Open" },
            { separator: true },
            { text: "Print" },
            { separator: true },
            { text: "Exit" },
        ]
    },
    {
      text: "Edit",
      children: [
          { text: "Undo" },
          { text: "Redo" },
          { separator: true },
          { text: "Cut" },
          { text: "Copy" },
          { text: "Paste" }
      ]
    },
    {
      text: "View",
      children: [
          { text: "Full Screen" },
      ]
    }
]);
menuBar.dataProvider = collection;

Set the collection's itemToChildren() method to get the children from each branch that need to be rendered by the menu bar.

collection.itemToChildren = (item:Dynamic) -> item.children;

Set the itemToText() method to get the text from each item to display from the collection.

menuBar.itemToText = (item:Dynamic) -> item.text;

Set the itemToSeparator() method to determine if any of the items in the collection represent a separator.

menuBar.itemToSeparator = (item:Dynamic) -> item.separator == true;

Items in the collection are not required to be anonymous structures, like {text: "Open"} in the example above. Class instances are allowed too (and encouraged as a best practice; you should prefer classes over anonymous structures). If not using class instances, consider creating a typedef for improved type checking at compile-time. If you use a class, be sure to update the item parameter's type in the itemToChildren, itemToText, and itemToSeparator functions so that the compiler can catch any errors.

Listen for events

Add an event listener for MenuEvent.ITEM_TRIGGER to perform an action when the user clicks or taps a menu item.

menuBar.addEventListener(MenuEvent.ITEM_TRIGGER, menuBar_itemTriggerHandler);

Check the event's state property in the listener to determine which menu item was triggered.

function menuBar_itemTriggerHandler(event:MenuEvent):Void {
    trace("Menu item trigger: " + event.state.text);
}

The state is an instance of theMenuItemState class, which includes various properties, such as the button's text, the full item data from the collection, and the index position of the item in the collection.

To perform actions when a top-level menu opens or closes, add an event listener for MenuEvent.MENU_OPEN or MenuEvent.MENU_CLOSE.

menuBar.addEventListener(MenuEvent.MENU_OPEN, menuBar_menuOpenHandler);
menuBar.addEventListener(MenuEvent.MENU_CLOSE, menuBar_menuOpenHandler);

The following example shows a sample listener for MenuEvent.MENU_OPEN.

private function menuBar_menuOpenHandler(event:MenuEvent):Void {
    trace("Menu item open: " + event.state.text);
}

Add or remove items

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

var newItem = { text: "New Item" };
var newLocation = [2, 1];
menuBar.dataProvider.addAt(newItem, newLocation);

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

Similarly, to remove an item, call remove() or removeAt() on the collection.

var locationToRemove = [2, 1];
menuBar.dataProvider.removeAt(locationToRemove);

Styles

A number of styles may be customized on a MenuBar component, including an optional background skin and the layout.

Background skin

Optionally give the menu bar a background using the backgroundSkin property. The following example sets it to a RectangleSkin instance.

var skin = new RectangleSkin();
skin.border = SolidColor(1.0, 0x999999);
skin.fill = SolidColor(0xcccccc);
skin.width = 16.0;
skin.height = 16.0;
menuBar.backgroundSkin = skin;

The border and fill properties of the RectangleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.

The menu bar automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like the layout and scroll bars), so it's important to set a skin's width and height properties to appropriate values to use in this calculation.

See Skinning with common shapes for more details about how to use RectangleSkin with the LineStyle and FillStyle enums that change its border and fill appearance.

The appearance of the menu bar's border or fill may be customized to change when the menu bar is disabled. In the next example, setting the skin's disabledFill method makes it switch to a different fill when the menu bar is disabled.

skin.disabledFill = SolidColor(0xffcccc);

Similarly, use the skin's disabledBorder property to change the border when disabled.

skin.disabledBorder = SolidColor(2.0, 0x999999);

In the examples above, the menu bar uses the same RectangleSkin for all states, and that skin listens for changes to the menu bar's current state. Alternatively, the menu bar's disabledBackgroundSkin method allows the menu bar to display a completely different display object when it is disabled.

var defaultSkin = new RectangleSkin();
// ... set border, fill, width, and height
menuBar.backgroundSkin = defaultSkin;

var disabledSkin = new RectangleSkin();
// ... set border, fill, width, and height
menuBar.disabledBackgroundSkin = disabledSkin;

In the example above, the menu bar will have a separate skins when enabled and disabled.

Layout

Set the menu bar's layout property to change how its children are positioned and sized. By default, a menu bar uses HorizontalLayout, but it may be changed to a different layout, if desired.

menuBar.layout = new VerticalLayout();

The example above uses VerticalLayout, but a number of different layouts are available in Feathers UI, and it's also possible to create custom layouts.