Packageflash.ui
Classpublic final class ContextMenuItem
InheritanceContextMenuItem Inheritance EventDispatcher Inheritance 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 context menu 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, or 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:

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
 PropertyDefined by
  caption : String
Specifies the menu item caption (text) displayed in the context menu.
ContextMenuItem
 Inheritedconstructor : 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
 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
  visible : Boolean
Indicates whether the specified menu item is visible when the Flash Player context menu is displayed.
ContextMenuItem
Events
 EventSummaryDefined by
  
menuItemSelect
Flash Player dispatches the menuItemSelect event when a user selects an item from a context menu.ContextMenuItem
Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods
 FunctionDefined 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
  
clone():ContextMenuItem
Creates and returns a copy of the specified ContextMenuItem object.
ContextMenuItem
 Inherited
dispatchEvent(event:Event):Boolean
Dispatches an event into the event flow.
EventDispatcher
 Inherited
hasEventListener(type:String):Boolean
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined.
Object
 Inherited
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
 Inherited
propertyIsEnumerable(name:String):Boolean
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
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
toString():String
Returns the string representation of the specified object.
Object
 Inherited
valueOf():Object
Returns the primitive value of the specified object.
Object
 Inherited
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
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
enabled property
enabled:Boolean  [read-write]

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]

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
Event detail
menuItemSelect event
Event object type: flash.events.ContextMenuEvent
ContextMenuEvent.type property = flash.events.ContextMenuEvent.MENU_ITEM_SELECT

Flash Player dispatches the menuItemSelect event 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.

This event has the following characteristics:

PropertiesValues
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.
bubblesNo.
currentTargetIndicates the object that is actively processing the Event object with an event listener.
cancelableNo. There is no default behavior to cancel.
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) — Specified 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. This parameter is optional.
visible:Boolean (default = true) — Specifies whether the menu item is visible or invisible. The default value is true.
Method detail
clone method

public function clone():ContextMenuItem

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.
Class examples

The following example uses the class ContextMenuBuiltInItemsExample to remove the normal right-click menu items from the stage and add a new menu item. This is accomplished using 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 right-click menu items except print.
  3. The method addCustomMenuItems() is called, which places an item called Hello World menu selection into the customItems Array using the push() method of Array.
  4. The Hello World right-click menu item is then added to the stage's right-click menu item list.
  5. Finally a TextField object with the text "Right Click" is added to the center of the stage via addChild() via createLabel().
package {
    import flash.ui.ContextMenu;
    import flash.ui.ContextMenuItem;
    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";
            txtField.x = this.stage.stageWidth/2 - txtField.width/2;
            txtField.y = this.stage.stageHeight/2 - txtField.height/2;
            return txtField;
        }
    }
}



© 1996-2006 Adobe Systems Incorporated. All rights reserved.
Fri Apr 21 2006, 12:34 PDT

 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/labs/flashauthoringpreview/flash/ui/ContextMenuItem.html