mx.controls

# FlexNativeMenu - AS3 Flex

Package | mx.controls
Class | public class FlexNativeMenu
Inheritance | FlexNativeMenu EventDispatcher Object
Implements | ILayoutManagerClient, IFlexContextMenu, IAutomationObject

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The FlexNativeMenu component provides a wrapper for AIR's NativeMenu class. The FlexNativeMenu provides a way to define native operating system menus (such as window, application, and context menus) using techniques that are familiar to Flex developers and consistent with other Flex menu components, such as using MXML and data providers to specify menu structure. However, unlike Flex menu components, the menus that are defined by a FlexNativeMenu component are rendered by the host operating system as part of an AIR application, rather than being created as visual components by Flex.

Like other Flex menu components, to define the structure of a menu represented by a FlexNativeMenu component, you create a data provider such as an XML hierarchy or an array of objects containing data to be used to define the menu. Several properties can be set to define how the data provider data is interpreted, such as the `labelField` property to specify the data field that is used for the menu item label, the `keyEquivalentField` property to specify the field that defines a keyboard equivalent shortcut for the menu item, and the `mnemonicIndexField` property to specify the field that defines the index position of the character in the label that is used as the menu item's mnemonic.

The data provider for FlexNativeMenu items can specify several attributes that determine how the item is displayed and behaves, as the following XML data provider shows:

       <mx:XML format="e4x" id="myMenuData">
         <root>
            <menuitem label="MenuItem A">
                <menuitem label="SubMenuItem A-1" enabled="False"/>
                <menuitem label="SubMenuItem A-2"/>
            </menuitem>
            <menuitem label="MenuItem B" type="check" toggled="true"/>
            <menuitem label="MenuItem C" type="check" toggled="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>

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 | Note: this attribute is deprecated as of Flex 3.2. Use `commandKey` instead. Specifies whether the Command key is required as part of the key equivalent for the item.
`commandKey` | Boolean | Specifies whether the Command key is required as part of the key equivalent for the item.
`controlKey` | Boolean | Specifies whether the Control key is required as part of the key equivalent for the item.
`ctrlKey` | Boolean | Note: this attribute is deprecated as of Flex 3.2. Use `controlKey` instead. 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` | Boolean | 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.

To create a window menu, set the FlexNativeMenu as the `menu` property of the Window or WindowedApplication instance on which the menu should appear. To create an application menu, assign the FlexNativeMenu as the `menu` property of the application's WindowedApplication. To assign a FlexNativeMenu as the context menu for a portion of the user interface, call the FlexNativeMenu instance's `setContextMenu()` method, passing the UI object as an argument. Call the FlexNativeMenu component's `display()` method to display the menu as a pop-up menu anywhere on one of the application's windows.

To detect when menu items commands are triggered, register a listener for the `itemClick` event. You can also register a listener for the `menuShow` event to determine when any menu or submenu is opened.

MXML Syntax Show MXML Syntax
Hide MXML Syntax

The `<mx:FlexNativeMenu>` tag supports the following tag attributes:

      <mx:FlexNativeMenu
        Properties
        dataDescriptor="mx.controls.treeClasses.DefaultDataDescriptor"
        dataProvider="undefined"
        keyEquivalentField="keyEquivalent"
        keyEquivalentFunction="undefined"
        keyEquivalentModifiersFunction="undefined"
        labelField="label"
        labelFunction="undefined"
        mnemonicIndexField="mnemonicIndex"
        mnemonicIndexFunction="undefined"
        showRoot="true"

        Events
        itemClick="No default"
        menuShow="No default"
      />

More examples

About the FlexNativeMenu control
Defining FlexNativeMenu menu structure and data
Example: An Array FlexNativeMenu data provider
Example: An XML FlexNativeMenu data provider
Specifying menu item mnemonics

Related API Elements

flash.display.NativeMenu
mx.events.FlexNativeMenuEvent

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | automationDelegate : Object The delegate object that handles the automation-related functionality. | FlexNativeMenu
|  | automationEnabled : Boolean [read-only] True if this component is enabled for automation, false otherwise. | FlexNativeMenu
|  | automationName : String Name that can be used as an identifier for this object. | FlexNativeMenu
|  | automationOwner : DisplayObjectContainer The owner of this component for automation purposes. | FlexNativeMenu
|  | automationParent : DisplayObjectContainer The parent of this component for automation purposes. | FlexNativeMenu
|  | automationTabularData : Object [read-only] An implementation of the IAutomationTabularData interface, which can be used to retrieve the data. | FlexNativeMenu
|  | automationValue : Array [read-only] This value generally corresponds to the rendered appearance of the object and should be usable for correlating the identifier with the object as it appears visually within the application. | FlexNativeMenu
|  | automationVisible : Boolean [read-only] True if this component is visible for automation, false otherwise. | FlexNativeMenu
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | dataDescriptor : IMenuDataDescriptor The object that accesses and manipulates data in the data provider. | FlexNativeMenu
|  | dataProvider : Object The hierarchy of objects that are used to define the structure of menu items in the NativeMenu. | FlexNativeMenu
|  | hasRoot : Boolean [read-only] A flag that indicates that the current data provider has a root node; for example, a single top node in a hierarchical structure. | FlexNativeMenu
|  | initialized : Boolean A flag that determines if an object has been through all three phases of layout: commitment, measurement, and layout (provided that any were required). | FlexNativeMenu
|  | keyEquivalentField : String The name of the field in the data provider that determines the key equivalent for each menu item. | FlexNativeMenu
|  | keyEquivalentFunction : Function The function that determines the key equivalent for each menu item. | FlexNativeMenu
|  | keyEquivalentModifiersFunction : Function The function that determines the key equivalent modifiers for each menu item. | FlexNativeMenu
|  | labelField : String The name of the field in the data provider that determines the text to display for each menu item. | FlexNativeMenu
|  | labelFunction : Function The function that determines the text to display for each menu item. | FlexNativeMenu
|  | mnemonicIndexField : String The name of the field in the data provider that determines the mnemonic index for each menu item. | FlexNativeMenu
|  | mnemonicIndexFunction : Function The function that determines the mnemonic index for each menu item. | FlexNativeMenu
|  | nativeMenu : NativeMenu [read-only] Returns the flash.display.NativeMenu managed by this object, or null if there is not one. | FlexNativeMenu
|  | nestLevel : int Depth of this object in the containment hierarchy. | FlexNativeMenu
|  | numAutomationChildren : int [read-only] The number of automation children this container has. | FlexNativeMenu
|  | processedDescriptors : Boolean Set to true after immediate or deferred child creation, depending on which one happens. | FlexNativeMenu
|  | showInAutomationHierarchy : Boolean A flag that determines if an automation object shows in the automation hierarchy. | FlexNativeMenu
|  | showRoot : Boolean A Boolean flag that specifies whether to display the data provider's root node. | FlexNativeMenu
|  | updateCompletePendingFlag : Boolean A flag that determines if an object has been through all three phases of layout validation (provided that any were required). | FlexNativeMenu

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | FlexNativeMenu() Constructor. | FlexNativeMenu
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | createAutomationIDPart(child:IAutomationObject):Object Returns a set of properties that identify the child within this container. | FlexNativeMenu
|  | createAutomationIDPartWithRequiredProperties(child:IAutomationObject, properties:Array):Object Returns a set of properties that identify the child within this container. | FlexNativeMenu
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | display(stage:Stage, x:int, y:int):void Pops up this menu at the specified location. | FlexNativeMenu
|  | getAutomationChildAt(index:int):IAutomationObject Provides the automation object at the specified index. | FlexNativeMenu
|  | getAutomationChildren():Array Provides the automation object list . | FlexNativeMenu
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | invalidateProperties():void Marks a component so that its commitProperties() method gets called during a later screen update. | FlexNativeMenu
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | replayAutomatableEvent(event:Event):Boolean Replays the specified event. | FlexNativeMenu
|  | resolveAutomationIDPart(criteria:Object):Array Resolves a child by using the id provided. | FlexNativeMenu
|  | setContextMenu(component:InteractiveObject):void Sets the context menu of the InteractiveObject to the underlying native menu. | FlexNativeMenu
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | unsetContextMenu(component:InteractiveObject):void Unsets the context menu of the InteractiveObject that has been set to the underlying native menu. | FlexNativeMenu
|  | validateDisplayList():void Validates the position and size of children and draws other visuals. | FlexNativeMenu
|  | validateNow():void Validates and updates the properties and layout of this object and redraws it, if necessary. | FlexNativeMenu
|  | validateProperties():void Validates the properties of a component. | FlexNativeMenu
|  | validateSize(recursive:Boolean = false):void Validates the measured size of the component If the LayoutManager.invalidateSize() method is called with this ILayoutManagerClient, then the validateSize() method is called when it's time to do measurements. | FlexNativeMenu
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Protected Methods

| Method | Defined By
--- | --- | ---
|  | commitProperties():void Processes the properties set on the component. | FlexNativeMenu
|  | itemToKeyEquivalent(data:Object):String Returns the key equivalent for the given data object based on the keyEquivalentField and keyEquivalentFunction properties. | FlexNativeMenu
|  | itemToKeyEquivalentModifiers(data:Object):Array Returns the key equivalent modifiers for the given data object based on the keyEquivalentModifiersFunction property. | FlexNativeMenu
|  | itemToLabel(data:Object):String Returns the String to use as the menu item label for the given data object, based on the labelField and labelFunction properties. | FlexNativeMenu
|  | itemToMnemonicIndex(data:Object):int Returns the mnemonic index for the given data object based on the mnemonicIndexField and mnemonicIndexFunction properties. | FlexNativeMenu
|  | parseLabelToMnemonicIndex(data:String):int Extracts the mnemonic index from a label based on the presence of an underscore character. | FlexNativeMenu
|  | parseLabelToString(data:String):String Determines the actual label to be used for the NativeMenuItem by removing underscore characters and converting escaped underscore characters, if there are any. | FlexNativeMenu

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | itemClick | Dispatched when a menu item is selected. | FlexNativeMenu
|  | menuShow | Dispatched before a menu or submenu is displayed. | FlexNativeMenu

Property Detail

### automationDelegate

property

`automationDelegate:Object`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The delegate object that handles the automation-related functionality.

Implementation
`public function get automationDelegate():Object`
`public function set automationDelegate(value:Object):void`

### automationEnabled

property

`automationEnabled:Boolean` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

True if this component is enabled for automation, false otherwise.

Implementation
`public function get automationEnabled():Boolean`

### automationName

property

`automationName:String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Name that can be used as an identifier for this object.

Implementation
`public function get automationName():String`
`public function set automationName(value:String):void`

### automationOwner

property

`automationOwner:DisplayObjectContainer`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The owner of this component for automation purposes.

Implementation
`public function get automationOwner():DisplayObjectContainer`
`public function set automationOwner(value:DisplayObjectContainer):void`

### automationParent

property

`automationParent:DisplayObjectContainer`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The parent of this component for automation purposes.

Implementation
`public function get automationParent():DisplayObjectContainer`
`public function set automationParent(value:DisplayObjectContainer):void`

### automationTabularData

property

`automationTabularData:Object` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

An implementation of the `IAutomationTabularData` interface, which can be used to retrieve the data.

Implementation
`public function get automationTabularData():Object`

### automationValue

property

`automationValue:Array` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

This value generally corresponds to the rendered appearance of the object and should be usable for correlating the identifier with the object as it appears visually within the application.

Implementation
`public function get automationValue():Array`

### automationVisible

property

`automationVisible:Boolean` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

True if this component is visible for automation, false otherwise.

Implementation
`public function get automationVisible():Boolean`

### dataDescriptor

property

`dataDescriptor:IMenuDataDescriptor`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The object that accesses and manipulates data in the data provider. The FlexNativeMenu control delegates to the data descriptor for information about its data. This data is then used to parse and move about the data source. The data descriptor defined for the FlexNativeMenu is used for all child menus and submenus.

When you specify this property as an attribute in MXML, you must use a reference to the data descriptor, not the string name of the descriptor. Use the following format for setting the property:

    <mx:FlexNativeMenu id="flexNativeMenu" dataDescriptor="{new MyCustomDataDescriptor()}"/>

Alternatively, you can specify the property in MXML as a nested subtag, as the following example shows:

    <mx:FlexNativeMenu>
          <mx:dataDescriptor>
             <myCustomDataDescriptor>
          </mx:dataDescriptor>
          ...

The default value is an internal instance of the DefaultDataDescriptor class.

Implementation
`public function get dataDescriptor():IMenuDataDescriptor`
`public function set dataDescriptor(value:IMenuDataDescriptor):void`

### dataProvider

property

`dataProvider:Object`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The hierarchy of objects that are used to define the structure of menu items in the NativeMenu. Individual data objects define menu items, and items with child items become menus and submenus.

The FlexNativeMenu control handles the source data object as follows:

- A String containing valid XML text is converted to an XML object.
- An XMLNode is converted to an XML object.
- An XMLList is converted to an XMLListCollection.
- Any object that implements the ICollectionView interface is cast to an ICollectionView.
- An Array is converted to an ArrayCollection.
- Any other type object is wrapped in an Array with the object as its sole entry.

The default value is `"undefined".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `collectionChange` event.

Implementation
`public function get dataProvider():Object`
`public function set dataProvider(value:Object):void`

### hasRoot

property

`hasRoot:Boolean` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

A flag that indicates that the current data provider has a root node; for example, a single top node in a hierarchical structure. XML and Object are examples of types that have a root node, while Lists and Arrays do not.

Implementation
`public function get hasRoot():Boolean`

### initialized

property

`initialized:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

A flag that determines if an object has been through all three phases of layout: commitment, measurement, and layout (provided that any were required).

Implementation
`public function get initialized():Boolean`
`public function set initialized(value:Boolean):void`

### keyEquivalentField

property

`keyEquivalentField:String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The name of the field in the data provider that determines the key equivalent for each menu item. The set of values is defined in the Keyboard class, in the `KEYNAME_XXXX` constants. For example, consult that list for the value for a control character such as Home, Insert, etc.

Setting the `keyEquivalentFunction` property causes this property to be ignored.

The default value is `"keyEquivalent".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `keyEquivalentChanged` event.

Implementation
`public function get keyEquivalentField():String`
`public function set keyEquivalentField(value:String):void`

Related API Elements

flash.ui.Keyboard

### keyEquivalentFunction

property

`keyEquivalentFunction:Function`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The function that determines the key equivalent for each menu item. If you omit this property, Flex uses the contents of the field or attribute specified by the `keyEquivalentField` property. If you specify this property, Flex ignores any `keyEquivalentField` property value.

The `keyEquivalentFunction` property is good for handling formatting, localization, and platform independence.

The key equivalent function must take a single argument, which is the item in the data provider, and must return a String.

    myKeyEquivalentFunction(item:Object):String

The default value is `"undefined".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `keyEquivalentFunctionChanged` event.

Implementation
`public function get keyEquivalentFunction():Function`
`public function set keyEquivalentFunction(value:Function):void`

Related API Elements

flash.ui.Keyboard

### keyEquivalentModifiersFunction

property

`keyEquivalentModifiersFunction:Function`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The function that determines the key equivalent modifiers for each menu item. If you omit this property, Flex uses its own default function to determine the Array of modifiers by looking in the data provider data for the presence of the following (boolean) fields: `altKey`, `commandKey`, `controlKey`, and `shiftKey`.

The `keyEquivalentModifiersFunction` property is good for handling formatting, localization, and platform independence.

The key equivalent modifiers function must take a single argument, which is the item in the data provider, and must return an array of modifier key names.

    myKeyEquivalentModifiersFunction(item:Object):Array

The default value is `"undefined".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `keyEquivalentModifiersFunctionChanged` event.

Implementation
`public function get keyEquivalentModifiersFunction():Function`
`public function set keyEquivalentModifiersFunction(value:Function):void`

### labelField

property

`labelField:String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The name of the field in the data provider that determines the text to display for each menu item. If the data provider is an Array of Strings, Flex uses each string value as the label. If the data provider is an E4X XML object, you must set this property explicitly. For example, if each XML elementin an E4X XML Object includes a "label" attribute containing the text to display for each menu item, set the labelField to `"@label"`.

In a label, you can specify the character to be used as the mnemonic index by preceding it with an underscore. For example, a label value of `"C_ut"` sets the mnemonic index to 1. Only the first underscore present is used for this purpose. To display a literal underscore character in the label, you can escape it using a double underscore. For example, a label value of `"C__u_t"` would result in a menu item with the label "C_ut" and a mnemonic index of 3 (the "t" character). If the field defined in the `mnemonicIndexField` property is present and set to a value greater than zero, that value takes precedence over any underscore-specified mnemonic index value.

Setting the `labelFunction` property causes this property to be ignored.

The default value is `"label".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `labelFieldChanged` event.

Implementation
`public function get labelField():String`
`public function set labelField(value:String):void`

### labelFunction

property

`labelFunction:Function`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The function that determines the text to display for each menu item. The label function must find the appropriate field or fields in the data provider and return a displayable string.

If you omit this property, Flex uses the contents of the field or attribute specified by the `labelField` property. If you specify this property, Flex ignores any `labelField` property value.

The `labelFunction` property can be helpful for handling formatting, localization, and platform-independence.

The label function must take a single argument, which is the item in the data provider, and must return a String.

    myLabelFunction(item:Object):String

The default value is `"undefined".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `labelFunctionChanged` event.

Implementation
`public function get labelFunction():Function`
`public function set labelFunction(value:Function):void`

### mnemonicIndexField

property

`mnemonicIndexField:String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The name of the field in the data provider that determines the mnemonic index for each menu item.

If the field specified by this property contains a number greater than zero, that mnemonic index takes precedence over one specified by an underscore in the label.

Setting the `mnemonicIndexFunction` property causes this property to be ignored.

The default value is `"mnemonicIndex".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `mnemonicIndexChanged` event.

Implementation
`public function get mnemonicIndexField():String`
`public function set mnemonicIndexField(value:String):void`

Related API Elements

labelField

### mnemonicIndexFunction

property

`mnemonicIndexFunction:Function`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The function that determines the mnemonic index for each menu item.

If you omit this property, Flex uses the contents of the field or attribute specified by the `mnemonicIndexField` property. If you specify this property, Flex ignores any `mnemonicIndexField` property value.

If this property is defined and the function returns a number greater than zero for a data item, the returned mnemonic index takes precedence over one specified by an underscore in the label.

The `mnemonicIndexFunction` property is good for handling formatting, localization, and platform independence.

The mnemonic index function must take a single argument which is the item in the data provider and return an int.

    myMnemonicIndexFunction(item:Object):int

The default value is `"undefined".`

This property can be used as the source for data binding. When this property is modified, it dispatches the `mnemonicIndexFunctionChanged` event.

Implementation
`public function get mnemonicIndexFunction():Function`
`public function set mnemonicIndexFunction(value:Function):void`

### nativeMenu

property

`nativeMenu:NativeMenu` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns the flash.display.NativeMenu managed by this object, or null if there is not one. Any changes made directly to the underlying NativeMenu instance may be lost when changes are made to the menu or the underlying data provider.

This property can be used as the source for data binding. When this property is modified, it dispatches the `nativeMenuUpdate` event.

Implementation
`public function get nativeMenu():NativeMenu`

### nestLevel

property

`nestLevel:int`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Depth of this object in the containment hierarchy. This number is used by the measurement and layout code. The value is 0 if this component is not on the DisplayList.

Implementation
`public function get nestLevel():int`
`public function set nestLevel(value:int):void`

### numAutomationChildren

property

`numAutomationChildren:int` [read-only]

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

The number of automation children this container has. This sum should not include any composite children, though it does include those children not significant within the automation hierarchy.

Implementation
`public function get numAutomationChildren():int`

### processedDescriptors

property

`processedDescriptors:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Set to `true` after immediate or deferred child creation, depending on which one happens. For a Container object, it is set to `true` at the end of the `createComponentsFromDescriptors()` method, meaning after the Container object creates its children from its child descriptors.

For example, if an Accordion container uses deferred instantiation, the `processedDescriptors` property for the second pane of the Accordion container does not become `true` until after the user navigates to that pane and the pane creates its children. But, if the Accordion had set the `creationPolicy` property to `"all"`, the `processedDescriptors` property for its second pane is set to `true` during application startup.

For classes that are not containers, which do not have descriptors, it is set to `true` after the `createChildren()` method creates any internal component children.

Implementation
`public function get processedDescriptors():Boolean`
`public function set processedDescriptors(value:Boolean):void`

### showInAutomationHierarchy

property

`showInAutomationHierarchy:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

A flag that determines if an automation object shows in the automation hierarchy. Children of containers that are not visible in the hierarchy appear as children of the next highest visible parent. Typically containers used for layout, such as boxes and Canvas, do not appear in the hierarchy.

Some controls force their children to appear in the hierarchy when appropriate. For example a List will always force item renderers, including boxes, to appear in the hierarchy. Implementers must support setting this property to `true`.

Implementation
`public function get showInAutomationHierarchy():Boolean`
`public function set showInAutomationHierarchy(value:Boolean):void`

### showRoot

property

`showRoot:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

A Boolean flag that specifies whether to display the data provider's root node.

If the data provider has a root node, and the `showRoot` property is set to `false`, the top-level menu items displayed by the FlexNativeMenu control correspond to the immediate descendants of the root node.

This flag has no effect when using a data provider without a root nodes, such as a List or Array.

The default value is `true.`

Implementation
`public function get showRoot():Boolean`
`public function set showRoot(value:Boolean):void`

Related API Elements

hasRoot

### updateCompletePendingFlag

property

`updateCompletePendingFlag:Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

A flag that determines if an object has been through all three phases of layout validation (provided that any were required).

Implementation
`public function get updateCompletePendingFlag():Boolean`
`public function set updateCompletePendingFlag(value:Boolean):void`
Constructor Detail

### FlexNativeMenu

()
Constructor

`public function FlexNativeMenu()`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Constructor.

Method Detail

### commitProperties

()
method

`protected function commitProperties():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Processes the properties set on the component.

Related API Elements

mx.core.UIComponent.commitProperties()

### createAutomationIDPart

()
method

`public function createAutomationIDPart(child:IAutomationObject):Object`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns a set of properties that identify the child within this container. These values should not change during the lifespan of the application.

Parameters

| `child:IAutomationObject` — Child for which to provide the id.

Returns

| `Object` — Sets of properties describing the child which can later be used to resolve the component.

### createAutomationIDPartWithRequiredProperties

()
method

`public function createAutomationIDPartWithRequiredProperties(child:IAutomationObject, properties:Array):Object`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns a set of properties that identify the child within this container. These values should not change during the lifespan of the application.

Parameters

| `child:IAutomationObject` — Child for which to provide the id.
| `properties:Array`

Returns

| `Object` — Sets of properties describing the child which can later be used to resolve the component.

### display

()
method

`public function display(stage:Stage, x:int, y:int):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Pops up this menu at the specified location.

Parameters

| `stage:Stage` — The Stage object on which to display this menu.
| `x:int` — The number of horizontal pixels, relative to the origin of stage, at which to display this menu.
| `y:int` — The number of vertical pixels, relative to the origin of stage, at which to display this menu.

### getAutomationChildAt

()
method

`public function getAutomationChildAt(index:int):IAutomationObject`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Provides the automation object at the specified index. This list should not include any children that are composites.

Parameters

| `index:int` — The index of the child to return

Returns

| `IAutomationObject` — The child at the specified index.

### getAutomationChildren

()
method

`public function getAutomationChildren():Array`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Provides the automation object list . This list does not include any children that are composites.

Returns

| `Array` — The children .

### invalidateProperties

()
method

`public function invalidateProperties():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Marks a component so that its `commitProperties()` method gets called during a later screen update.

Invalidation is a useful mechanism for eliminating duplicate work by delaying processing of changes to a component until a later screen update. For example, if you want to change the text color and size, it would be wasteful to update the color immediately after you change it and then update the size when it gets set. It is more efficient to change both properties and then render the text with its new size and color once.

Invalidation methods rarely get called. In general, setting a property on a component automatically calls the appropriate invalidation method.

### itemToKeyEquivalent

()
method

`protected function itemToKeyEquivalent(data:Object):String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns the key equivalent for the given data object based on the `keyEquivalentField` and `keyEquivalentFunction` properties. If the method cannot convert the parameter to a String, it returns an empty string.

Parameters

| `data:Object` — Object to be displayed.

Returns

| `String` — The key equivalent based on the data.

### itemToKeyEquivalentModifiers

()
method

`protected function itemToKeyEquivalentModifiers(data:Object):Array`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns the key equivalent modifiers for the given data object based on the `keyEquivalentModifiersFunction` property. If the method cannot convert the parameter to an Array of modifiers, it returns an empty Array.

Parameters

| `data:Object` — Object to be displayed.

Returns

| `Array` — The array of key equivalent modifiers based on the data.

### itemToLabel

()
method

`protected function itemToLabel(data:Object):String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns the String to use as the menu item label for the given data object, based on the `labelField` and `labelFunction` properties. If the method cannot convert the parameter to a String, it returns a single space.

Parameters

| `data:Object` — Object to be displayed.

Returns

| `String` — The string to be displayed based on the data.

### itemToMnemonicIndex

()
method

`protected function itemToMnemonicIndex(data:Object):int`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Returns the mnemonic index for the given data object based on the `mnemonicIndexField` and `mnemonicIndexFunction` properties. If the method cannot convert the parameter to an integer, it returns -1.

Parameters

| `data:Object` — Object to be displayed.

Returns

| `int` — The mnemonic index based on the data.

### parseLabelToMnemonicIndex

()
method

`protected function parseLabelToMnemonicIndex(data:String):int`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Extracts the mnemonic index from a label based on the presence of an underscore character. It finds the leading underscore character if there is one and uses that as the index.

Parameters

| `data:String` — The data to parse for the index.

Returns

| `int` — The index.

### parseLabelToString

()
method

`protected function parseLabelToString(data:String):String`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Determines the actual label to be used for the NativeMenuItem by removing underscore characters and converting escaped underscore characters, if there are any.

Parameters

| `data:String` — The data to parse for the label.

Returns

| `String` — The label.

### replayAutomatableEvent

()
method

`public function replayAutomatableEvent(event:Event):Boolean`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Replays the specified event. A component author should probably call super.replayAutomatableEvent in case default replay behavior has been defined in a superclass.

Parameters

| `event:Event` — The event to replay.

Returns

| `Boolean` — `true` if a replay was successful.

### resolveAutomationIDPart

()
method

`public function resolveAutomationIDPart(criteria:Object):Array`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Resolves a child by using the id provided. The id is a set of properties as provided by the `createAutomationIDPart()` method.

Parameters

| `criteria:Object` — Set of properties describing the child. The criteria can contain regular expression values resulting in multiple children being matched.

Returns

| `Array` — Array of children that matched the criteria or `null` if no children could not be resolved.

### setContextMenu

()
method

`public function setContextMenu(component:InteractiveObject):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Sets the context menu of the InteractiveObject to the underlying native menu.

Parameters

| `component:InteractiveObject` — The interactive object.

### unsetContextMenu

()
method

`public function unsetContextMenu(component:InteractiveObject):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Unsets the context menu of the InteractiveObject that has been set to the underlying native menu.

Parameters

| `component:InteractiveObject` — The interactive object.

### validateDisplayList

()
method

`public function validateDisplayList():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Validates the position and size of children and draws other visuals. If the `LayoutManager.invalidateDisplayList()` method is called with this ILayoutManagerClient, then the `validateDisplayList()` method is called when it's time to update the display list.

### validateNow

()
method

`public function validateNow():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Validates and updates the properties and layout of this object and redraws it, if necessary.

### validateProperties

()
method

`public function validateProperties():void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Validates the properties of a component. If the `LayoutManager.invalidateProperties()` method is called with this ILayoutManagerClient, then the `validateProperties()` method is called when it's time to commit property values.

### validateSize

()
method

`public function validateSize(recursive:Boolean = false):void`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Validates the measured size of the component If the `LayoutManager.invalidateSize()` method is called with this ILayoutManagerClient, then the `validateSize()` method is called when it's time to do measurements.

Parameters

| `recursive:Boolean` (default = `false`)`` — If `true`, call this method on the objects children.

Event Detail

### itemClick

Event

Event Object Type: `mx.events.FlexNativeMenuEvent`
property FlexNativeMenuEvent.type = `mx.events.FlexNativeMenuEvent.ITEM_CLICK`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Dispatched when a menu item is selected.

The FlexNativeMenuEvent.ITEM_CLICK event type constant indicates that the user selected a menu item.

The properties of the event object for this event type have the following values. Not all properties are meaningful for all kinds of events. See the detailed property descriptions for more information.

Property | Value
--- | ---
`bubbles` | false
`cancelable` | true
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`index` | The index in the menu of the selected menu item.
`item` | The item in the dataProvider that was selected.
`label` | The label text of the selected menu item.
`nativeMenu` | The specific NativeMenu instance associated with this event.
`nativeMenuItem` | The specific NativeMenuItem instance associated with this event.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.
`type` | FlexNativeMenuEvent.ITEM_CLICK

### menuShow

Event

Event Object Type: `mx.events.FlexNativeMenuEvent`
property FlexNativeMenuEvent.type = `mx.events.FlexNativeMenuEvent.MENU_SHOW`

Language Version: | ActionScript 3.0

Product Version: | Flex 3

Runtime Versions: | AIR 1.1

Dispatched before a menu or submenu is displayed.

The FlexNativeMenuEvent.MENU_SHOW type constant indicates that the mouse pointer rolled a menu or submenu opened.

The properties of the event object for this event type have the following values. Not all properties are meaningful for all kinds of events. See the detailed property descriptions for more information.

Property | Value
--- | ---
`bubbles` | false
`cancelable` | true
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`index` | -1. This property is not set for this type of event.
`item` | null. This property is not set for this type of event.
`label` | null. This property is not set for this type of event.
`nativeMenu` | The specific NativeMenu instance associated with this event.
`nativeMenuItem` | null. This property is not set for this type of event.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.
`type` | FlexNativeMenuEvent.MENU_SHOW

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00