PackageTop Level
Classpublic dynamic class ContextMenuItem
InheritanceContextMenuItem Inheritance Object

Player version: Flash Player 7

The ContextMenuItem class allows you 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, and a callback handler (a function) that is invoked when the menu item is selected. To add a new context menu item to a context menu, you add it to the customItems array of a ContextMenu object.

You can enable or disable specific menu items, make items visible or invisible, or change the caption or callback handler associated with a menu item.

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. You can add no more than 15 custom items to a context menu. Each item must contain at least one visible character; control characters, newlines, and other white space characters are ignored. No item can be more than 100 characters long. Items 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 items are compared without regard to case, punctuation, or white space.

None of the following words can appear in a custom item: Macromedia, Flash Player, or Settings.



Public Properties
 Property
  caption : String
A string that specifies the menu item caption (text) displayed in the context menu.
  enabled : Boolean
A Boolean value that indicates whether the specified menu item is enabled or disabled.
  separatorBefore : Boolean
A Boolean value that indicates whether a separator bar should appear above the specified menu item.
  visible : Boolean
A Boolean value that indicates whether the specified menu item is visible when the Flash Player context menu is displayed.
 Properties inherited from class Object
 __proto__, __resolve, constructor, prototype
Public Methods
 Method
  
ContextMenuItem(caption:String, callbackFunction:Function, [separatorBefore:Boolean], [enabled:Boolean], [visible:Boolean])
Creates a new ContextMenuItem object that can be added to the ContextMenu.customItems array.
  
Creates and returns a copy of the specified ContextMenuItem object.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Events
 EventSummaryDefined by
  
onSelect = function(obj:Object, menuItem:Object) {}
Invoked when the specified menu item is selected from the Flash Player context menu.ContextMenuItem
Property detail
captionproperty
public var caption:String

Player version: Flash Player 7

A string that specifies the menu item caption (text) displayed in the context menu.


Example
The following example displays the caption for the selected menu item (Pause Game) in the Output panel:The following example writes the caption for the selected menu item (Pause Game) to the log file:
var my_cm:ContextMenu = new ContextMenu();
var menuItem_cmi:ContextMenuItem = new ContextMenuItem("Pause Game", onPause);
my_cm.customItems.push(menuItem_cmi);
function onPause(obj, menuItem) {
    trace("You chose: " + menuItem.caption);
}
this.menu = my_cm;

enabledproperty 
public var enabled:Boolean

Player version: Flash Player 7

A Boolean value that indicates whether the specified menu item is enabled or disabled. By default, this property is true.


Example
The following example creates two new context menu items: Start and Stop. When the user selects Start, the number of milliseconds from when the SWF file started is traced. Start is then disabled in the menu. When Stop is selected, the number of milliseconds that have elapsed since the SWF file started is traced. The Start menu item is re-enabled and the Stop menu item is disabled.
var my_cm:ContextMenu = new ContextMenu();
var startMenuItem:ContextMenuItem = new ContextMenuItem("Start", startHandler);
startMenuItem.enabled = true;
my_cm.customItems.push(startMenuItem);
var stopMenuItem:ContextMenuItem = new ContextMenuItem("Stop", stopHandler, true);
stopMenuItem.enabled = false;
my_cm.customItems.push(stopMenuItem);
function stopHandler(obj, item) {
    trace("Stopping... "+getTimer()+"ms");
    startMenuItem.enabled = true;
    stopMenuItem.enabled = false;
}
function startHandler(obj, item) {
    trace("Starting... "+getTimer()+"ms");
    startMenuItem.enabled = false;
    stopMenuItem.enabled = true;
}
this.menu = my_cm;

separatorBeforeproperty 
public var separatorBefore:Boolean

Player version: Flash Player 7

A Boolean value that indicates whether a separator bar should appear above the specified menu item. By default, this property is false.

Note: A separator bar always appears between any custom menu items and the built-in menu items.

See also


Example
This example creates three menu items, labeled Open, Save, and Print. A separator bar divides the Save and Print items. The menu items are then added to the ContextMenu object's customItems array. Finally, the menu is attached to the current Timeline of the SWF file.
var my_cm:ContextMenu = new ContextMenu();
var open_cmi:ContextMenuItem = new ContextMenuItem("Open", itemHandler);
var save_cmi:ContextMenuItem = new ContextMenuItem("Save", itemHandler);
var print_cmi:ContextMenuItem = new ContextMenuItem("Print", itemHandler);
print_cmi.separatorBefore = true;
my_cm.customItems.push(open_cmi, save_cmi, print_cmi);
function itemHandler(obj, menuItem) {
    trace("You chose: " + menuItem.caption);
};
this.menu = my_cm;

visibleproperty 
public var visible:Boolean

Player version: Flash Player 7

A Boolean value that indicates whether the specified menu item is visible when the Flash Player context menu is displayed. By default, this property is true.


Example
The following example creates two new context menu items: Start and Stop. When the user selects Start, the number of milliseconds from when the SWF file started is displayed. Start is then made invisible in the menu. When Stop is selected, the number of milliseconds that have elapsed since the SWF file started is displayed. The Start menu item is made visible and the Stop menu item is made invisible.
var my_cm:ContextMenu = new ContextMenu();
var startMenuItem:ContextMenuItem = new ContextMenuItem("Start", startHandler);
startMenuItem.visible = true;
my_cm.customItems.push(startMenuItem);
var stopMenuItem:ContextMenuItem = new ContextMenuItem("Stop", stopHandler, true);
stopMenuItem.visible = false;
my_cm.customItems.push(stopMenuItem);
function stopHandler(obj, item) {
    trace("Stopping... "+getTimer()+"ms");
    startMenuItem.visible = true;
    stopMenuItem.visible = false;
}
function startHandler(obj, item) {
    trace("Starting... "+getTimer()+"ms");
    startMenuItem.visible = false;
    stopMenuItem.visible = true;
}
this.menu = my_cm;

Constructor detail
ContextMenuItem()constructor
public function ContextMenuItem(caption:String, callbackFunction:Function, [separatorBefore:Boolean], [enabled:Boolean], [visible:Boolean])

Player version: Flash Player 7

Creates a new ContextMenuItem object that can be added to the ContextMenu.customItems array.

Parameters
caption:String — A string that specifies the text associated with the menu item.
 
callbackFunction:Function — A function that you define, which is called when the menu item is selected.
 
separatorBefore:Boolean [optional] — A Boolean value that indicates whether a separator bar should appear above the menu item in the context menu. The default value is false.
 
enabled:Boolean [optional] — A Boolean value that indicates whether the menu item is enabled or disabled in the context menu. The default value is true.
 
visible:Boolean [optional] — A Boolean value that indicates whether the menu item is visible or invisible. The default value is true.

Example
This example adds Start and Stop menu items, separated by a bar, to the ContextMenu object my_cm. The startHandler() function is called when Start is selected from the context menu; stopHandler() is called when Stop is selected. The ContextMenu object is applied to the current Timeline.
var my_cm:ContextMenu = new ContextMenu();
my_cm.customItems.push(new ContextMenuItem("Start", startHandler));
my_cm.customItems.push(new ContextMenuItem("Stop", stopHandler, true));
function stopHandler(obj, item) {
    trace("Stopping...");
}
function startHandler(obj, item) {
    trace("Starting...");
}
this.menu = my_cm;

Method detail
copy()method
public function copy():ContextMenuItem

Player version: Flash Player 7

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

Returns
ContextMenuItem — A ContextMenuItem object.

Example
This example creates a new ContextMenuItem object named original_cmi with the caption Pause and a callback handler set to the function onPause. The example then creates a copy of the ContextMenuItem object and assigns it to the variable copy_cmi.
var original_cmi:ContextMenuItem = new ContextMenuItem("Pause", onPause);
function onPause(obj:Object, menu:ContextMenu) {
    trace("pause me");
}

var copy_cmi:ContextMenuItem = original_cmi.copy();

var my_cm:ContextMenu = new ContextMenu();
my_cm.customItems.push(original_cmi);
my_cm.customItems.push(copy_cmi);

my_mc.menu = my_cm;

Event detail
onSelectevent handler

public onSelect = function(obj:Object, menuItem:Object) {}

Player version: Flash Player 7

Invoked when the specified menu item is selected from the Flash Player context menu. The specified callback handler receives two parameters: obj, a reference to the object under the mouse when the user invoked the Flash Player context menu, and item, a reference to the ContextMenuItem object that represents the selected menu item.

Parameters
obj:Object — A reference to the object (movie clip, Timeline, button, or selectable text field) on which the user right or Control clicked.
 
menuItem:Object — A reference to the selected ContextMenuItem object.

Example
The following example determines over what type of object the context menu was invoked.
var my_cmi:ContextMenu = new ContextMenu();
var start_cmi:ContextMenuItem = new ContextMenuItem("Start");
start_cmi.onSelect = function(obj, item) {
    trace("You chose: "+item.caption);
};
my_cmi.customItems.push(start_cmi);
my_cmi.customItems.push(new ContextMenuItem("Stop", stopHandler, true));
function stopHandler(obj, item) {
    trace("Stopping...");
}
this.menu = my_cmi;

See also