Using IlvMenuItem

Menu bars, toolbars, and pop-up menus are composed of several entries, called menu items. Menus items are implemented by the IlvMenuItem class, a subclass of IlvGadgetItem. They can display a label, a bitmap, or any IlvGraphic object. See Gadget Items.

Creating Menu Items

The following code sample creates three menu items: one with a label, one with a bitmap, and one with an IlvGraphic object.

item1 = new IlvMenutItem("item1");        // Creates an item with a label.

item2 = new IlvMenuItem(bitmap);          // Creates an item with a bitmap.

item3 = new IlvMenuItem(graphic);         // Creates an item with a graphic.

A menu item can also be used as a separator. A separator is a line that divides a group of commands represented by menu items in a menu.

item4 = new IlvMenuItem(); // Creates a separator.

You can check whether an item is a separator or not using the getType member function, as follows:

if (item->getType() == IlvSeparatorItem) {

...

}

Attaching a Submenu to a Menu Item

Any menu item that is not a separator can display a submenu. To attach a submenu to a menu item, use the member function setMenu. When the menu item belongs to a pop-up menu, a small arrow next to it indicates that it provides access to a submenu.

New Menu Item with a Submenu

Associating a Callback with a Menu Item

When the user selects a menu item, its associated callback is invoked to perform an action. Each menu item can have a specific callback.

To attach a callback to a menu item, use one of the following member functions:

• item->setCallback(myCallback);

where myCallback is a function that might be described like this:

static void

myCallback(IlvGraphic* g, IlvAny data)

{

....

}

The g parameter is the holder of the item that triggers the callback, that is, an instance of a subclass of IlvAbstractMenu. The data parameter is the client data of the menu item which you can install with the member function setClientData.

Of course, it is useless to set a callback to a menu item separator or to a menu item that has a submenu, as these callbacks will never be called.

• item->setCallbackName("myCallback");

In this case, the callback name "myCallback" must be registered with the container that holds the menu.

If a menu item does not have a callback, the Main callback associated with the menu, if any, is invoked. This allows you to perform the same action for each item of the menu. See Associating a Callback with a Gadget.

Associating Mnemonics with Menu Items

You can associate a mnemonic letter with a menu item. Pressing the modifier key (Alt on PCs, and Meta on UNIX) and the mnemonic letter associated with a menu or toolbar item displays the attached pop-up menu. When a menu is open, pressing the mnemonic letter selects the corresponding command in that menu, that is, triggers the Menu Item callback.

See Associating a Mnemonic with a Gadget Label.

Associating Accelerators with Menu Items

A pop-up menu item can be associated with an accelerator. An accelerator is a combination of a letter key with a modifier key. When the user presses the key combination, the Menu Item callback is directly accessed without the corresponding menu being opened.

An accelerator is composed of two parts: a key combination and the accelerator itself. The key combination appears beside its associated menu item.

For example, if you want to assign the key combination Ctrl+A to a menu item, use the following code:

item->setAcceleratorText("Ctrl+A");

item->setAcceleratorModifiers(0);

item->setAcceleratorKey(IlvCtrlChar('A'));

By default, the key combination associated with a menu item is captured only when the containing menu is not active (that is, the menu is not displayed). This applies to menus belonging to a Menu Bar, sub-menus, and standalone menus. To change the default behavior, set the environment variable ILVGREEDYACCELERATORS to “ON” or “on” to capture the accelerator combination even when the menu containing the associated item is active.