Volume 6A: Motif Programming Manual

* menu_item's sensitivity is reset.

*/

XtAddCallback (XtParent(dialog), /* dialog's _parent_ */

XmNpopdownCallback, reset_sensitive, menu_item);

XtAddCallback (dialog, XmNdestroyCallback, reset_sensitive, menu_item);

XtManageChild (dialog);

XtPopup (XtParent (dialog), XtGrabNone);

}

The open_callback() function is called whenever the user activates the Open menu item on the File menu. The

first thing open_callback() does is find the nearest WMShell widget associated with the menu item. We do not

want the MenuShell here, as we need a non−transient widget to act as the parent for the FileSelectionDialog. If the

menu item is used as the parent for the dialog, when the menu is popped down, the dialog is also popped down

because it is a secondary window.

We set the menu item's sensitivity to False, which prevents the user from selecting the item again. In order to be

notified when the FileSelectionDialog is dismissed, we add callback routines for XmNpopdownCallback and

XmNdestroyCallback. In both cases, the Open menu item needs to be reset so that the user can select it again.

The only thing in open_callback() is a callback function that opens the selected file when the user selects the

OK button. This functionality is beyond the scope of this chapter; see Chapter 6, Selection Dialogs, for details.

16.3.7 Tear−Off Menus

Motif 1.2 provides a new feature that allows menus to be torn off and placed in separate windows. From the user's

perspective, tear−off menus make it easy to make repeated menu selections. Normally, when the user posts a menu, it

is only displayed until she makes a selection, and then it is removed. If the menu has been torn off, however, it is

displayed in a separate window, and the user can make as many selections as she wants without having to repost it

each time.

Tear−off behavior is provided for all of the Motif menu types, but the behavior is disabled by default. When tear−off

functionality is enabled in a menu, the first item in the menu is a tear−off button. The button displays a dashed line to

indicate that the user can tear off the menu, much as she would tear a coupon out of a newspaper. If the user selects

the tear−off button, the menu is placed in a separate window with limited window manager decorations. The window

can be moved, so the user can position it in a convenient location. The menu remains torn off until the user cancels the

menu by pressing the ESCAPE key within the window.

Tear−off functionality is controlled by the XmNtearOffModel resource of the RowColumn widget. This resource is

only valid when the RowColumn is being used as a PulldownMenu or a PopupMenu. The resource can have one of

the following values: XmTEAR_OFF_ENABLED or XmTEAR_OFF_DISABLED. By default, the resource is set to

XmTEAR_OFF_DISABLED, so if you want to provide tear−off functionality in the menus in your application, you

must set the resource for all of your menu panes. the figure shows a PulldownMenu both before and after being torn

off.

16 Menus 16.3.7 Tear−Off Menus

450

A PulldownMenu before and after being torn off

Motif does not install a resource converter for the XmNtearOffModel resource, but it does provide one that you can

install if you want to specify the resource in a resource file. The

XmRepTypeInstallTearOffModelConverter() routine installs the resource converter for

XmNtearOffModel. This routine does not take any arguments, but it does win the award for the longest function

name in the Motif toolkit. Once the converter is installed, you can use the following resource specification to enable

tear−off functionality for all menus:

*tearOffModel: TEAR_OFF_ENABLED

The converter is not installed by default for backwards compatibility reasons.

Some applications use menus in such a way that they need to keep track of when the menu is popped up and popped

down. For example, an application might use some ToggleButtons in a PulldownMenu to allow the user to set state

variables for the program. If the application also provides another interface for changing the variables, such as a

command−line, the application needs to know when the menu is popped up so that it can make sure the ToggleButtons

are set appropriately.

Now let's say that this application is recompiled with Motif 1.2. If the resource converter for XmNtearOffModel

were installed, the user could enable tear−off functionality, and that might cause the application to malfunction. If an

application needs to keep track of the comings and goings of menus, it has to do extra work for tear−off menus. Since

the converter is not installed by default, the programmer can decide whether or not to support tear−off functionality in

this case. If the application is modified to support tear−off menus, then it can install the converter and allow the user

to set the resource in a resource file. If your application does not require any special handling of menus, there is no

reason not to enable tear−off functionality for all menus, as it really is a convenience to the user.

The RowColumn widget provides two new callback resources that allow an application to keep track of tear−off

menus. The XmNtearOffMenuActivateCallback routine is called when a menu is torn off;

XmNtearOffMenuDeactivateCallback is called when the torn−off menu is dismissed. These callbacks

provide a way for you to perform any special processing that is necessary for handling tear−off menus.

Motif also provides access to the tear−off button with the XmGetTearOffControl() routine. This routine takes a

menu pane and returns the widget ID of the tear−off button in the menu, if there is one. Otherwise the routine returns

16 Menus 16.3.7 Tear−Off Menus

451