Volume 6A: Motif Programming Manual

A simple MenuBar

If you are specifying an item in the MenuBar, the first parameter is a symbolic constant that identifies the type of the

item. Since CascadeButtons are the only elements that can display PulldownMenus, the first parameter should always

be set to XmVaCASCADEBUTTON. The label of the CascadeButton is given by the second parameter, which must be a

compound string. In the above example, the variable file contains a compound string that contains the text File.

The third parameter specifies an optional mnemonic character for the CascadeButton that can be used to post the

menu from the keyboard. The mnemonic for the File menu is F. By convention, the first letter of a menu or menu item

label is used as the mnemonic.

We use the compound string creation function, XmStringCreateLocalized(), to create the compound strings

for the menu labels. This function creates a compound string with the text encoded in the current locale.

XmStringCreateLocalized() is a new routine in Motif 1.2; it replaces XmStringCreateSimple(),

which creates a compound string using the default character set associated with the widget in which the string is

rendered. For a complete discussion of compound strings, see Chapter 19, Compound Strings.

Since you are not creating each CascadeButton using the normal creation routines, you are not returned a handle to

each button. You might think that the label string that you assign to each button is used as the widget's name, but this

is not the case. The buttons are created sequentially, so the MenuBar assigns the name button_n to each button. The

value n is the position of the button in the MenuBar, where positions are numbered starting with 0 (zero). We will

discuss how you can specify resources for items on the MenuBar later in the chapter.

Do not attempt to install callback routines on the CascadeButtons themselves. If you need to know when a particular

menu is popped up, you should use the XmNpopupCallback on the MenuShell that contains the PulldownMenu

associated with the CascadeButton. The popup and popdown callback lists are described briefly in Chapter 7, Custom

Dialogs; for more information, see Volume Four, X Toolkit Intrinsics Programming Manual.

5.2.1 Creating a PulldownMenu

Every CascadeButton in a MenuBar must have a PulldownMenu associated with it. You can create the items in a

PulldownMenu using a method that is similar to the one for creating a MenuBar. A PulldownMenu can be created

using the function XmVaCreateSimplePulldownMenu(). This routine is slightly more involved than

XmVaCreateSimpleMenuBar(). The routine takes the following form:

Widget

XmVaCreateSimplePulldownMenu (parent, name, post_from_button,

callback, ...)

Widget parent;

String name;

int post_from_button;

XtCallbackProc callback;

...

The post_from_button parameter specifies the CascadeButton that posts the PulldownMenu. This parameter is

an index (starting at zero) into the array of CascadeButtons in the parent widget, which should be a MenuBar. The

name parameter specifies the widget name for the RowColumn widget that is the PulldownMenu. This name is not

the title of the CascadeButton associated with the menu. The MenuShell that contains the PulldownMenu uses the

same name with _popup appended to it. The callback parameter specifies a function that is invoked whenever the

user activates any of the items in the menu. The rest of the arguments to XmVaCreateSimplePulldownMenu()

are either RowColumn resource/value pairs or special arguments that specify the items in the PulldownMenu.

5 The Main Window 5.2.1 Creating a PulldownMenu

88

You should not manage a PulldownMenu after you create it because you do not want it to appear until it is posted by

the user. The CascadeButton that posts the menu handles -managing the menu when it needs to be displayed. The

following code fragment shows the use of XmVaCreateSimplePulldownMenu() to create a PulldownMenu:

XmString open, save, quit, quit_acc;

Widget menubar, menu;

...

/* First menu is the File menu −− callback is file_cb() */

open = XmStringCreateLocalized ("Open...");

save = XmStringCreateLocalized ("Save...");

quit = XmStringCreateLocalized ("Quit");

quit_acc = XmStringCreateLocalized ("Ctrl−C");

menu = XmVaCreateSimplePulldownMenu (menubar, "file_menu", 0, file_cb,

XmVaPUSHBUTTON, open, 'O', NULL, NULL,

XmVaPUSHBUTTON, save, 'S', NULL, NULL,

XmVaSEPARATOR,

XmVaPUSHBUTTON, quit, 'Q', "Ctrl<Key>c", quit_acc,

NULL);

XmStringFree (open);

XmStringFree (save);

XmStringFree (quit);

XmStringFree (quit_acc);

...

Unlike a MenuBar, which can only contain CascadeButtons, a PulldownMenu can contain a number of different types

of elements. As with XmVaCreateSimpleMenuBar(), these elements are specified by a symbolic constant that

identifies the type of the item. The symbolic constant is followed by a variable number of additional parameters that

depend on the type of the menu item. You can use the following values to specify the items in a PulldownMenu:

XmVaPUSHBUTTON

The item is a PushButton. It takes four additional parameters: a compound string label, a mnemonic, an

accelerator, and a compound string that contains a text representation of the accelerator. When the PushButton

is selected, the callback routine is called. It is passed an integer value as client_data that indicates the

item on the PulldownMenu that was activated. The value is an index into the menu that ranges from 0 to n−1;

if client_data is two, then the third item in the menu was selected.

XmVaTOGGLEBUTTON

The item is a ToggleButton. It takes the same four additional parameters as described for

XmVaPUSHBUTTON. When the ToggleButton is selected, the value of the button is toggled and the

callback routine is called. The client_data that is passed to the callback routine is handled the same

as for PushButtons.

XmVaCHECKBUTTON

This value is identical to XmVaTOGGLEBUTTON.

XmVaRADIOBUTTON

The item is a ToggleButton with RadioBox characteristics, which means that only one item in the menu can

be set at a time. The PulldownMenu does not enforce this behavior, so you must either handle it yourself or

specify other RowColumn resources to make the menu function like a RadioBox. We demonstrate creating a

menu with RadioBox behavior later in the chapter. This value takes the same additional parameters and deals

with the callback routine in the same way as ToggleButtons.

XmVaCASCADEBUTTON

5 The Main Window 5.2.1 Creating a PulldownMenu

89