flash.ui.ContextMenuItem (Flex 3)

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

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

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

	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 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
		toString():String 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

Summary	Defined By
activate	Dispatched when Flash Player or an AIR application gains operating system focus and becomes active.	EventDispatcher
deactivate	Dispatched when Flash Player or an AIR application loses operating 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
select	Dispatched whenever a menu item is selected by the user.	NativeMenuItem

Property Detail

caption

property

caption:String [read-write]

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 [read-write]

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]

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)

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).

Event Detail

menuItemSelect

Event

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

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:

A property myContextMenu is declared and then assigned to a new ContextMenu object.
The method removeDefaultItems() is called, which removes all built-in context menu items except Print.
The method addCustomMenuItems() is called, which places a menu item called Hello World into the customItems array by using the push() method of Array.
The Hello World context menu item is added to the Stage's context menu item list.
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;
        }
    }
}

ActionScript 3.0 Language and Components Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Conventions \| Frames No Frames
ContextMenuItem	Properties \| Methods \| Events \| Examples