flash.display

# NativeMenu - AS3

Package | flash.display
Class | public class NativeMenu
Inheritance | NativeMenu EventDispatcher Object
Subclasses | ContextMenu

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The NativeMenu class contains methods and properties for defining native menus.

AIR profile support: This feature is supported on all desktop operating systems, but is not supported on mobile devices or AIR for TV devices. You can test for support at run time using the `NativeMenu.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

A native menu is a menu that is controlled and drawn by the operating system rather than by your application. AIR supports the following types of native menus:

- Application menus are supported on OS X. Use the `NativeApplication.supportsMenu` property to test whether application menus are supported on the host operating system. An application menu is displayed on the Menu bar at the top of the Mac desktop. OS X provides a default menu for every application, but many of the menu commands are not functional. You can add event listeners to the default items, replace individual menus and items, or even replace the default menu entirely. Access the application menu object using the NativeApplication `menu` property.
- Window menus are supported on Windows and Linux. Use the `NativeWindow.supportsMenu` property to test whether window menus are supported on the host operating system. A window menu is displayed below the window title bar. The area occupied by the menu is not part of the window stage. Applications cannot draw into this area. Assign a menu to a window using the NativeWindow `menu` property.
- Dock icon menus are supported on OS X. Use the `NativeApplication.supportsDockIcon` property to test whether dock icons are supported on the host operating system. Items in a dock icon menu are displayed above the default items provided by the operating system. The default items cannot be accessed by application code. Assign a menu to the `menu` property of the application's DockIcon object.
- System tray icon menus are supported on Windows and most Linux operating systems. Use the `NativeApplication.supportsSystemTrayIcon` property to test whether system tray icons are supported on the host operating system. A system tray icon menu is displayed in response to a right-click on the icon, in much the same fashion as a context menu. Assign a menu to the `menu` property of the application's SystemTrayIcon object.
- Context menus are supported on all operating systems. Context menus are displayed in response to a user interface event, such as a right-click or a command-click on an InteractiveObject displayed in the application. The UI mechanism for showing the menu varies by host operating system and hardware. Assign a menu to the `contextMenu` property of an InteractiveObject. In AIR, a context menu can be created with either the NativeMenu class or the ContextMenu class. In Flash Player, only the ContextMenu class can be used. ContextMenus in AIR do not have built-in items; a default context menu is not displayed.
- Pop-up menus are supported on all operating systems. Pop-up menus are functionally the same as context menus, but are displayed using the menu `display()` method rather than as a response to a user interface event. A pop-up menu is not attached to any other object. Simply create the native menu and call the `display()` method.

A menu object contains menu items. A menu item can represent a command, a submenu, or a separator line. Add menu items to a menu using the `addItem()` or `addItemAt()` method. The display order of the menu items matches the order of the items in the menu's `items` array.

To create a submenu, add a menu item to the parent menu object. Assign the menu object representing the submenu to the `submenu` property of the matching menu item in the parent menu.

Note: The root menu of window and application menus must contain only submenu items; items that do not represent submenus may not be displayed and are contrary to user expectation for these types of menus.

Menus dispatch `select` events when a command item in the menu or one of its submenus is selected. (Submenu and separator items are not selectable.) The `target` property of the event object references the selected item.

Menus dispatch `preparing` events just before the menu is displayed and when a key equivalent attached to one of the items in the menu is pressed. You can use this event to update the contents of the menu based on the current state of the application.

Note: If you are using the Flex Framework, consider using the FlexNativeMenu class. It is typically easier to define menus declaratively in MXML than it is to write ActionScript code to create the menu structure item-by-item.

More examples

Working with menus

Related API Elements

flash.display.InteractiveObject.contextMenu
flash.display.NativeMenuItem
flash.display.NativeWindow.menu
flash.desktop.DockIcon
flash.desktop.SystemTrayIcon
flash.desktop.NativeApplication.menu
flash.desktop.NativeApplication.icon
mx.controls.FlexNativeMenu

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | isSupported : Boolean [static] [read-only] Indicates whether any form of native menu is supported on the client system. | NativeMenu
|  | items : Array The array of NativeMenuItem objects in this menu. | NativeMenu
|  | numItems : int [read-only] The number of NativeMenuItem objects in this menu. | NativeMenu
|  | parent : NativeMenu [read-only] The parent menu. | NativeMenu

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | NativeMenu() Creates a new NativeMenu object. | NativeMenu
|  | 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
|  | addItem(item:NativeMenuItem):NativeMenuItem Adds a menu item at the bottom of the menu. | NativeMenu
|  | addItemAt(item:NativeMenuItem, index:int):NativeMenuItem Inserts a menu item at the specified position. | NativeMenu
|  | addSubmenu(submenu:NativeMenu, label:String):NativeMenuItem Adds a submenu to the menu by inserting a new menu item. | NativeMenu
|  | addSubmenuAt(submenu:NativeMenu, index:int, label:String):NativeMenuItem Adds a submenu to the menu by inserting a new menu item at the specified position. | NativeMenu
|  | clone():NativeMenu Creates a copy of the menu and all items. | NativeMenu
|  | containsItem(item:NativeMenuItem):Boolean Reports whether this menu contains the specified menu item. | NativeMenu
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | display(stage:Stage, stageX:Number, stageY:Number):void Pops up this menu at the specified location. | NativeMenu
|  | getItemAt(index:int):NativeMenuItem Gets the menu item at the specified index. | NativeMenu
|  | getItemByName(name:String):NativeMenuItem Gets the menu item with the specified name. | NativeMenu
|  | getItemIndex(item:NativeMenuItem):int Gets the position of the specified item. | NativeMenu
|  | 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
|  | 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
|  | removeAllItems():void Removes all items from the menu. | NativeMenu
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | removeItem(item:NativeMenuItem):NativeMenuItem Removes the specified menu item. | NativeMenu
|  | removeItemAt(index:int):NativeMenuItem Removes and returns the menu item at the specified index. | NativeMenu
|  | setItemIndex(item:NativeMenuItem, index:int):void Moves a menu item to the specified position. | NativeMenu
|  | 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
|  | 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

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
|  | displaying | Dispatched by this NativeMenu object immediately before the menu is displayed. | NativeMenu
|  | preparing | Dispatched by the NativeMenu object when a key equivalent is pressed and immediately before the menu is displayed. | NativeMenu
|  | select | Dispatched by this NativeMenu object when one of its menu items or an item in one of its descendant submenus is selected. | NativeMenu

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.0

Indicates whether any form of native menu is supported on the client system.

Implementation
`public static function get isSupported():Boolean`

Related API Elements

flash.display.NativeWindow.supportsMenu
flash.desktop.NativeApplication

### items

property

`items:Array`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The array of NativeMenuItem objects in this menu.

The array is sorted in display order.

Note: This property is read-only in AIR 1.0. It became read/write in AIR 1.1.

Implementation
`public function get items():Array`
`public function set items(value:Array):void`

### numItems

property

`numItems:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The number of NativeMenuItem objects in this menu.

Implementation
`public function get numItems():int`

### parent

property

`parent:NativeMenu` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The parent menu.

The `parent` of the root (top-level) menu object is `null`.

Implementation
`public function get parent():NativeMenu`
Constructor Detail

### NativeMenu

()
Constructor

`public function NativeMenu()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a new NativeMenu object.

Method Detail

### addItem

()
method

`public function addItem(item:NativeMenuItem):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Adds a menu item at the bottom of the menu.

When creating a context menu, you can add either NativeMenuItem or ContextMenuItem objects. However, it is advisable to use only one type of object in a context menu so that all items in the menu have the same properties.

Note: Adding an item to a menu can cause an application to hang if the item's submenu is set to the menu itself (causing a circular reference).

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to add at the bottom of the menu.

Returns

| `NativeMenuItem`

Throws

| `ArgumentError` — If `item` is `null`.
| `ArgumentError` — If `item` is a member of another menu.

### addItemAt

()
method

`public function addItemAt(item:NativeMenuItem, index:int):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Inserts a menu item at the specified position. The position is indexed from the top. Set the `index` parameter to zero to insert the item at the top of the menu. All types of menus: window, application, system tray icon, dock icon, context, and pop-up, index the menu position from the top.

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to insert.
| `index:int` — The (zero-based) position in menu at which to insert the menu item. Note: Adding an item to a menu can cause an application to hang if the item's submenu is set to the menu itself (causing a circular reference).

Returns

| `NativeMenuItem`

Throws

| `ArgumentError` — If `item` is `null`.
| `ArgumentError` — If `item` is a member of another menu.
| `RangeError` — If the index is outside the bounds of the menu's `items` array.

### addSubmenu

()
method

`public function addSubmenu(submenu:NativeMenu, label:String):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Adds a submenu to the menu by inserting a new menu item.

Calling the `addSubMenu()` method is equivalent to creating a new menu item, adding it to the menu, and assigning a NativeMenu object to the item's `submenu` property.

Note: Adding a menu as a submenu of itself (in a circular reference) can cause an application to hang.

Parameters

| `submenu:NativeMenu` — The NativeMenu object that defines the submenu to be added.
| `label:String` — The display label for the menu item to be added.

Returns

| `NativeMenuItem` — The NativeMenuItem object created for the submenu.

### addSubmenuAt

()
method

`public function addSubmenuAt(submenu:NativeMenu, index:int, label:String):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Adds a submenu to the menu by inserting a new menu item at the specified position.

Calling the `addSubMenuAt()` method is equivalent to creating a new menu item, inserting it at the desired position in the menu, and assigning a NativeMenu object to the item's `submenu` property.

Note: Adding a menu as a submenu of itself (in a circular reference) can cause an application to hang.

Parameters

| `submenu:NativeMenu` — The NativeMenu object that defines the submenu to be added.
| `index:int` — The position in the `items` array of this menu at which to insert the menu item to be added.
| `label:String` — The display label for the menu item to be added.

Returns

| `NativeMenuItem` — The NativeMenuItem object created for the submenu.

### clone

()
method

`public function clone():NativeMenu`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a copy of the menu and all items.

Returns

| `NativeMenu`

### containsItem

()
method

`public function containsItem(item:NativeMenuItem):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Reports whether this menu contains the specified menu item.

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to look up.

Returns

| `Boolean` — `true` if `item` is in this menu.

### display

()
method

`public function display(stage:Stage, stageX:Number, stageY:Number):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Pops up this menu at the specified location.

Parameters

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

### getItemAt

()
method

`public function getItemAt(index:int):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Gets the menu item at the specified index.

Parameters

| `index:int` — The (zero-based) position of the item to return.

Returns

| `NativeMenuItem` — The NativeMenuItem object at the specified position in the menu.

Throws

| `RangeError` — If `index` is outside the bounds of the menu's `items` array.

### getItemByName

()
method

`public function getItemByName(name:String):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Gets the menu item with the specified name.

Note: The `name` property of menu items is not assigned by default.

Parameters

| `name:String` — The string to look up.

Returns

| `NativeMenuItem` — The NativeMenuItem object with the specified name or `null`, if no such item exists in the menu.

### getItemIndex

()
method

`public function getItemIndex(item:NativeMenuItem):int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Gets the position of the specified item.

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to look up.

Returns

| `int` — The (zero-based) position of the specified item in this menu or `-1`, if the item is not in this menu.

### removeAllItems

()
method

`public function removeAllItems():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Removes all items from the menu.

### removeItem

()
method

`public function removeItem(item:NativeMenuItem):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Removes the specified menu item.

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to remove from this menu.

Returns

| `NativeMenuItem`

Throws

| `RangeError` — If the `item` is not in this menu

### removeItemAt

()
method

`public function removeItemAt(index:int):NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Removes and returns the menu item at the specified index.

Parameters

| `index:int` — The (zero-based) position of the item to remove.

Returns

| `NativeMenuItem` — The NativeMenuItem object removed.

Throws

| `RangeError` — If `index` is outside the bounds of this menu's `items` array.

### setItemIndex

()
method

`public function setItemIndex(item:NativeMenuItem, index:int):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Moves a menu item to the specified position. If the item is not already in the menu, calling this method adds the item to the menu.

Parameters

| `item:NativeMenuItem` — The NativeMenuItem object to move.
| `index:int` — The (zero-based) position in the menu to which to move the `item`.

Throws

| `RangeError` — If `index` is outside the bounds of the menu's `items` array.

Event Detail

### displaying

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.DISPLAYING`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Dispatched by this NativeMenu object immediately before the menu is displayed.

Listen to this event to update the menu before it is displayed. A `displaying` event is also dispatched by the items in a menu.

The `preparing` event supersedes the `displaying` event and provides additional functionality. Listen for the `preparing` event or the `displaying` event, but not both.

Note: On Mac OS X, prior to AIR 2.6, menus and menu items dispatched a `displaying` event when the user pressed a key equivalent. (This event was not dispatched for key equivalent interaction on other operating systems.) As of AIR 2.6, `displaying` events are no longer dispatched when the user presses a key equivalent. Use the `preparing` event instead.

The `Event.DISPLAYING` constant defines the value of the `type` property of a `displaying` event object.

Note: This event does not go through a "capture phase" and is dispatched directly to the target, whether the target is on the display list or not.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object that is about to be displayed.

### preparing

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.PREPARING`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.6

Dispatched by the NativeMenu object when a key equivalent is pressed and immediately before the menu is displayed.

Listen to this event to update the menu either before it is displayed, or when a key equivalent is pressed by the user. The `preparing` event is dispatched before the key equivalent is fully evaluated. You can enable, disable, add, or remove items from the menu in the `preparing` event handler and those changes will be in effect when the key equivalent is processed. For example, if you remove or disable the menu item assigned to the triggering key equivalent, then the sequence of events is effectively canceled and no `select` event is dispatched. A `preparing` event is also dispatched by the items in a menu.

The `preparing` event supersedes the `displaying` event and provides additional functionality. Listen for the `preparing` event or the `displaying` event, but not both.

The `Event.PREPARING` constant defines the value of the `type` property of a `preparing` event object.

Note: This event does not go through a "capture phase" and is dispatched directly to the target, whether the target is on the display list or not.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`
`currentTarget` | The object that dispatched this event.
`target` | The object that dispatched this event.

### select

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.SELECT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Dispatched by this NativeMenu object when one of its menu items or an item in one of its descendant submenus is selected.

A `select` event bubbles from a menu item to its containing menu and on up through the parent menu chain to the root menu object. The `target` property of the event object references the selected NativeMenuItem object; the `currentTarget` property references this NativeMenu object.

The `Event.SELECT` constant defines the value of the `type` property of a `select` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object on which an item has been selected.

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