Flash 8 ActionScript 2.0 Language Reference

Class ContextMenu

Object

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.

builtInItems Property

public builtInItems : Object

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);
}

customItems Property

public customItems : Array

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.

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");
}

onSelect Event Handler

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

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.

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;

ContextMenu Constructor

public ContextMenu([callbackFunction:Function])

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.

copy Method

public copy() : ContextMenu

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 hideBuiltInItems() : Void

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

var my_cm:ContextMenu = new ContextMenu();
my_cm.hideBuiltInItems();
my_cm.builtInItems.print = true;
this.menu = my_cm;