FlexNativeMenu

(Preview)

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 expanded

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"
  />

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

	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

Constructor Detail

Method Detail

Event Detail

[an error occurred while processing this directive]

Legal Notices | Online Privacy Policy

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

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

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

	`properties:Array`

	`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.

FlexNativeMenu - AS3 Flex

Packagesx

Language Elements

Appendixes

Package mx.controls

automationDelegate

automationEnabled

automationName

automationOwner

automationParent

automationTabularData

automationValue

automationVisible

dataDescriptor

dataProvider

hasRoot

initialized

keyEquivalentField

keyEquivalentFunction

keyEquivalentModifiersFunction

labelField

labelFunction

mnemonicIndexField

mnemonicIndexFunction

nativeMenu

nestLevel

numAutomationChildren

processedDescriptors

showInAutomationHierarchy

showRoot

updateCompletePendingFlag

commitProperties

createAutomationIDPart

createAutomationIDPartWithRequiredProperties

display

getAutomationChildAt

getAutomationChildren

invalidateProperties

itemToKeyEquivalent

itemToKeyEquivalentModifiers

itemToLabel

itemToMnemonicIndex

parseLabelToMnemonicIndex

parseLabelToString

replayAutomatableEvent

resolveAutomationIDPart

setContextMenu

unsetContextMenu

validateDisplayList

validateNow

validateProperties

validateSize

itemClick

menuShow