flash.ui

# ContextMenuItem - AS3

Package | flash.ui
Class | public final class ContextMenuItem
Inheritance | ContextMenuItem NativeMenuItem EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

The ContextMenuItem class represents an item in the context menu. Each ContextMenuItem object has a caption (text) that is displayed in the context menu. To add a new item to a context menu, you add it to the `customItems` array of a ContextMenu object.

With the properties of the ContextMenuItem class you can enable or disable specific menu items, and you can make items visible or invisible.

You write an event handler for the `menuItemSelect` event to add functionality to the menu item when the user selects it.

Custom menu items appear at the top of the context menu, above any built-in items. A separator bar divides custom menu items from built-in items. In AIR, there are no built-in items and the following restrictions do not apply to content in the AIR application sandbox.

Restrictions:

- You can add no more than 15 custom items to a context menu.
- Each caption must contain at least one visible character.
- Control characters, newlines, and other white space characters are ignored.
- No caption can be more than 100 characters long.
- Captions that are identical to any built-in menu item, or to another custom item, are ignored, whether the matching item is visible or not. Menu captions are compared to built-in captions or existing custom captions without regard to case, punctuation, or white space.
- The following captions are not allowed, but the words may be used in conjunction with other words to form a custom caption (for example, although "Paste" is not allowed, "Paste tastes great" is allowed):

       Save
       Zoom In
       Zoom Out
       100%
       Show All
       Quality
       Play
       Loop
       Rewind
       Forward
       Back
       Movie not loaded
       About
       Print
       Show Redraw Regions
       Debugger
       Undo
       Cut
       Copy
       Paste
       Delete
       Select All
       Open
       Open in new window
       Copy link

- None of the following words can appear in a custom caption on their own or in conjunction with other words:

       Adobe
       Macromedia
       Flash Player
       Settings

Note: When the player is running on a non-English system, the caption strings are compared to both the English list and the localized equivalents.

View the examples

More examples

Working with menus

Related API Elements

ContextMenu class
ContextMenuBuiltInItems class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | caption : String Specifies the menu item caption (text) displayed in the context menu. | ContextMenuItem
|  | 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
|  | separatorBefore : Boolean Indicates whether a separator bar should appear above the specified menu item. | ContextMenuItem
|  | submenu : NativeMenu The submenu associated with this menu item. | NativeMenuItem
|  | visible : Boolean Indicates whether the specified menu item is visible when the Flash Player context menu is displayed. | ContextMenuItem

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ContextMenuItem(caption:String, separatorBefore:Boolean = false, enabled:Boolean = true, visible:Boolean = true) Creates a new ContextMenuItem object that can be added to the ContextMenu.customItems array. | ContextMenuItem
|  | 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 [override] Creates a copy of the NativeMenuItem object. | ContextMenuItem
|  | 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
|  | systemClearMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemCopyLinkMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemCopyMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemCutMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemOpenLinkMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemPasteMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | systemSelectAllMenuItem():ContextMenuItem [static] | ContextMenuItem
|  | 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
|  | menuItemSelect | Dispatched when a user selects an item from a context menu. | ContextMenuItem
|  | 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

### caption

property

`caption:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Specifies the menu item caption (text) displayed in the context menu. See the ContextMenuItem class overview for `caption` value restrictions.

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

### separatorBefore

property

`separatorBefore:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Indicates whether a separator bar should appear above the specified menu item.

Note: A separator bar always appears between any custom menu items and the built-in menu items.

The default value is `false.`

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

### visible

property

`visible:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Indicates whether the specified menu item is visible when the Flash Player context menu is displayed.

The default value is `true.`

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

### ContextMenuItem

()
Constructor

`public function ContextMenuItem(caption:String, separatorBefore:Boolean = false, enabled:Boolean = true, visible:Boolean = true)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Creates a new ContextMenuItem object that can be added to the `ContextMenu.customItems` array.

Parameters

| `caption:String` — Specifies the text associated with the menu item. See the ContextMenuItem class overview for `caption` value restrictions.
| `separatorBefore:Boolean` (default = `false`)`` — Specifies whether a separator bar appears above the menu item in the context menu. The default value is `false`.
| `enabled:Boolean` (default = `true`)`` — Specifies whether the menu item is enabled or disabled in the context menu. The default value is `true` (enabled). This parameter is optional.
| `visible:Boolean` (default = `true`)`` — Specifies whether the menu item is visible or invisible. The default value is `true` (visible).

Method Detail

### clone

()
method

`override public function clone():NativeMenuItem`

Creates a copy of the NativeMenuItem object.

Returns

| `NativeMenuItem`

### systemClearMenuItem

()
method

`public static function systemClearMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemCopyLinkMenuItem

()
method

`public static function systemCopyLinkMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemCopyMenuItem

()
method

`public static function systemCopyMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemCutMenuItem

()
method

`public static function systemCutMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemOpenLinkMenuItem

()
method

`public static function systemOpenLinkMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemPasteMenuItem

()
method

`public static function systemPasteMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

### systemSelectAllMenuItem

()
method

`public static function systemSelectAllMenuItem():ContextMenuItem`

Returns

| `ContextMenuItem`

Event Detail

### menuItemSelect

Event

Event Object Type: `flash.events.ContextMenuEvent`
property ContextMenuEvent.type = `flash.events.ContextMenuEvent.MENU_ITEM_SELECT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Dispatched when a user selects an item from a context menu. The user generates the context menu by clicking the secondary button of the user's pointing device.

Defines the value of the `type` property of a `menuItemSelect` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`contextMenuOwner` | The display list object to which the menu is attached.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`mouseTarget` | The display list object on which the user right-clicked to display the context menu.
`target` | The ContextMenuItem object that has been selected. The target is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.

Examples How to use this example
ContextMenuItemExample.as
The following example uses the class `ContextMenuBuiltInItemsExample` to remove the default context menu items from the Stage and add a new menu item. This is accomplished with the following steps:

1. A property `myContextMenu` is declared and then assigned to a new ContextMenu object.
2. The method `removeDefaultItems()` is called, which removes all built-in context menu items except Print.
3. The method `addCustomMenuItems()` is called, which places a menu item called `Hello World` into the `customItems` array by using the `push()` method of Array.
4. The `Hello World` context menu item is added to the Stage's context menu item list.
5. A TextField object with the text "Right Click Here" is added to the stage.

Copy

    package {
        import flash.ui.ContextMenu;
        import flash.ui.ContextMenuItem;
        import flash.ui.ContextMenuBuiltInItems;
        import flash.display.Sprite;
        import flash.text.TextField;

        public class ContextMenuItemExample extends Sprite {
            private var myContextMenu:ContextMenu;

            public function ContextMenuItemExample() {
                myContextMenu = new ContextMenu();
                removeDefaultItems();
                addCustomMenuItems();
                this.contextMenu = myContextMenu;
                addChild(createLabel());
            }

            private function removeDefaultItems():void {
                myContextMenu.hideBuiltInItems();

                var defaultItems:ContextMenuBuiltInItems = myContextMenu.builtInItems;
                defaultItems.print = true;
            }

            private function addCustomMenuItems():void {
                var item:ContextMenuItem = new ContextMenuItem("Hello World");
                myContextMenu.customItems.push(item);
            }

            private function createLabel():TextField {
                var txtField:TextField = new TextField();
                txtField.text = "Right Click Here";
                return txtField;
            }
        }
    }

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