flash.display

# NativeMenuItem - AS3

Package | flash.display
Class | public class NativeMenuItem
Inheritance | NativeMenuItem EventDispatcher Object
Subclasses | ContextMenuItem

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The NativeMenuItem class represents a single item in a menu.

A menu item can be a command, a submenu, or a separator line:

- To create a command item, call the NativeMenuItem constructor, passing in a string for the label and `false` for the `isSeparator` parameter.
- To create a submenu, create a command item for the parent menu and assign the NativeMenu object of the submenu to the item's `submenu` property. You can also call the `addSubmenu()` method of the parent NativeMenu object to create the item and set the `submenu` property at the same time.
- To create a separator, call the NativeMenuItem constructor, passing in an empty string for the label and `true` for the `isSeparator` parameter.

Listen for `select` events on an item or a parent menu to detect when a menu command is selected. Neither submenus nor separators dispatch select events. Listen for `preparing` events to determine when a menu item is about to be displayed or activated through a key equivalent.

More examples

Working with menus

Related API Elements

flash.display.NativeMenu
flash.display.NativeMenu.addSubmenu()

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | checked : Boolean Controls whether this menu item displays a checkmark. | NativeMenuItem
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | data : Object An arbitrary data object associated with this menu item. | NativeMenuItem
|  | enabled : Boolean Controls whether this menu item is enabled. | NativeMenuItem
|  | isSeparator : Boolean [read-only] Reports whether this item is a menu separator line. | NativeMenuItem
|  | keyEquivalent : String The key equivalent for this menu item. | NativeMenuItem
|  | keyEquivalentModifiers : Array The array of key codes for the key equivalent modifiers. | NativeMenuItem
|  | label : String The display string of this menu item. | NativeMenuItem
|  | menu : NativeMenu [read-only] The menu that contains this item. | NativeMenuItem
|  | mnemonicIndex : int The position of the mnemonic character in the menu item label. | NativeMenuItem
|  | name : String The name of this menu item. | NativeMenuItem
|  | submenu : NativeMenu The submenu associated with this menu item. | NativeMenuItem

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | NativeMenuItem(label:String = "", isSeparator:Boolean = false) Creates a new NativeMenuItem object. | NativeMenuItem
|  | 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
|  | clone():NativeMenuItem Creates a copy of the NativeMenuItem object. | NativeMenuItem
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | 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
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | 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 [override] Returns a string containing all the properties of the NativeMenuItem object. | NativeMenuItem
|  | 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 NativeMenuItem object immediately before the menu containing the item is displayed. | NativeMenuItem
|  | preparing | Dispatched by this NativeMenuItem object when its key equivalent is pressed and immediately before the containing menu is displayed. | NativeMenuItem
|  | select | Dispatched whenever a menu item is selected by the user. | NativeMenuItem

Property Detail

### checked

property

`checked:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Controls whether this menu item displays a checkmark.

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

### data

property

`data:Object`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

An arbitrary data object associated with this menu item.

You can assign any object to this property. The assigned object is not used by the menu system, but is available to event handling code (through the target property of the event object). By default, the value of this property is `null`.

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

### enabled

property

`enabled:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Controls whether this menu item is enabled.

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

### isSeparator

property

`isSeparator:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Reports whether this item is a menu separator line.

Create a separator line by setting the `isSeparator` parameter in the NativeMenuItem constructor to `true`.

Implementation
`public function get isSeparator():Boolean`

### keyEquivalent

property

`keyEquivalent:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The key equivalent for this menu item.

Set the `keyEquivalent` with a lowercase letter to assign a shortcut without a Shift-key modifier. Set with an uppercase letter to assign a shortcut with the Shift-key modifier.

By default, a key equivalent modifier (Ctrl on Windows or Linux and Command on Mac OS X) is included as part of the key equivalent. If you want the key equivalent to be a key with no modifier, set the `keyEquivalentModifiers` property to an empty array.

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

### keyEquivalentModifiers

property

`keyEquivalentModifiers:Array`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The array of key codes for the key equivalent modifiers.

Use the constants defined in the Keyboard class to specify the modifier key codes. Valid modifier keys include:

- `Keyboard.ALTERNATE`
- `Keyboard.COMMAND`
- `Keyboard.CONTROL`

If you do not assign any modifiers, then by default the `Keyboard.CONTROL` key is assigned on Windows or Linux and the `Keyboard.COMMAND` key is assigned on Mac OS X. If you do not want the key equivalent to include these modifiers, set this property to an empty array.

If you assign an uppercase letter to the `keyEquivalent` property, the Shift key is used as a modifier automatically. Setting `keyEquivalentModifier` to an empty array does not remove the Shift key as a modifier.

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

Related API Elements

flash.ui.Keyboard

### label

property

`label:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The display string of this menu item.

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

### menu

property

`menu:NativeMenu` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The menu that contains this item.

Implementation
`public function get menu():NativeMenu`

### mnemonicIndex

property

`mnemonicIndex:int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The position of the mnemonic character in the menu item label.

The character at the specified position is the mnemonic character for the menu item. The index is zero-based, so the first character has an index of 0.

This property is ignored on operating systems that do not use menu mnemonics.

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

### name

property

`name:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The name of this menu item.

The name value is not displayed and can be used as a locale-independent identifier. A name is not assigned automatically.

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

### submenu

property

`submenu:NativeMenu`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The submenu associated with this menu item.

Assigning a NativeMenu object to this property changes the appearance and behavior of the menu item. A submenu item displays the submenu icon and no longer dispatches select events.

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

Implementation
`public function get submenu():NativeMenu`
`public function set submenu(value:NativeMenu):void`

Related API Elements

flash.display.NativeMenu.addSubmenu()
Constructor Detail

### NativeMenuItem

()
Constructor

`public function NativeMenuItem(label:String = "", isSeparator:Boolean = false)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a new NativeMenuItem object.

To create a menu command, set the `label` parameter to a string containing the display label and set `isSeparator` to `false`.

To create a submenu command, create a command item and then assign the NativeMenu object for the submenu to the item's `submenu` property. Add the item to the parent menu.

To create a separator, set the `label` parameter to an empty string and set `isSeparator` to `true`.

Add and remove items from a menu using the NativeMenu `addItem()` and `removeItem()` methods.

Parameters

| `label:String` (default = "``")`` — The display label for the item, or an empty string for separators.
| `isSeparator:Boolean` (default = `false`)`` — Set to `true` to create a separator; set to `false` otherwise.

Related API Elements

flash.display.NativeMenu.addSubmenu()
Method Detail

### clone

()
method

`public function clone():NativeMenuItem`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a copy of the NativeMenuItem object.

Returns

| `NativeMenuItem`

### toString

()
method

`override public function toString():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Returns a string containing all the properties of the NativeMenuItem object.

Returns

| `String` — A string containing all the properties of the Event object.

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 NativeMenuItem object immediately before the menu containing the item is displayed.

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.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 this NativeMenuItem object when its key equivalent is pressed and immediately before the containing menu is displayed.

Listen to this event to update the item either before the containing menu is displayed, or when its key equivalent is pressed by the user. The `preparing` event is dispatched before the key equivalent is fully evaluated. You can enable, disable, or remove the item 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 this menu item, then the sequence of events is effectively canceled and no `select` event is dispatched. A `preparing` event is also dispatched by the other 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 whenever a menu item is selected by the user.

A `select` event bubbles from this 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 this NativeMenuItem object; the `currentTarget` property references the dispatching object (either this NativeMenuItem or an ancestral NativeMenu object).

Note: If the window containing the menu is in fullscreen mode (`stage.displayState == StageDisplayState.FULL_SCREEN`), the NativeMenuItem object does not dispatch a `select` event when the user enters a keyboard equivalent for a menu item.

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