PackageTop Level
Classpublic dynamic class ContextMenu
InheritanceContextMenu Inheritance Object

Player version: Flash Player 7

The ContextMenu class provides runtime control over the items in the Flash Player context menu, which appears when a user right-clicks (Windows) or Control-clicks (Macintosh) on Flash Player. You can use the methods and properties of the ContextMenu class to add custom menu items, control the display of the built-in context menu items (for example, Zoom In and Print), or create copies of menus.

You can attach a ContextMenu object to a specific button, movie clip, or text field object, or to an entire movie level. You use the menu property of the Button, MovieClip, or TextField classes to do this. For more information about the menu property, see Button.menu, MovieClip.menu, and TextField.menu.

In Flex, only top-level components in the application can have context menus. For example, if a DataGrid control is a child of a TabNavigator or VBox container, the DataGrid control cannot have its own context menu.

To add new items to a ContextMenu object, you create a ContextMenuItem object, and then add that object to the ContextMenu.customItems array. For more information about creating context menu items, see the ContextMenuItem class entry.

Flash Player has three types of context menus: the standard menu (which appears when you right-click in Flash Player), the edit menu (which appears when you right-click over a selectable or editable text field), and an error menu (which appears when a SWF file has failed to load into Flash Player.) Only the standard and edit menus can be modified with the ContextMenu class.

Custom menu items always appear at the top of the Flash Player context menu, above any visible built-in menu items; a separator bar distinguishes built-in and custom menu items. You can add no more than 15 custom items to a context menu. You cannot remove the Settings menu item from the context menu. The Settings menu item is required in Flash so users can access the settings that affect privacy and storage on their computers. You also cannot remove the About menu item from the context menu, which is required so users can find out what version of Flash Player they are using.

You must use the constructor new ContextMenu() to create a ContextMenu object before calling its methods.

See also

ContextMenuItem class
Button.menu
MovieClip.menu
TextField.menu


Public Properties
 Property
  builtInItems : Object
An object that has the following Boolean properties: zoom, quality, play, loop, rewind, forward_back, and print.
  customItems : Array
An array of ContextMenuItem objects.
 Properties inherited from class Object
 __proto__, __resolve, constructor, prototype
Public Methods
 Method
  
ContextMenu([callbackFunction:Function])
Creates a new ContextMenu object.
  
Creates a copy of the specified ContextMenu object.
  
Hides all built-in menu items (except Settings) in the specified ContextMenu object.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Events
 EventSummaryDefined by
  
onSelect = function(item:Object, item_menu:Object) {}
Called when a user invokes the Flash Player context menu, but before the menu is actually displayed.ContextMenu
Property detail
builtInItemsproperty
public var builtInItems:Object

Player version: Flash Player 7

An object that has the following Boolean properties: zoom, quality, play, loop, rewind, forward_back, and print. Setting these variables to false removes the corresponding menu items from the specified ContextMenu object. These properties are enumerable and are set to true by default.


Example
In this example, the built-in Quality and Print menu items are disabled for the ContextMenu object my_cm, which is attached to the current Timeline of the SWF file.
var my_cm:ContextMenu = new ContextMenu ();
my_cm.builtInItems.quality=false;
my_cm.builtInItems.print=false;
this.menu = my_cm;

Note: You cannot disable the Settings or About menu items from the context menu.

In the next example, a for..in loop enumerates through all names and values of the built-in menu items of the ContextMenu object, my_cm.

var my_cm:ContextMenu = new ContextMenu();
for(eachProp in my_cm.builtInItems) {
    var propName = eachProp;
    var propValue = my_cm.builtInItems[propName];
    trace(propName + ": " + propValue);
}

customItemsproperty 
public var customItems:Array

Player version: Flash Player 7

An array of ContextMenuItem objects. Each object in the array represents a context menu item that you have defined. Use this property to add, remove, or modify these custom menu items.

To add new menu items, you first create a new ContextMenuItem object, and then add it to the menu_mc.customItems array (for example, using Array.push()). For more information about creating new menu items, see the ContextMenuItem class entry.

See also


Example
The following example creates a new custom menu item called menuItem_cmi with a caption of "Send e-mail" and a callback handler named emailHandler. The new menu item is then added to the ContextMenu object, my_cm, using the customItems array. Finally, the new menu is attached to a movie clip named email_mc. To make this example work, create a movie clip instance on your stage, and use the Property Inspector to name the instance email_mc. In Test Movie mode, the new context menu item will appear if you bring up the context menu while your pointer is over the email_mc movie clip.
var my_cm:ContextMenu = new ContextMenu();
var menuItem_cmi:ContextMenuItem = new ContextMenuItem("Send e-mail", emailHandler);
my_cm.customItems.push(menuItem_cmi);
email_mc.menu = my_cm;
function emailHandler() {
    trace("sending email");
}

Constructor detail
ContextMenu()constructor
public function ContextMenu([callbackFunction:Function])

Player version: Flash Player 7

Creates a new ContextMenu object. You can optionally specify an identifier for an event handler when you create the object. The specified function is called when the user invokes the context menu, but before the menu is actually displayed. This is useful for customizing menu contents based on application state or based on the type of object (movie clip, text field, or button) or the Timeline that the user right-clicks or Control-clicks. (For an example of creating an event handler, see ContextMenu.onSelect.)

Parameters
callbackFunction:Function [optional] — A reference to a function that is called when the user right-clicks or Control-clicks, before the menu is displayed.

See also


Example
The following example hides all the built-in objects in the Context menu. (However, the Settings and About items still appear, because they cannot be disabled.)
var newMenu:ContextMenu = new ContextMenu();
newMenu.hideBuiltInItems();
this.menu = newMenu;

In this example, the specified event handler, menuHandler, enables or disables a custom menu item (using the ContextMenu.customItems array) based on the value of a Boolean variable named showItem. If false, the custom menu item is disabled; otherwise, it's enabled.

var showItem = true;  // Change this to false to remove
var my_cm:ContextMenu = new ContextMenu(menuHandler);
my_cm.customItems.push(new ContextMenuItem("Hello", itemHandler));
function menuHandler(obj, menuObj) {
    if (showItem == false) {
    menuObj.customItems[0].enabled = false;
    } else {
    menuObj.customItems[0].enabled = true;
    }
}
function itemHandler(obj, item) {
    //...put code here...
    trace("selected!");
}
this.menu = my_cm;

When the user right-clicks or Control-clicks the Stage, the custom menu is displayed.

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

Player version: Flash Player 7

Creates a copy of the specified ContextMenu object. The copy inherits all the properties of the original menu object.

Returns
ContextMenu — A ContextMenu object.

Example
This example creates a copy of the ContextMenu object named my_cm whose built-in menu items are hidden, and adds a menu item with the text "Save...". It then creates a copy of my_cm and assigns it to the variable clone_cm, which inherits all the properties of the original menu.
var my_cm:ContextMenu = new ContextMenu();
my_cm.hideBuiltInItems();
var menuItem_cmi:ContextMenuItem = new ContextMenuItem("Save...", saveHandler);
my_cm.customItems.push(menuItem_cmi);
function saveHandler(obj, menuItem) {
    // saveDocument();
    // custom function (not shown)
    trace("something");
}
clone_cm = my_cm.copy();
this.menu = my_cm;
for (var i in clone_cm.customItems) {
    trace("clone_cm-> "+clone_cm.customItems[i].caption);
}
for (var i in my_cm.customItems) {
    trace("my_cm-> "+my_cm.customItems[i].caption);
}

hideBuiltInItems()method 
public function hideBuiltInItems():Void

Player version: Flash Player 7

Hides all built-in menu items (except Settings) in the specified ContextMenu object. If the Flash Debug Player is running, the Debugging menu item shows, although it is dimmed for SWF files that don't have remote debugging enabled.

This method hides only menu items that appear in the standard context menu; it does not affect items that appear in the edit or error menus.

This method works by setting all the Boolean members of my_cm.builtInItems to false. You can selectively make a built-in item visible by setting its corresponding member in my_cm.builtInItems to true (as demonstrated in the following example).


Example
The following example creates a new ContextMenu object named my_cm whose built-in menu items are hidden, except for Print. The menu object is attached to the current Timeline.
var my_cm:ContextMenu = new ContextMenu();
my_cm.hideBuiltInItems();
my_cm.builtInItems.print = true;
this.menu = my_cm;

Event detail
onSelectevent handler

public onSelect = function(item:Object, item_menu:Object) {}

Player version: Flash Player 7

Called when a user invokes the Flash Player context menu, but before the menu is actually displayed. This event handler allows customization of the contents of the context menu based on the current application state.

It is also possible to specify the callback handler for a ContextMenu object when constructing a new ContextMenu object. For more information, see the ContextMenuItem onSelect entry.

Parameters
item:Object — A reference to the object (movie clip, button, or selectable text field) that was under the mouse pointer when the Flash Player context menu was invoked and whose menu property is set to a valid ContextMenu object.
 
item_menu:Object — A reference to the ContextMenu object assigned to the menu property of object.

Example
The following example determines over what type of object the context menu was invoked.
var my_cm:ContextMenu = new ContextMenu();
function menuHandler(obj:Object, menu:ContextMenu) {
    if(obj instanceof MovieClip) {
        trace("Movie clip: " + obj);
    }
    if(obj instanceof TextField) {
        trace("Text field: " + obj);
    }
    if(obj instanceof Button) {
        trace("Button: " + obj);
    }
}
my_cm.onSelect = menuHandler;
my_mc.menu = my_cm;
my_btn.menu = my_cm;