9.6 Alternative menu items

Menus can include "alternative" items, which are invoked if some modifiers are held while selecting the "main" item. The modifiers are defined by the :accelerator initarg of the item, which also allows the item to be invoked by a keyboard accelerator key if specified. On Cocoa, the title and accelerator of the alternative item appear when the appropriate modifier(s) are pressed.

A menu item becomes an alternative to an immediately previous item when it is made with initarg :alternative t . Each alternative item must have the same parent as its previous item. That is, they are within the same menu and menu component, as described in Grouping menu items together. More than one alternative item can be supplied for a given main item by putting them consecutively in the menu. The main item is the item preceding the first alternative item.

The main item and its alternative items forms a group of items. The accelerators of all items in the group must consist of the same key, but with different modifiers. If there is no need for an accelerator key, the main item should not have no accelerator and the alternative items should have accelerators with Null as the key, for example "Shift-Null" .

When the menu is displayed, only one item from the group will be shown. On Windows, GTK+ and Motif the main item is always displayed. Cocoa displays the item with the least number of modifiers initially, so to get a consistent cross-platform behavior, the main item should have the least number of modifiers. On Cocoa, pressing modifier keys that match alternative items changes the title and accelerators displayed for the item.

When the user selects an item with the modifiers pressed, the appropriate alternative item is selected.

To make a menu-item an alternative item, pass the initarg :alternative t and a suitable value for the initarg :accelerator .

There is an example illustrating alternative menu items in

Note: Accelerators of alternative items do not work on Motif.

CAPI User Guide (Macintosh version) - 30 Aug 2011