Volume 6A: Motif Programming Manual

in the figure.

Output of action_area.c

In order to distribute the PushButtons evenly across the action area, we use the XmN-fractionBase resource of the

Form widget to segment the widget into equal portions. The value of the resource is based on the value of the

TIGHTNESS definition, which controls the spacing between buttons. A higher value causes the PushButtons to be

closer together, while a lower value spaces them further apart. We use the value 20 for purely aesthetic reasons. As

each button is created, its attachments are set. The left side of the first button and right side of the last button are

attached to the left and right edges of the Form, respectively, while all of the other left and right edges are attached to

positions.

The callback routine and associated client data for each button are added using XtAddCallback(). The first button

in the action area is specified as the default button for the dialog. The XmNdefaultButton resource indicates

which button is designated as the default button for certain actions that take place in the control area of the dialog. The

XmN-activateCallback of the TextField widget in the control area uses the resource to activate the default

button when the user presses the RETURN key in the TextField.

The CreateActionArea() function also sets XmNpaneMaximum and XmNpaneMinimum constraint resources

on the action area. These are PanedWindow constraint resources that are used to specify the height of the action area.

The assumption, of course, is that the parent of the action area is a PanedWindow. If that is not true, these resource

specifications have no effect.

8.5 Using a TopLevelShell for a Dialog

You don't have to use a DialogShell widget to implement a dialog. In fact, it is quite common to use a TopLevelShell

or even an ApplicationShell in cases where the particular functionality is an important part of a larger application. For

example, an e−mail application has a variety of functions that range from reading messages to composing new ones.

As shown in the figure, you can have a separate TopLevelShell, complete with a MenuBar, that looks and acts like a

separate application, but is still considered a dialog, since it is only a subpart of the whole application.

As you can see, this dialog uses the same elements as other dialogs. The control area is complete with a ScrolledText

region and other controls, while the action area contains action buttons. The principal difference between this dialog

and a dialog implemented with a DialogShell is that this dialog that uses a TopLevelShell may be iconified separately

from the other windows in the program.

8 Custom Dialogs 8.5 Using a TopLevelShell for a Dialog

194

A message composition dialog from an e−mail application

When you need to implement a dialog with a TopLevelShell, you should not regard or implement it as a popup dialog.

But for the most part, there is little difference from this approach and the method discussed for regular dialogs. You

may still use BulletinBoards, Forms, and RowColumns to manage the inner controls. You still need an action area

(provided you want to look and act like a dialog), and you still need to handle the cases where the dialog is popped up

and down. You can create the TopLevelShell with XtVaAppCreateShell(). The shell is automatically mapped

onto the screen when you call XtPopup(). You may also want to call XMapRaised() on the shell, in case it is

already popped up but is not at the top of the window hierarchy.

In direct contrast to the DialogShell widget, managing the immediate child of a TopLevelShell does not cause the

dialog to pop up automatically. Even if that child is subclassed from the BulletinBoard widget, this type of behavior

only happens if the shell is a DialogShell widget. Because you are using a TopLevelShell, you cannot rely on the

special communication that happens between a DialogShell and a BulletinBoard or Form widget. As a result, many

resources such as XmNautoUnmanage and XmNdialogTitle no longer apply. To achieve the effects of these

resources, you have to implement the functionality yourself.

If you want to use one of the standard Motif dialogs, such as a MessageDialog or a FileSelectionDialog, in a shell

widget that can be iconified iconified separately from its primary window shell, you can put the dialog in a

TopLevelShell. Create the shell using XtVaAppCreateShell() and then use one of the Motif convenience

routines to create a MessageBox or a FileSelectionBox, rather than the corresponding dialog widget. The following

code fragment shows an example of this usage:

shell = XtVaAppCreateShell (NULL, "Class",

topLevelShellWidgetClass, dpy,

XtNtitle, "Dialog Shell Title",

NULL);

8 Custom Dialogs 8.5 Using a TopLevelShell for a Dialog

195