ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
ContextMenu

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

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The ContextMenu class provides control over the items in the Flash Player context menu. Users open the context menu by right-clicking (Windows) 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.

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 `menu` property of the Button, MovieClip, or TextField class to do this. For more information about the `menu` property, see Button.menu, MovieClip.menu, and TextField.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.

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 can add no more than 15 custom items to a context menu. 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.

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

View the examples

See also

ContextMenuItem class
flash.display.InteractiveObject.contextMenu

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | builtInItems : ContextMenuBuiltInItems An object that has the following properties of the ContextMenuBuiltInItems class: forwardAndBack, loop, play, print, quality, rewind, save, and zoom. | ContextMenu
|  | clipboardItems : ContextMenuClipboardItems An object that has the following properties of the ContextMenuClipboardItems class: 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
|  | link : URLRequest The URLRequest of the link. | ContextMenu
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

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
|  | clone():ContextMenu Creates a copy of the specified ContextMenu object. | ContextMenu
|  | 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
|  | 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
|  | 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
|  | 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
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | menuSelect | Dispatched when a user first generates a context menu but before the contents of the context menu are displayed. | ContextMenu

Property Detail

builtInItems | property

`builtInItems:ContextMenuBuiltInItems` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

An object that has the following properties of the ContextMenuBuiltInItems class: `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.

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

See also

ContextMenuBuiltInItems class
ContextMenu.hideBuiltInItems()

clipboardItems | property |

`clipboardItems:ContextMenuClipboardItems` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

An object that has the following properties of the ContextMenuClipboardItems class: `cut`, `copy`, `paste`, `delete`, `selectAll`. Setting these properties to `false` disables the corresponding menu items in the clipboard menu. These properties are enumerable.

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

See also

ContextMenuClipboardItems class
Example
The following example demonstrates the use of the `clipboardItems` property of the `ContextMenu` object. A menu is created, and an event handler is added for the `MENU_SELECT` (generally, right-click) event. Depending on the context, menu items can be enabled or disabled. In this case, the `paste` menu is enabled.

    var myContextMenu:ContextMenu = new ContextMenu();
    myContextMenu.clipboardMenu = true;
    myContextMenu.addEventListener(ContextMenuEvent.MENU_SELECT, menuSelectHandler);
    mc1.contextMenu = myContextMenu;
    function menuSelectHandler(event:ContextMenuEvent):void {
        if (Clipboard.generalClipboard.hasFormat("myFormat")) {
            event.contextMenuOwner.contextMenu.clipboardItems.paste = true;
        }
    }

clipboardMenu | property |

`clipboardMenu:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

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

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

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

customItems | property |

`customItems:Array` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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`

See also

flash.display.InteractiveObject.contextMenu

link | property |

`link:URLRequest` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The `URLRequest` of the link. If this property is null, a normal context menu is displayed. If this property is non-null, the link context menu is displayed, and will operate 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`
Constructor Detail

ContextMenu | () | Constructor

`public function ContextMenu()`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates a ContextMenu object.

See also

ContextMenu.customItems
ContextMenu.hideBuiltInItems()
Method Detail

clone | () | method

`public function clone():ContextMenu`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Returns

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

hideBuiltInItems | () | method |

`public function hideBuiltInItems():void`

Language Version : | ActionScript 3.0

Player Version : | 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`.

See also

ContextMenuBuiltInItems class
ContextMenu.builtInItems
Event Detail

menuSelect | Event

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

Language Version : | ActionScript 3.0

Player Version : | 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 examples
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.

    package {
        import flash.ui.ContextMenu;
        import flash.ui.ContextMenuItem;
        import flash.ui.ContextMenuBuiltInItems;
        import flash.events.ContextMenuEvent;
        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;
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00