The native menu classes allow you to access the native menu features of the operating system on which your application is running. NativeMenu objects can be used for application menus (available on OS X), window menus (available on Windows), context menus, and pop-up menus.

Contents

• AIR menu classes
• Menu varieties
• Menu structure
• Menu events
• Key equivalents for menu commands
• Mnemonics
• Menu item state
• Attaching an object to a menu item

AIR menu classes

The AIR Menu classes include:

Menu varieties

AIR supports the following types of menus:

Application menus 

An application menu is a global menu that applies to the entire application. Application menus are supported on Mac OS X, but not on Windows. On Mac OS X, the operating system automatically creates an application menu. You can use the AIR menu API to add items and submenus to the standard menus. You can add listeners for handling the existing menu commands. Or you can remove existing items.

Window menus 

A window menu is associated with a single window and is displayed below the title bar. Menus can be added to a window by creating a new NativeMenu object and assigning it to the menu property of the NativeWindow object. Window menus are supported on the Windows operating system, but not on Mac OS X. Native menus can only be used with windows that have system chrome.

Context menus 

Context menus open in response to a right-click or command-click on an interactive object in SWF content or a document element in HTML content. You can create a context menu using the AIR NativeMenu class. (You can also use the legacy Flash ContextMenu class.) In HTML content, you can use the Webkit HTML and JavaScript APIs to add context menus to an HTML element.

Dock and system tray icon menus 

These icon menus are similar to context menus and are assigned to an application icon in the Mac OS X dock or Windows notification area. Dock and system tray icon menus use the NativeMenu class. On Mac OS X, the items in the menu are added above the standard operating system items. On Windows, there is no standard menu.

Pop-up menus 

An AIR pop-up menu is like a context menu, but is not necessarily associated with a particular application object or component. Pop-up menus can be displayed anywhere in a window by calling the display() method of any NativeMenu object.

Flex menus 

The Flex framework provides a set of Flex menu components. The Flex menus are drawn by the AIR runtime rather than the operating system and are not native menus. A Flex menu component can be used for Flex windows that do not have system chrome. Another benefit of using the Flex menu component is that you can specify menus declaratively in MXML format. If you are using the Flex Framework, use the Flex menu classes for window menus instead of the native classes. See About the FlexNativeMenu control.

Custom menus 

Native menus are drawn entirely by the operating system and, as such, exist outside the Flash and HTML rendering models. You are, of course, free to create your own non-native menus using MXML, ActionScript, or JavaScript. The AIR menu classes do not provide any facility for controlling the drawing of native menus.

Default menus

The following default menus are provided by the operating system or a built-in AIR class:

• Application menu on Mac OS X
• Dock icon menu on Mac OS X
• Context menu for selected text and images in HTML content
• Context menu for selected text in a TextField object (or an object that extends TextField)

Menu structure

Menus are hierarchical in nature. NativeMenu objects contain child NativeMenuItem objects. NativeMenuItem objects that represent submenus, in turn, can contain NativeMenu objects. The top- or root-level menu object in the structure represents the menu bar for application and window menus. (Context, icon, and pop-up menus don't have a menu bar).

The following diagram illustrates the structure of a typical menu. The root menu represents the menu bar and contains two menu items referencing a File submenu and an Edit submenu. The File submenu in this structure contains two command items and an item that references an Open Recent Menu submenu, which, itself, contains three items. The Edit submenu contains three commands and a separator.

Defining a submenu requires both a NativeMenu and a NativeMenuItem object. The NativeMenuItem object defines the label displayed in the parent menu and allows the user to open the submenu. The NativeMenu object serves as a container for items in the submenu. The NativeMenuItem object references the NativeMenu object through the NativeMenuItem submenu property.

To view a code example that creates this menu see Example: Window and application menu.

Menu events

NativeMenu and NativeMenuItem objects both dispatch displaying and select events:

Displaying: 

Immediately before a menu is displayed, the menu and its menu items will dispatch a displaying event to any registered listeners. The displaying event gives you an opportunity to update the menu contents or item appearance before it is shown to the user. For example, in the listener for the displaying event of an "Open Recent" menu, you could change the menu items to reflect the current list of recently viewed documents.

The target property of the event object is always the menu that is about to be displayed. The currentTarget is the object on which the listener is registered, either the menu itself, or one of its items.

Select:  

When a command item is chosen by the user, the item will dispatch a select event to any registered listeners. Submenu and separator items cannot be selected and so never dispatch a select event.

A select event bubbles up from a menu item to its containing menu, on up to the root menu. You can listen for select events directly on an item and you can listen higher up in the menu structure. When you listen for the select event on a menu, you can identify the selected item using the event target property. As the event bubbles up through the menu hierarchy, the currentTarget property of the event object identifies the current menu object.

Key equivalents for menu commands

You can assign a key equivalent (sometimes called an accelerator) to a menu command. The menu item will dispatch a select event to any registered listeners when the key, or key combination is pressed. The menu containing the item must be part of the menu of the application or the active window for the command to be invoked.

Key equivalents have two parts, a string representing the primary key and an array of modifier keys that must also be pressed. To assign the primary key, set the menu item keyEquivalent property to the single character string for that key. If you use an uppercase letter, the shift key is added to the modifier array automatically.

On Mac OS X, the default modifier is the command key (Keyboard.COMMAND). On Windows, it is the control key (Keyboard.CONTROL). These default keys are automatically added to the modifier array. To assign different modifier keys, assign a new array containing the desired key codes to the keyEquivalentModifiers property. The default array is overwritten. Whether or not you use the default modifiers or assign your own modifier array, the shift key is added if the string you assign to the keyEquivalent property is an uppercase letter. Constants for the key codes to use for the modifier keys are defined in the Keyboard class.

The assigned key equivalent string is automatically displayed beside the menu item name. The format depends on the user's operating system and system preferences.

The following example assigns Ctrl+Shift+G as the key equivalent for a menu item:

var item:NativeMenuItem = new NativeMenuItem("Ungroup");
item.keyEquivalent = "G";

This example assigns Ctrl+Shift+G as the key equivalent by setting the modifier array directly:

var item:NativeMenuItem = new NativeMenuItem("Ungroup");
item.keyEquivalent = "g";
item.keyEquivalentModifiers = [Keyboard.CONTROL, Keyboard.SHIFT];

Mnemonics

Mnemonics are part of the operating system keyboard interface to menus. Both Mac OS X and Windows allow users to open menus and select commands with the keyboard, but there are subtle differences. On Mac OS X, the user types the first letter or two of the menu or command and then types return.

On Windows, only a single letter is significant. By default, the significant letter is the first character in the label, but if you assign a mnemonic to the menu item, then the significant character becomes the designated letter. If two items in a menu have the same significant character (whether or not a mnemonic has been assigned), then the user's keyboard interaction with the menu changes slightly. Instead of pressing a single letter to select the menu or command, the user must press the letter as many times as necessary to highlight the desired item and then press the enter key to complete the selection. To maintain a consistent behavior, it is generally advisable to assign a unique mnemonic to each item in a menu for window menus.

Specify the mnemonic character as an index into the label string. The index of the first character in a label is 0. Thus, to use "r" as the mnemonic for a menu item labeled, "Format," you would set the mnemonicIndex property equal to 2.

var item:NativeMenuItem = new NativeMenuItem("Format");
item.mnemonicIndex = 2;

Menu item state

Menu items have the two state properties, checked and enabled:

checked 

Set to true to display a check mark next to the item label.

var item:NativeMenuItem = new NativeMenuItem("Format");
item.checked = true;

enabled 

Toggle the value between true and false to control whether the command is enabled. Disabled items are visually "grayed-out" and do not dispatch select events.

var item:NativeMenuItem = new NativeMenuItem("Format");
item.enabled = false;

Attaching an object to a menu item

The data property of the NativeMenuItem class allows you to reference an arbitrary object in each item. For example, in an "Open Recent" menu, you could assign the File object for each document to each menu item.

var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf")
var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name));
menuItem.data = file;