Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.ui 
ContextMenuItem 
Packageflash.ui
Classpublic final class ContextMenuItem
InheritanceContextMenuItem Inheritance NativeMenuItem Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 9, AIR 1.0

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

See also



Public Properties
 PropertyDefined By
  caption : String
Specifies the menu item caption (text) displayed in the context menu.
ContextMenuItem
 InheritedAIR-only checked : Boolean
Controls whether this menu item displays a checkmark.
NativeMenuItem
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedAIR-only data : Object
An arbitrary data object associated with this menu item.
NativeMenuItem
 InheritedAIR-only enabled : Boolean
Controls whether this menu item is enabled.
NativeMenuItem
 InheritedAIR-only isSeparator : Boolean
[read-only] Reports whether this item is a menu separator line.
NativeMenuItem
 InheritedAIR-only keyEquivalent : String
The key equivalent for this menu item.
NativeMenuItem
 InheritedAIR-only keyEquivalentModifiers : Array
The array of key codes for the key equivalent modifiers.
NativeMenuItem
 InheritedAIR-only label : String
The display string of this menu item.
NativeMenuItem
 InheritedAIR-only menu : NativeMenu
[read-only] The menu that contains this item.
NativeMenuItem
 InheritedAIR-only mnemonicIndex : int
The position of the mnemonic character in the menu item label.
NativeMenuItem
 InheritedAIR-only name : String
The name of this menu item.
NativeMenuItem
 Inheritedprototype : 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
 InheritedAIR-only 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
 MethodDefined 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
 Inherited
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
  
[override] Creates a copy of the NativeMenuItem object.
ContextMenuItem
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
[override] Returns a string containing all the properties of the NativeMenuItem object.
NativeMenuItem
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
 InheritedDispatched by this NativeMenuItem object immediately before the menu containing the item is displayed.NativeMenuItem
  Dispatched when a user selects an item from a context menu.ContextMenuItem
 InheritedDispatched whenever a menu item is selected by the user.NativeMenuItem
Property Detail

caption

property
caption:String

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 9, AIR 1.0

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: Flash Player 9, AIR 1.0

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: Flash Player 9, AIR 1.0

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

AIR-only clone

()method
override public function clone():NativeMenuItem

Runtime Versions: AIR 1.0

Creates a copy of the NativeMenuItem object.

Returns
NativeMenuItem
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: Flash Player 9, AIR 1.0

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
contextMenuOwnerThe display list object to which the menu is attached.
currentTargetThe object that is actively processing the Event object with an event listener.
mouseTargetThe display list object on which the user right-clicked to display the context menu.
targetThe 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.
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;
        }
    }
}