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

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

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Use the ContextMenuItem class to create custom menu items to display in the Flash Player 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 always divides custom menu items from built-in items.

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

See also

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
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | enabled : Boolean Indicates whether the specified menu item is enabled or disabled. | ContextMenuItem
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | separatorBefore : Boolean Indicates whether a separator bar should appear above the specified menu item. | ContextMenuItem
|  | 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():ContextMenuItem Creates and returns a copy of the specified ContextMenuItem 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
|  | 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
|  | menuItemSelect | Dispatched when a user selects an item from a context menu. | ContextMenuItem

Property Detail

caption | property

`caption:String` [read-write]

Language Version : | ActionScript 3.0

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

enabled | property |

`enabled:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Indicates whether the specified menu item is enabled or disabled.

The default value is `true`.

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

separatorBefore | property |

`separatorBefore:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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` [read-write]

Language Version : | ActionScript 3.0

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

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

`public function clone():ContextMenuItem`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates and returns a copy of the specified ContextMenuItem object. The copy includes all properties of the original object.

Returns

| `ContextMenuItem` — A ContextMenuItem object that contains all the properties of the original object.

Event Detail

menuItemSelect | Event

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

Language Version : | ActionScript 3.0

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

    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;
            }
        }
    }

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