flash.ui

# ContextMenu - AS3

Package | flash.ui
Class | public final class ContextMenu
Inheritance | ContextMenu NativeMenu EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

The ContextMenu class provides control over the items displayed in context menus.

Mobile Browser Support: This class is not supported in mobile browsers.

AIR profile support: This feature is not supported on mobile devices or AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

In Flash Player, users open the context menu by right-clicking (Windows or Linux) or Control-clicking (Macintosh) Flash Player. You can use the methods and properties of the ContextMenu class to add custom menu items, control the display of the built-in context menu items (for example, Zoom In, and Print), or create copies of menus. In AIR, there are no built-in items and no standard context menu.

In Flash Professional, you can attach a ContextMenu object to a specific button, movie clip, or text field object, or to an entire movie level. You use the `contextMenu` property of the InteractiveObject class to do this.

In Flex or Flash Builder, only top-level components in the application can have context menus. For example, if a DataGrid control is a child of a TabNavigator or VBox container, the DataGrid control cannot have its own context menu.

To add new items to a ContextMenu object, you create a ContextMenuItem object, and then add that object to the `ContextMenu.customItems` array. For more information about creating context menu items, see the ContextMenuItem class entry.

Flash Player has three types of context menus: the standard menu (which appears when you right-click in Flash Player), the edit menu (which appears when you right-click a selectable or editable text field), and an error menu (which appears when a SWF file has failed to load into Flash Player). Only the standard and edit menus can be modified with the ContextMenu class. Only the edit menu appears in AIR.

Custom menu items always appear at the top of the Flash Player context menu, above any visible built-in menu items; a separator bar distinguishes built-in and custom menu items. You cannot remove the Settings menu item from the context menu. The Settings menu item is required in Flash so that users can access the settings that affect privacy and storage on their computers. You also cannot remove the About menu item, which is required so that users can find out what version of Flash Player they are using. (In AIR, the built-in Settings and About menu items are not used.)

You can add no more than 15 custom items to a context menu in Flash Player. In AIR, there is no explicit limit imposed on the number of items in a context menu.

You must use the `ContextMenu()` constructor to create a ContextMenu object before calling its methods.

View the examples

More examples

Working with menus

Related API Elements

ContextMenuItem class
flash.display.InteractiveObject.contextMenu

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | builtInItems : ContextMenuBuiltInItems An instance of the ContextMenuBuiltInItems class with the following properties: forwardAndBack, loop, play, print, quality, rewind, save, and zoom. | ContextMenu
|  | clipboardItems : ContextMenuClipboardItems An instance of the ContextMenuClipboardItems class with the following properties: cut, copy, paste, delete, selectAll. | ContextMenu
|  | clipboardMenu : Boolean Specifies whether or not the clipboard menu should be used. | ContextMenu
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | customItems : Array An array of ContextMenuItem objects. | ContextMenu
|  | isSupported : Boolean [static] [read-only] The isSupported property is set to true if the ContextMenu class is supported on the current platform, otherwise it is set to false. | ContextMenu
|  | items : Array [override] The array of custom items in this menu. | ContextMenu
|  | link : URLRequest The URLRequest of the link. | ContextMenu
|  | numItems : int [override] [read-only] The number of items in this menu. | ContextMenu
|  | parent : NativeMenu [read-only] The parent menu. | NativeMenu

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ContextMenu() Creates a ContextMenu object. | ContextMenu
|  | 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 [override] Adds a menu item at the bottom of the menu. | ContextMenu
|  | 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 [override] Creates a copy of the specified ContextMenu object. | ContextMenu
|  | containsItem(item:NativeMenuItem):Boolean [override] Reports whether this menu contains the specified menu item. | ContextMenu
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | display(stage:Stage, stageX:Number, stageY:Number):void [override] Pops up this menu at the specified location. | ContextMenu
|  | getItemAt(index:int):NativeMenuItem [override] Gets the menu item at the specified index. | ContextMenu
|  | getItemByName(name:String):NativeMenuItem Gets the menu item with the specified name. | NativeMenu
|  | getItemIndex(item:NativeMenuItem):int [override] Gets the position of the specified item. | ContextMenu
|  | 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
|  | hideBuiltInItems():void Hides all built-in menu items (except Settings) in the specified ContextMenu object. | ContextMenu
|  | 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 [override] Removes all items from the menu. | ContextMenu
|  | 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 [override] Removes and returns the menu item at the specified index. | ContextMenu
|  | 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
|  | menuSelect | Dispatched when a user first generates a context menu but before the contents of the context menu are displayed. | ContextMenu
|  | 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

### builtInItems

property

`builtInItems:ContextMenuBuiltInItems`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

An instance of the ContextMenuBuiltInItems class with the following properties: `forwardAndBack`, `loop`, `play`, `print`, `quality`, `rewind`, `save`, and `zoom`. Setting these properties to `false` removes the corresponding menu items from the specified ContextMenu object. These properties are enumerable and are set to `true` by default.

Note: In AIR, context menus do not have built-in items.

Implementation
`public function get builtInItems():ContextMenuBuiltInItems`
`public function set builtInItems(value:ContextMenuBuiltInItems):void`

Related API Elements

ContextMenuBuiltInItems class
ContextMenu.hideBuiltInItems()

### clipboardItems

property

`clipboardItems:ContextMenuClipboardItems`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

An instance of the ContextMenuClipboardItems class with the following properties: `cut`, `copy`, `paste`, `delete`, `selectAll`. Setting one of these properties to `false` disables the corresponding item in the clipboard menu.

Implementation
`public function get clipboardItems():ContextMenuClipboardItems`
`public function set clipboardItems(value:ContextMenuClipboardItems):void`

Related API Elements

ContextMenuClipboardItems class
Example ( How to use this example )
The following example demonstrates the use of the `clipboardItems` property of the `ContextMenu` object. Create a `ContextMenu`, and set its `clipboardMenu` property to `true`. Add an event handler for the `MENU_SELECT` (generally, right-click) event, and assign the menu to a display object. In this case, the `copy` and `paste` menus are enabled.
Copy

    package {
        import flash.ui.ContextMenu;
        import flash.events.ContextMenuEvent;
        import flash.display.Sprite;

        public class ContextMenuClipboardItemsExample extends Sprite {
            public function ContextMenuClipboardItemsExample() {
                var myContextMenu:ContextMenu = new ContextMenu();
                myContextMenu.clipboardMenu = true;
                myContextMenu.addEventListener(ContextMenuEvent.MENU_SELECT, menuSelectHandler);
                var rc:Sprite = new Sprite();
                rc.graphics.beginFill(0xDDDDDD);
                rc.graphics.drawRect(0,0,100,30);
                addChild(rc);
                rc.contextMenu = myContextMenu;
            }
            function menuSelectHandler(event:ContextMenuEvent):void {
                event.contextMenuOwner.contextMenu.clipboardItems.copy = true;
                event.contextMenuOwner.contextMenu.clipboardItems.paste = true;
            }
        }
    }

### clipboardMenu

property

`clipboardMenu:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

Specifies whether or not the clipboard menu should be used. If this value is `true`, the `clipboardItems` property determines which items are enabled or disabled on the clipboard menu.

If the `link` property is non-null, this `clipBoardMenu` property is ignored.

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

### customItems

property

`customItems:Array`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

An array of ContextMenuItem objects. Each object in the array represents a context menu item that you have defined. Use this property to add, remove, or modify these custom menu items.

To add new menu items, you create a ContextMenuItem object and then add it to the `customItems` array (for example, by using `Array.push()`). For more information about creating menu items, see the ContextMenuItem class entry.

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

Related API Elements

flash.display.InteractiveObject.contextMenu

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The `isSupported` property is set to `true` if the ContextMenu class is supported on the current platform, otherwise it is set to `false`.

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

### items

property

`items:Array`[override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The array of custom items in this menu.

Using this property is equivalent to using the `customItems` property. The array is sorted in display order.

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

### link

property

`link:URLRequest`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.5

The `URLRequest` of the link. If this property is `null`, a normal context menu is displayed. If this property is not `null`, the link context menu is displayed, and operates on the url specified.

If a `link` is specified, the `clipboardMenu` property is ignored.

The default value is `null`.

Implementation
`public function get link():URLRequest`
`public function set link(value:URLRequest):void`

### numItems

property

`numItems:int` [read-only] [override]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The number of items in this menu.

Implementation
`override public function get numItems():int`
Constructor Detail

### ContextMenu

()
Constructor

`public function ContextMenu()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Creates a ContextMenu object.

Related API Elements

ContextMenu.customItems
ContextMenu.hideBuiltInItems()
Method Detail

### addItemAt

()
method

`override public function addItemAt(item:NativeMenuItem, index:int):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.

Parameters

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

Returns

| `NativeMenuItem`

Throws

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

### clone

()
method

`override public function clone():NativeMenu`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Creates a copy of the specified ContextMenu object. The copy inherits all the properties of the original menu object.

Returns

| `NativeMenu` — A ContextMenu object with all the properties of the original menu object.

### containsItem

()
method

`override 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 item to look up.

Returns

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

### display

()
method

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

Runtime Versions: | AIR 1.0

Pops up this menu at the specified location.

Note: In Flash Player, this method is not supported.

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

`override 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 item at the specified position in the menu.

Throws

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

### getItemIndex

()
method

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

### hideBuiltInItems

()
method

`public function hideBuiltInItems():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Hides all built-in menu items (except Settings) in the specified ContextMenu object. If the debugger version of Flash Player is running, the Debugging menu item appears, although it is dimmed for SWF files that do not have remote debugging enabled.

This method hides only menu items that appear in the standard context menu; it does not affect items that appear in the edit and error menus.

This method works by setting all the Boolean members of `my_cm``.builtInItems` to `false`. You can selectively make a built-in item visible by setting its corresponding member in `my_cm``.builtInItems` to `true`.

Note: In AIR, context menus do not have built-in items. Calling this method will have no effect.

Related API Elements

ContextMenuBuiltInItems class
ContextMenu.builtInItems

### removeAllItems

()
method

`override public function removeAllItems():void`

Runtime Versions: | AIR 1.0

Removes all items from the menu.

### removeItemAt

()
method

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

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.

Event Detail

### menuSelect

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Dispatched when a user first generates a context menu but before the contents of the context menu are displayed. This allows your program to modify the set of context menu items before displaying the menu. The user generates the context menu by right-clicking the pointing device.

Defines the value of the `type` property of a `menuSelect` 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 ContextMenu object that is about to be displayed. 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
ContextMenuExample.as
The following example uses the class `ContextMenuExample` to remove the default context menu items from the Stage and add a new menu item, which, if clicked, changes the color of a square on the Stage. This is accomplished with the following steps:

1. A property `myContextMenu` is declared and then assigned to a new ContextMenu object and a property `redRectangle` of type Sprite is declared.
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 `Red to Black` menu selection into the `defaultItems` array by using the `push()` method of Array. A `menuItemSelect` event listener is added to the ContextMenuItem object and the associated method is called `menuItemSelectHandler()`. This method prints out some statements using `trace()` whenever the context menu is accessed and `Red to Black` is selected. Also the red square is removed and replaced with a black one.
4. An event listener of type `menuSelect` is added, along with the associated method `menuSelectHandler`, which simply prints out three statements using `trace()` every time an item in the context menu is opened.
5. Then `addChildren()` draws a red square and adds it to the display list, where it is immediately displayed.
6. Finally, `myContextMenu` is assigned to the context menu of the `redRectangle` sprite so that the custom context menu is displayed only when the mouse pointer is over the square.

Copy

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

        public class ContextMenuExample extends Sprite {
            private var myContextMenu:ContextMenu;
            private var menuLabel:String = "Reverse Colors";
            private var textLabel:String = "Right Click";
            private var redRectangle:Sprite;
            private var label:TextField;
            private var size:uint = 100;
            private var black:uint = 0x000000;
            private var red:uint = 0xFF0000;

            public function ContextMenuExample() {
                myContextMenu = new ContextMenu();
                removeDefaultItems();
                addCustomMenuItems();
                myContextMenu.addEventListener(ContextMenuEvent.MENU_SELECT, menuSelectHandler);

                addChildren();
                redRectangle.contextMenu = myContextMenu;
            }

            private function addChildren():void {
                redRectangle = new Sprite();
                redRectangle.graphics.beginFill(red);
                redRectangle.graphics.drawRect(0, 0, size, size);
                addChild(redRectangle);
                redRectangle.x = size;
                redRectangle.y = size;
                label = createLabel();
                redRectangle.addChild(label);
            }

            private function removeDefaultItems():void {
                myContextMenu.hideBuiltInItems();
                var defaultItems:ContextMenuBuiltInItems = myContextMenu.builtInItems;
                defaultItems.print = true;
            }

            private function addCustomMenuItems():void {
                var item:ContextMenuItem = new ContextMenuItem(menuLabel);
                myContextMenu.customItems.push(item);
                item.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, menuItemSelectHandler);
            }

            private function menuSelectHandler(event:ContextMenuEvent):void {
                trace("menuSelectHandler: " + event);
            }

            private function menuItemSelectHandler(event:ContextMenuEvent):void {
                trace("menuItemSelectHandler: " + event);
                var textColor:uint = (label.textColor == black) ? red : black;
                var bgColor:uint = (label.textColor == black) ? black : red;
                redRectangle.graphics.clear();
                redRectangle.graphics.beginFill(bgColor);
                redRectangle.graphics.drawRect(0, 0, size, size);
                label.textColor = textColor;
            }

            private function createLabel():TextField {
                var txtField:TextField = new TextField();
                txtField.text = textLabel;
                return txtField;
            }
        }
    }

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