Defining FlexNativeMenu menu structure and data

The techniques for defining structure and data for a FlexNativeMenu are like the techniques for structuring all Flex menu controls. Consequently, this section does not provide comprehensive information on structuring Flex menus, but instead focuses on differences between FlexNativeMenu structure versus other Flex menu components. For more information on structuring data providers for all Flex menu controls, see Defining menu structure and data. For more information on hierarchical data providers including data descriptors, see Hierarchical data objects.

The dataProvider property of a FlexNativeMenu defines the structure of the menu. To change a menu's structure at runtime, change the data provider and the menu updates itself accordingly. Menus typically use a hierarchical data provider such as nested arrays or XML. However, a simple menu may consist of a single flat structure of menu items.

A FlexNativeMenu instance uses a data descriptor to parse and manipulate the data provider's contents. By default, a FlexNativeMenu control uses a DefaultDataDescriptor instance as its descriptor. However, you can customize menu data parsing by creating your own data descriptor class and setting it as the FlexNativeMenu control's dataDescriptor property. The DefaultDataDescriptor supports a data provider that is an XML object or XMLList object, an array of objects, an object with a children property containing an array of objects, or a collection that implements the ICollectionView interface such as an ArrayCollection or XMLListCollection instance.

Contents

Specifying and using menu entry information

Information in a FlexNativeMenu control's data provider determines how each menu entry appears and is used. To access or change the menu contents, you modify the contents of the data provider.

The FlexNativeMenu class uses the methods of the IMenuDataDescriptor interface to access and manipulate information in the data provider that defines the menu behavior and contents. Flex includes the DefaultDataDescriptor class that implements this interface. A FlexNativeMenu control uses the DefaultDataDescriptor class if you do not specify another class in the dataDescriptor property.

Menu entry types

Each data provider entry can specify an item type and type-specific information about the menu item. Menu-based classes support the following item types (type field values):

Menu item type	Description
normal	The default type. Selecting an item with the `normal` type triggers an `itemClick` event. Alternatively, if the item has children, the menu dispatches a `menuShow` event and opens a submenu.
check	Selecting an item with the `check` type toggles the menu item's `toggled` property between `true` and `false` values and triggers an `itemClick` event. When the menu item is in the `true` state, it displays a check mark in the menu next to the item's label.
separator	Items with the `separator` type provide a simple horizontal line that divides the items in a menu into different visual groups.

Unlike other Flex menu controls, the FlexNativeMenu component does not support radio-button menu items (type radio).

Menu attributes

Menu items can specify several attributes that determine how the item is displayed and behaves. The following table lists the attributes you can specify, their data types, their purposes, and how the data provider must represent them if the menu uses the DefaultDataDescriptor class to parse the data provider:

Attribute	Type	Description
`altKey`	Boolean	Specifies whether the Alt key is required as part of the key equivalent for the item.
`cmdKey`	Boolean	Specifies whether the Command key is required as part of the key equivalent for the item.
`ctrlKey`	Boolean	Specifies whether the Control key is required as part of the key equivalent for the item.
`enabled`	Boolean	Specifies whether the user can select the menu item (`true`), or not (`false`). If not specified, Flex treats the item as if the value were `true`. If you use the default data descriptor, data providers must use an `enabled` XML attribute or object field to specify this characteristic.
`keyEquivalent`	String	Specifies a keyboard character which, when pressed, triggers an event as though the menu item was selected. The menu's `keyEquivalentField` or `keyEquivalentFunction` property determines the name of the field in the data that specifies the key equivalent, or a function for determining the key equivalents. (If the data provider is in E4X XML format, you must specify one of these properties to assign a key equivalent.)
`label`	String	Specifies the text that appears in the control. This item is used for all menu item types except `separator.` The menu's `labelField` or `labelFunction` property determines the name of the field in the data that specifies the label, or a function for determining the labels. (If the data provider is in E4X XML format, you must specify one of these properties to display a label.) If the data provider is an array of strings, Flex uses the string value as the label.
`mnemonicIndex`	Integer	Specifies the index position of the character in the label that is used as the mnemonic for the menu item. The menu's `mnemonicIndexField` or `mnemonicIndexFunction` property determines the name of the field in the data that specifies the mnemonic index, or a function for determining mnemonic index. (If the data provider is in E4X XML format, you must specify one of these properties to specify a mnemonic index in the data.) Alternatively, you can indicate that a character in the label is the menu item's mnemonic by including an underscore immediately to the left of that character.
`shiftKey`	String	Specifies whether the Shift key is required as part of the key equivalent for the item.
`toggled`	Boolean	Specifies whether a `check` item is selected. If not specified, Flex treats the item as if the value were `false` and the item is not selected. If you use the default data descriptor, data providers must use a `toggled` XML attribute or object field to specify this characteristic.
`type`	String	Specifies the type of menu item. Meaningful values are `separator` and `check`. Flex treats all other values, or nodes with no type entry, as normal menu entries. If you use the default data descriptor, data providers must use a `type` XML attribute or object field to specify this characteristic.

Unlike other Flex menu controls, the FlexNativeMenu component does not support the groupName or icon attributes. In addition, it supports the additional attribute keyEquivalent and the key equivalent modifier attributes altKey, cmdKey, ctrlKey, and shiftKey.

The FlexNativeMenu component ignores all other object fields or XML attributes, so you can use them for application-specific data.

Considerations for XML-based FlexNativeMenu data providers

In a simple case for creating a single menu or menu bar using the FlexNativeMenu control, you might use an <mx:XML> or <mx:XMLList> tag and standard XML node syntax to define the menu data provider. When you use an XML-based data provider, keep the following rules in mind:

With the <mx:XML> tag you must have a single root node, and you set the showRoot property of the FlexNativeMenu control to false. (otherwise, your FlexNativeMenu would have only the root node as a menu item). With the <mx:XMLList> tag you define a list of XML nodes, and the top-level nodes define the top-level menu items.
If your data provider has label, keyEquivalent, or mnemonicIndex attributes the default attribute names are not recognized by the DefaultDataDescriptor class. Set the FlexNativeMenu control's labelField , keyEquivalentField, or mnemonicIndexField property and use the E4X @ notation to specify the attribute name, such as:
```
labelField="@label"
keyEquivalentField="@keyEquivalent"
mnemonicIndexField="@mnemonicIndex"
```

Example: An Array FlexNativeMenu data provider

The following example uses a FlexNativeMenu component to display a popup menu. It demonstrates how to define the menu structure using an Array of plain objects as a data provider. For an application that specifies an identical menu structure in XML, see Example: An XML FlexNativeMenu data provider.

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute" 
    creationComplete="init();">
    
    <mx:Script>
        <![CDATA[
            import mx.controls.FlexNativeMenu;
            
            private var myMenu:FlexNativeMenu;
            
            private function init():void
            {
                myMenu = new FlexNativeMenu();
                myMenu.dataProvider = menuData;
                myMenu.showRoot = false;
            }
            
            // Method to show the menu. 
            private function show():void
            {
                myMenu.display(this.stage, 10, 10);
            }
            
            // The Array data provider
            [Bindable]
            public var menuData:Array = [
                {label: "MenuItem A"},
                {label: "MenuItem B", type: "check", toggled: true},
                {label: "MenuItem C", enabled: false},
                {type: "separator"},
                {label: "MenuItem D", children: [
                    {label: "SubMenuItem D-1"},
                    {label: "SubMenuItem D-2"}, 
                    {label: "SubMenuItem D-3"} 
                    ]} 
                ];
        ]]>
    </mx:Script>
    
    <!-- Button control to create and open the menu. -->
    <mx:Button x="300" y="10" 
        label="Open Menu" 
        click="show();"/>
</mx:WindowedApplication>

Example: An XML FlexNativeMenu data provider

The following example displays a popup menu using a FlexNativeMenu component. It shows how to define the menu structure using XML as a data provider. For an application that specifies an identical menu structure using an Array of objects as a data provider, see Example: An Array FlexNativeMenu data provider.

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute" 
    creationComplete="init();">
    
    <mx:Script>
        <![CDATA[
            import mx.controls.FlexNativeMenu;
            
            private var myMenu:FlexNativeMenu;
            
            private function init():void
            {
                myMenu = new FlexNativeMenu();
                myMenu.dataProvider = menuData;
                myMenu.labelField = "@label";
                myMenu.showRoot = false;
            }
            
            // Method to show the menu. 
            private function show():void
            {
                myMenu.display(this.stage, 10, 10);
            }
        ]]>
    </mx:Script>
    
    <!-- The XML data provider -->
    <mx:XML format="e4x" id="menuData">
        <root>
            <menuitem label="MenuItem A"/>
            <menuitem label="MenuItem B" type="check" toggled="true"/>
            <menuitem label="MenuItem C" enabled="false"/>
            <menuitem type="separator"/>
            <menuitem label="MenuItem D">
                <menuitem label="SubMenuItem D-1"/>
                <menuitem label="SubMenuItem D-2"/>
                <menuitem label="SubMenuItem D-3"/>
            </menuitem>
        </root>
    </mx:XML>
    
    <!-- Button control to create and open the menu. -->
    <mx:Button x="300" y="10" 
        label="Open Menu" 
        click="show();"/>
</mx:WindowedApplication>