You have already seen how an app-defaults file can set the string for a PushButton widget. However, xrowcolumn has an instance hierarchy that contains a RowColumn widget with two PushButton widgets as children. It is worth seeing how to set the PushButton widget labels in this new situation. (We will be returning often to the subject of setting resources, because it is so important to Toolkit programming. Each time, new ideas will be presented.)

Example 3-2 shows an app-defaults file for xrowcolumn.

*pressme.labelString:      Press Me
*quit.labelString:         Quit
*XmPushButton.fontList:    variable
*XmRowColumn.background:   green4

When an application contains multiple widgets of the same class, resource specifications can either identify individual widget instances by name or can use wildcards or widget class names to reference more than one widget. The first two specifications in the example identify the pressme and quit widgets by instance name. The third specification uses the class name PushButton to set the font of both PushButton widgets in the application. This line shows that resources of groups of widgets can be set with a single line. The fourth specification uses the class name RowColumn to set the background of the RowColumn widget (but not the PushButton widgets) to the color green. Whenever you use a class name, it will match all widgets of that class in the application, even ones we add later in a later revision of the application.

By changing the period in the fourth specification to an asterisk, the specification will change the background color of not only all RowColumn widgets in the application, but also all their children, and their children, recursively. Remember from Chapter 2 that an asterisk matches zero or any number of intervening widget instance names or class names. In xrowcolumn, this setting will make the background of the RowColumn and PushButton widgets green. Try not to get careless with asterisks, though. They lead you to think you don't have to remember the instance hierarchy in your application, but this can backfire, because it is easy to set resources on more widgets than you realize.

Note that you need to know the instance name for each widget in the application in order to set its resources individually. This is true for all resource files, including the ones customized by the user. Therefore, in the documentation for your application, be sure to include the name and class of each widget in your instance hierarchy. To be thorough, also include a description of the resources of each class, and specify which resources the user can customize.

The first argument of each XtVaCreateManagedWidget() call is the widget instance name. This is the name used to set resources for this widget in the resource databases. Most programmers make the widget instance name the same as the variable name of type Widget that holds the widget ID. This lexical connection is not mandatory, but it is highly recommended because it reduces confusion by helping you to remember the connection between entries in the app-defaults file and the widget instances in the application.

The purpose of geometry managing widgets is two-fold:

Build and run xrowcolumn, and then try resizing it to see how the RowColumn widget deals with various geometries. This is the default behavior of RowColumn--it can be customized with resources to use many different layout rules. Try adding the following resource settings to its app-defaults file, run it again, and try out its resizing characteristics.

*rowColumn.packing: XmPACK_TIGHT
*rowColumn.orientation: XmHORIZONTAL

Two of the resulting geometries are shown in Figure 3-2.

Figure 3-2. Two configurations of xrowcolumn

What happens if you use resource settings in the app-defaults file to directly set the size or position of a widget that is being managed by a geometry managing widget? Depending on the specific geometry managing widget, you may not get the desired effect. For example, trying to set the size of the PushButton widgets managed by RowColumn may not work. For example, if you added the resource setting *pressme.height: 400, it would have no effect on the height of the pressme widget unless allowShellResize is also set to True (if you are using mwm). This is because the RowColumn widget needs to ask its parent, the shell widget, to be resized, and this will be denied unless mwm allows the shell to resize itself. However, it is possible to set things like geometries in the application code, as will be demonstrated later in this chapter.

Every widget's size and position is ultimately under the control of the window manager.^[23] A RowColumn widget attempts to make itself just big enough to hold its children, using the resources provided by the application as a guide, but the window manager can override anything the widget or the application does.

What happens when the user resizes an application is only part of the picture. The application itself may need to resize one of its widgets in order to display more widgets. Or the application may tell a widget to display more data and the widget will have to ask its parent to be resized. For example, what happens when the application changes the string in one of the PushButton widgets while the application is displayed? The PushButton widget attempts to resize itself to display the current string, by asking its parent for permission.

Whether this request is granted depends on the position of the widget in the instance hierarchy, the resizing policy imposed by each composite widget in the hierarchy, and the window manager. This is because each widget, from the PushButton widget on up, negotiates with its parent when the PushButton widget requests a new size. The PushButton widget tries to change size to accommodate the new string (larger or smaller), and the RowColumn widget must approve this change. Since the RowColumn widget is already the same size as the Shell widget, RowColumn can't get any larger without asking Shell. The Shell widget is responsible for negotiating with the window manager.

The mwm window managers will allow applications to resize themselves only if the user has set the allowShellResize resource to True. (Some other window managers, such as twm, never allow it.) Otherwise, the RowColumn widget will reject the resize request unless the original change made the PushButton widget smaller. If the new size is rejected, the PushButton widget will still display the new string, but it may not show all of the string (if the new string is longer than the old one) or there may be extra space left over (if the old string was longer).

Fortunately, all this negotiation is done by the widgets themselves. The application doesn't need to do anything. However, you should be aware that any widget resource change that results in a widget size change may not work unless there is enough room in the application for the change to be granted without resizing the top-level window.

The RowColumn widget is Motif's most comprehensive and powerful geometry managing widget. It is widely used for managing groups of small widgets in many settings. (Some of these uses of RowColumn are under other names, such as CheckBox, PullDownMenu, and MenuBar.) However, it treats all its children the same, and therefore isn't appropriate for widgets of radically different geometries. RowColumn's decisions about where to place the widgets can be inappropriate. Figure 3-3 shows the results upon resizing of a RowColumn widget that is attempting to manage two ScrollBar widgets and a BitmapEdit widget. ^[24]

Figure 3-3. Incorrect results upon resize of ScrollBar widgets inside a RowColumn widget

Those two large triangles are actually ArrowButtons on the ends of a very wide but short ScrollBar! It might be possible to use the RowColumn resources to make this application look better, but it would be difficult to keep it good looking after resizing.

Because no single geometry managing widget can satisfy all needs, there are several different types of composite widgets in most widget sets, each with different rules about how it places children. Many widget sets, including Motif, have a widget specifically designed to place scrollbars next to a main window. In Motif, this widget is called ScrolledWindow.

Of course, applications are not limited to using only one composite widget. It is quite common for the application's main window to be a large composite widget which contains several smaller composite widgets, each of which in turn contains certain groups of related widgets. You'll need to design the layout of widgets in your application, decide where in the instance hierarchy to place composite widgets, and experiment to find out which composite widgets provide the best appearance when the application is resized. The following application shows how several kinds of geometry managing widgets can be used together in an application.

Figure 3-4 shows the xmh application and the instance hierarchy used to create it. This application is built using the Athena widgets. However, analogues of all these widgets are available in Motif, and the application could easily be ported. The top composite widget in xmh is of the Athena Paned class (equivalent to PanedWindow). The Paned widget creates several horizontal panels, or panes, one for each child, with a sash positioned on the line between each pane. Each pane contains a different functional area of the application.

Figure 3-4. The xmh application and its instance hierarchy

So, you see, there are three different kinds of geometry managing widgets in this application: Paned, Box, and Viewport. In a Motif port of this application, they would be PanedWindow, RowColumn, and ScrolledWindow.

Box and Viewport are relatively simple geometry managing widgets that are subclasses of the Composite class. The Paned widget is a more complex kind of geometry managing widget which is a subclass of the Constraint class. Both Composite and Constraint are basic classes defined by the Xt Intrinsics.

All the previous examples have used XtVaCreateManagedWidget() to create widgets. As you may recall, you specify which type of widget you want by supplying an argument such as xmPushButtonWidgetClass. But Motif also provides its own functions for creating widgets. To create a PushButton, Motif's function is XmCreatePushButton(). Note, however, that Motif's function does not manage the widget, so you need to call XtManageChild() separately. (If you forget, the widget won't be visible.) Also, as you will see later, it is harder to set widget resources with the Motif widget creation functions. In the cases where the two techniques are identical, our examples stick with the basic Xt routine.^[27]

In some cases, however, the Motif widget creation routines have code beyond just calling the Xt widget creation routine. Some set resources in particular ways. For example, XmCreateMenuBar() actually creates a RowColumn widget, but with some special resource settings. It is a lot more convenient to use XmCreateMenuBar() than to use the Xt widget creation routine and set the resources yourself.

As in the case of XmCreateMenuBar(), the Motif widget creation routines often have names that are different from the widgets they create. There is no such thing as a MenuBar widget. Remember this when you look up a widget's resources in the Motif reference manual. If you are unsure of the widget class, look on the page for the Motif widget creation function first.

Other Motif widget-creation functions actually create a combination of widgets. More will be said about this later.

With that introduction, we are ready to show you the code needed to implement a standard Motif MainWindow and its usual children. Example 3-4 shows a portion of xmainwindow.c, the code for implementing the application shown in Figure 3-6.

/*
 *  xmainwindow.c - main window with help and quit
 */
/* Standard Motif include files: */
#include <Xm/Xm.h>  
#include <Xm/RepType.h>  
/*
 * Public header files for widgets used in this file.
 */
#include <Xm/MainW.h>       /* MainWindow */
#include <Xm/RowColumn.h>   /* for MenuBar (actually a RowColumn) */
#include <Xm/Frame.h>       /* Frame (simulated custom widget) */
#include <Xm/PushB.h>       /* PushButton (for menu buttons) */
#include <Xm/CascadeB.h>    /* CascadeButton (for menubar labels) */
#include <Xm/MessageB.h>    /* MessageBox dialog (for help) */
 /* callback functions defined here */
main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, mainWindow, menuBar, frame;
    Widget fileButton, fileMenu, quit, help, helpButton,
            helpMenu, helpBox;
    XtSetLanguageProc(NULL, (XtLanguageProc)NULL, NULL);
    topLevel = XtVaAppInitialize(
            &app_context,     /* Application context */
            "XMainWindow",    /* application class name */
            NULL, 0,          /* command line option list */
            &argc, argv,      /* command line args */
            NULL,             /* for missing app-defaults file */
            NULL);            /* terminate varargs list */
    /* create main window */
    mainWindow = XtVaCreateManagedWidget(
            "mainWindow",     /* widget name */
            xmMainWindowWidgetClass, /* widget class */
            topLevel,         /* parent widget */
            NULL);            /* terminate varargs list */
    /* register converter for setting tearoff menus from resource files */
    XmRepTypeInstallTearOffModelConverter();
    /* create menubar along top inside of main window */
    menuBar = XmCreateMenuBar(
            mainWindow, /* parent widget */
            "menuBar",  /* widget name */
            NULL,       /* no arguments needed */
            0);         /* no arguments needed */
    XtManageChild(menuBar);
    frame = XtVaCreateManagedWidget(
            "frame",            /* widget name */
            xmFrameWidgetClass, /* widget class */
            mainWindow,         /* parent widget */
            NULL);              /* terminate varargs list */
    /* Set MainWindow areas */
    XmMainWindowSetAreas (mainWindow, menuBar, NULL, NULL, NULL,
            frame);
      .
      .
      .
}

This code creates a MainWindow that contains two widgets: a menubar (which is actually a kind of RowColumn configured as a menubar via resources automatically set by the convenience function used to create the widget) and a Frame. Note that the parent arguments of functions that create the menubar and the Frame are both mainWindow.

We use XtVaCreateManagedWidget() to create the main window, but XmCreateMenuBar() to create the menubar, for the reasons described above. Notice that widget name and widget parent arguments are in a different order in the two functions.

The menubar must be managed with a separate call to XtManageChild(), because XmCreateMenuBar() does not manage it.

XmMainWindowSetAreas() tells the main window which of its children should be treated as the menubar (placed across the top of the application), and which as the work area (at the bottom, with scrollbars if needed). The work area in this case is the Frame widget. The three unused arguments, here set to NULL, allow you to tell MainWindow which widget is the Command window, and which widgets are the scrollbars that will control the work area.

You might ask, why does MainWindow need to be told which widget is which, since it has access to its list of child widgets? This is done mainly for added flexibility, so that you can switch work areas or other children.

The purpose of the scrollbar arguments in XmMainWindowSetAreas() is a common point of confusion. MainWindow is a subclass of ScrolledWindow. That means that MainWindow has all the features of ScrolledWindow, plus more. Therefore, MainWindow automatically creates its own scrollbars and uses these scrollbars to control the work area. Why, then, should XmMainWindowSetAreas() allow you to tell MainWindow which scrollbars to use, when MainWindow already has its own scrollbars and knows how to use them? The answer is that in some cases an application wants to provide its own code to handle the callbacks that connect its scrollbars with its work region. In practically all cases, however, an application can use the scrollbars created automatically by MainWindow or ScrolledWindow, even if it wishes to manually connect those widgets with the work area.

A resource setting is necessary in order to make MainWindow display scrollbars and use them to control the custom window. Here is the portion of the XMainWindow app-defaults file that applies to the code shown so far:

! Set initial size of application
*XmMainWindow.width:  200
! Frame will be bigger that application, thus requiring scrollbars
*XmFrame.width:  300
*XmFrame.height:  300
! Make MainWindow display scrollbars and use them to
! pan around in the frame.
*XmMainWindow.scrollingPolicy:  XmAUTOMATIC

The remaining part of the boilerplate code in a standard Motif application is to build the File menu and Help button in the menubar, that you see in xmainwindow. This is described in the next section.

Motif provides three different types of menu: Popup, Pulldown, and Option. Popup menus have no on-screen presence until you press a certain button or key-button combination while in a certain widget. Pulldown menus and Option menus have buttons on the screen--when you press the button the menu appears below (for Pulldown) or over (for Option) the button. Option menus remember the most recent previous selection. RadioBox and CheckBox can also be thought of as kinds of menus. The menus that are invoked from the menubar are Pulldown menus.

It's also worth mentioning that Motif 1.2 supports tear-off menus. This allows the user to move any menu which has its XmNtearOffModel resource set to TEAR_OFF_ENABLED from the location where it first appears anywhere on the screen, and semi-permanently post it there. This makes it quicker to use commonly-used menus (especially since the menus mnemonics--keyboard shortcuts--are only active while a menu is displayed.

The application can call XmRepTypeInstallTearOffModelConverter() to support setting of the XmNtearOffModel resource from resource files. This allows menus to be torn off and posted permanently.

Figure 3-7 shows xmainwindow with the File pulldown menu displayed. The techniques for creating all three types of menus are very similar, but we'll reserve discussion of the other types until "Chapter 13, Menus, Gadgets, and Cascaded Popups."

Figure 3-7. xmainwindow with the File pulldown menu displayed

Creating a pulldown menu is a four-step process:

In Motif, the RowColumn widget created by XmCreatePulldownMenu() is called a menu pane, and the buttons contained by that menu are called menu items.

This process sets up the popup widget, but does not put it on the screen. Somewhere in your code you need to call XtManageChild() to pop up the widget. This is typically done in the XmNactivateCallback callback routine of the CascadeButton. Motif takes care of popping down the menu at the appropriate times according to its conventions.

Example 3-5 shows the code needed to add a File menu containing only a quit button to an existing menubar.

/*
 * quit button callback function
 */
/*ARGSUSED*/
void Quit(w, client_data, call_data)
Widget w;
XtPointer client_data, call_data;
{
    exit(0);
}
main(argc, argv)
int argc;
char **argv;
{
    Widget fileMenu, fileButton, quit;
     .
     .
     .
    /*
     *  CREATE FILE MENU AND CHILDREN
     */
    /* create the File button in the menubar */
    fileButton = XtVaCreateManagedWidget(
            "fileButton",                /* widget name */
            xmCascadeButtonWidgetClass,  /* widget class */
            menuBar,                     /* parent widget */
            NULL);                       /* terminate varargs list */
    /* create menu (really a Shell widget
     * and RowColumn widget combo) */
    fileMenu = XmCreatePulldownMenu(
            menuBar,                     /* parent widget */
            "fileMenu",                  /* widget name */
            NULL,                        /* no argument list needed */
            0);                          /* no argument list needed */
    /* Notice that fileMenu is intentionally NOT managed here */
    /* create button in menu that exits application */
    quit = XtVaCreateManagedWidget(
            "quit",                     /* widget name */
            xmPushButtonWidgetClass,    /* widget class */
            fileMenu,                   /* parent widget */
            NULL);                      /* terminate varargs list */
    /*
     * Specify which menu the fileButton will pop up.
     */
    XtVaSetValues(fileButton,
            XmNsubMenuId, fileMenu,
            NULL);
    /* arrange for quit button to call function that exits. */
    XtAddCallback(quit, XmNactivateCallback, Quit, 0);
      .
      .
      .
}

This code sample exactly matches the four steps listed above for creating a menu. First it creates the button that pops up the menu, followed by the menu pane itself, followed by a button that will appear in the menu. Finally, it tells fileButton that it should pop up fileMenu whenever activated.

There are several important things to remember about this example. Note that fileMenu is not managed after it is created, unlike the widgets in all previous examples. Motif itself will manage the widget when it comes time to pop it up. Also note how, by setting the XmNsubMenuId resource, we connect the fileButton widget with fileMenu. Finally, note that both fileButton and fileMenu are children of the menubar, while quit is a child of fileMenu. This instance hierarchy is important.

Motif has even more different types of dialog boxes than it has menus. Luckily, they are also more uniform in the way they are created! This section will demonstrate creating a dialog box to provide help. "Chapter 13, Menus, Gadgets, and Cascaded Popups," describes the variations in how to use other types of Motif dialog boxes. Figure 3-8 shows xmainwindow with the Help dialog box displayed.

Figure 3-8. xmainwindow with the Help dialog box displayed

This dialog box is a MessageBox widget. Motif doesn't provide a dialog widget that is ideal for providing help, since MessageBox provides Help buttons and Cancel buttons that are normally not needed in Help dialog boxes.

A Help button is created just like the fileButton in the previous example. It is a CascadeButton created as a child of the menubar. The dialog box that will contain the text is created with XmCreateMessageDialog().

Example 3-6 shows the code required to add a Help button and dialog box to xmainwindow. Note that the OSF/Motif Style Guide specifies that the menubar can contain only menus. Therefore, we cannot just put a help button on the menubar. Instead, we need to create a help menu, and then put the help button on the menu. In a real application, the help menu might list various topics for which help is available.

  .
  .
/*
 * callback to pop up help dialog widget (or any other dialog)
 */
/*ARGSUSED*/
void ShowHelp(w, client_data, call_data)
Widget w;
XtPointer client_data;
XtPointer call_data;
{
    Widget dialog = (Widget) client_data;
    XtManageChild(dialog);
}
  .
  .
  .
main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, mainWindow, menuBar, frame;
    Widget fileButton, fileMenu, quit, helpButton, helpMenu,
            help, helpBox;
    Widget temp;
      .
      .
      .
    /*
     *  CREATE HELP BUTTON AND BOX
     */
    /* create button that will bring up help popup */
    helpButton = XtVaCreateManagedWidget(
            "helpButton",                /* widget name */
            xmCascadeButtonWidgetClass,  /* widget class */
            menuBar,                     /* parent widget */
            NULL);                       /* terminate varargs list */
    /* tell menuBar which is the Help button
     * (will be specially positioned. */
    XtVaSetValues(menuBar,
            XmNmenuHelpWidget, helpButton,
            NULL);
    /* create menu (really a Shell widget with a RowColumn child) */
    helpMenu = XmCreatePulldownMenu(
            menuBar,    /* parent widget */
            "helpMenu", /* widget name */
            NULL,       /* terminate argument list (none needed) */
            0);         /* terminate argument list (none needed) */
    /* create help button in the menu */
    help = XtVaCreateManagedWidget(
            "helpMenu"  /* widget name */
            XmPushButtonWidgetClass,  /* widget name */<
            helpMenu,    /* parent widget */
            NULL);      /* terminate argument list (none needed) */
    /* Specify which menu helpButton will pop up */
    XtVaSetValues(helpButton,
            XmNsubMenuId, helpMenu,
            NULL);
    /* create popup that will contain help */
    helpBox = XmCreateMessageDialog(
            help,    /* parent widget */
            "helpBox",  /* widget name */
            NULL,       /* no arguments needed */
            0);         /* no arguments needed */
    temp = XmMessageBoxGetChild (helpBox, XmDIALOG_CANCEL_BUTTON);
    XtUnmanageChild (temp);
    temp = XmMessageBoxGetChild (helpBox, XmDIALOG_HELP_BUTTON);
    XtUnmanageChild (temp);
    /* arrange for help button to pop up helpBox */
    XtAddCallback(help,          /* widget that takes user input */
            XmNactivateCallback, /* callback resource */
            ShowHelp,            /* callback function */
                                 /* data passed as client_data
                                  * to callback function */
      .
      .
      .
}

As shown in Example 3-6, the first step in creating a Help feature is to create a CascadeButton widget as a child of the menubar. Then, you set the XmNmenuHelpWidget resource of the menubar to tell the menubar that this particular CascadeButton is the Help button. This is necessary because the menubar treats the Help button specially; it is a Motif convention that the Help button appears at the extreme right of the menubar. Third, you create the dialog box with XmCreateMessageDialog(). Finally, you register a callback function, here called ShowHelp, with the CascadeButton widget. ShowHelp simply calls XtManageChild() to put the dialog widget on the screen. (If you have several dialog widgets, they can all share this callback function because it doesn't have any code that depends on any particular type of dialog widget.)

If you get a run-time error that says “Error: Attempt to manage a child when parent is not Composite,” it may mean that you have used XmCreateMessageBox() instead of XmCreateMessageDialog(). XmCreateMessageBox() creates a widget with the same appearance, but it does not create the Shell widget parent that allows the message box to be used as a popup. This can also happen with file selection boxes, radio boxes, selection boxes, and check boxes.

The parent of the dialog box can be any widget in the application, since it is only used to determine on which screen to create the dialog. However, it is useful to use some consistent system of parenting, to make it easier to keep track of the purpose of each dialog. In this case, the parent is the CascadeButton widget that pops up the dialog, getHelp.

XmCreateMessageDialog() actually creates two widgets for you, an OverrideShell and a MessageBox as its child. The OverrideShell handles communication with the window manager, and the MessageBox displays the help text and creates the OK button that pops down the dialog. By default, a MessageBox (and most Motif dialogs) contains three buttons, that read by default OK, Cancel, and Help. Since we are providing help, we have no need for the Cancel and Help buttons. Unfortunately, Motif does not provide a dialog widget with just the OK button. But it is easy enough to take the Cancel and Help widgets off the dialog by unmanaging them. We get their IDs with the Motif function XmMessageBoxGetChild(), and then unmanage them with XtUnmanageChild(). The MessageBox widget then automatically centers the OK button.

Note that the help text is not specified anywhere in the application code. At least until the application is final, it can be specified in the app-defaults file. Example 3-7 shows this portion of the app-defaults file for xmainwindow.

*helpBox.messageString:  This is help text. \n\
But it is only a few words. \n\
If you really need help, \n\
I'm afraid you'll have to read the manual.
! The following used if the window manager titles the dialog.
*helpBox.dialogTitle:  Help

By ending lines with \n\, you can use a multi-line string as a resource value.

You may notice that dialog boxes can extend outside the application. This is because their Shell widgets are child windows of the root window, not the top-level window of the application, no matter which widget you supply as parent. By default in Xt, a child of the root is positioned at the top-left corner of the screen. However, Motif automatically positions most menus and dialog boxes in a suitable location in or over the application before popping them up. Dialog boxes or menus that are not triggered by a mouse button press, though, need to be positioned by the application. How to do this will be described in "Chapter 13, Menus, Gadgets, and Cascaded Popups."

Figure 3-9 shows the widget instance hierarchy of xmainwindow, and its X window hierarchy. Note that the only difference between the two is the parentage of the dialog and menu widgets.

Figure 3-9. The widget instance and X window hierarchies are different only for popups

Note that when you create a PulldownMenu, you are actually creating a Shell widget with the menu as its child. The same is true of MessageDialog. Each separate window hierarchy has a shell widget at the top.

If you have a popup widget that might never be used, or whose characteristics are not known until just before it is popped up, you can create the popup shell and widget just before popping it up, in the callback function or action that pops up the widget. This technique makes the startup time of the application marginally faster, but slows the pop up time the first time the popup is used.

Popups, and menus in particular, will be described in much more detail in "Chapter 13, Menus, Gadgets, and Cascaded Popups."

A callback function is called with three arguments: widget, client_data, and call_data.

The widget argument is necessary if you have registered the same callback function for two widgets, and you need to know which widget called the function. It also may be used in routine ways, such as for the argument of macros. The application determines the use of client_data, whereas the widget determines the use of call_data.

/*ARGSUSED*/
void PressMe(w, client_data, call_data)
Widget w;
XtPointer client_data, call_data;
{
    fprintf(stderr, "%s, client_data);
}
main(argc, argv)
int argc;
char **argv;
{
    Widget pressme;
      .
      .
    /* XtAppInitialize, create pressme widget */
      .
      .
    /* last argument is client_data */
    XtAddCallback(pressme, XmNactivateCallback, PressMe, "Thanks");
      .
      .
}

typedef struct {
    String name;
    String street;
    String city;
} app_stuff;
/*ARGSUSED*/
void PressMe(w, client_data, call_data)
Widget w;
XtPointer client_data;   /* to be cast to app_stuff */
XtPointer call_data;
{
    /* cast required in ANSI C */
    app_stuff *address = (app_stuff) client_data;
    fprintf(stderr, "%s\n%s\n%s\n", address->name, address->street,
            address->city);
}
main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget box, quit, pressme, topLevel;
    static app_stuff stuff = {
        "John Doe",
        "1776 Constitution Way",
        "Philadelphia, PA 01029"
    };
      .
      .
    /* XtVaAppInitialize, create pressme widget */
      .
      .
    XtAddCallback(pressme, XmNactivateCallback, PressMe, &stuff);
      .
      .
}

/*ARGSUSED*/
void PressMe(w, address /* call_data omitted */)
Widget w;
app_stuff *address;     /* ANSI non-conformant cast */
/* third arg omitted - ANSI non-conformant */
{
    fprintf(stderr, "%s\n%s\n%s\n, address->name, address->street,
            address->city);
}

typedef struct {
    int     reason;
    XEvent  *event;
    int     click_count;
} XmPushButtonCallbackStruct;

You may register any number of callback functions for a single widget callback resource. In other words, when a callback is triggered by a user event, all the functions in the current callback list for that callback for that widget instance will be called, one at a time. Multiple callback functions are not needed in many applications, but can be useful if applied carefully.

There is no guarantee that the functions on a callback list will be called in the specified order. Therefore, each callback function must be independent of all other callback functions on the list. This dramatically reduces the usefulness of multiple callback functions.

Remember that most widgets also have more than one callback list, each triggered by a different occurrence. What we are talking about here is that you can register a series of functions to be called in response to one occurrence.

Let's take an example of how a callback list might be used. Perhaps you have the functions A, B, and C, and you need to be able to call them separately in response to events in three different PushButton widgets, or to call all of them in response to events in a fourth PushButton widget. How should we structure the callback for the fourth PushButton widget? The first approach is to have a callback list including the functions A, B, and C. This is preferred if A, B, and C can be called in any order, since you can pass a different piece of data into each routine. The other approach is to register a single callback, function D, that calls A, B, and C. In this case you are assured that A, B, and C will be called in the desired order.

You can also call the same function more than once in a callback list.

---

Note: Never use XtRemoveAllCallbacks(). Widget sets such as Motif add their own callback functions to many of the widgets, and depend on these functions to operate properly.

---

One way to add more than one callback function is to call XtAddCallback() more than once. Another way is to call XtAddCallbacks(), which takes an XtCallbackRec array as an argument. This array is usually initialized at compile time, as shown in Example 3-12. The final NULL, NULL entry terminates the list. (This particular list registers the functions do_A and then_B, and passes them both 0 as client_data.)

XtCallbackRec quit_callback_list[]={
    {do_A, 0},
    {then_B, 0},
    {(XtCallbackProc) NULL, (XtPointer) NULL}
};

This form of XtCallbackRec list can also be used to replace a callback list with XtSetValues() (but not to get a callback list, because Xt compiles the list into an internal form). An XtCallbackRec list can also be used to register one or more callbacks when creating a widget.

The structure type that contains all the application variables to be set through resources is commonly called AppData. Once this structure type is declared, memory can be allocated for a structure called app_data. Example 3-13 shows the code that defines the structure type and then allocates memory for the actual structure.

typedef struct {
        Pixel copy_fg;
        Pixel copy_bg;
        int pixmap_width_in_cells;
        int pixmmap_height_in_cells;
        int cell_size_in_pixels;
        Boolean debug;
} AppData;

AppData app_data;

As usual in C, the members of the app_data structure will be referenced throughout the application code using the dot format. For example, the value of the debug field of app_data will be referenced with app_data.debug.

The resource list looks complicated, but it is easy to understand and even easier to write because it conforms to a consistent pattern. Each field in the application data structure has an entry in the resource list. Each resource entry in turn has seven fields, which describe the name of the resource, its type and default value, and various other information.

The resource list controls Xt's value conversion facilities. Since user resources are always strings, and application data structure fields can be any type, a conversion may have to take place. Xt has built-in converters to convert from string to most common types needed by applications. These types are called representation types by Xt, and they are indicated by constants starting with XmR in Motif, or XtR in standard Xt. The representation type of a string (char *) is XmRString. A Motif compound string is XmRXmString. You control the conversion simply by specifying a resource as a certain representation type in the resource list.

It is possible to represent the same value in several different representation types. For example, a color may be represented as an ASCII color name such as “blue,” as a structure containing Red, Green, and Blue values, or as a pixel value (an index into a colormap). Also note that a representation type is different from a C-Language type. It is also possible for two different representations of something to both use the same C-Language type. For example, two hypothetical representation types might be XtRInch and XtRMeter. Both represent distances and both would probably be integers or floating point numbers, but each would have a different value for the same distance.

See "Chapter 10, Resource Management and Type Conversion," for a description of the standard representation types, as well as information on how to write your own converter routine.

Example 3-14 shows the resource list for xbitmap4, followed by a description of each of the fields in each entry.

/*
 * The following could be placed in a "xbitmap.h" file.
 */
#define XtNdebug "debug"
#define XtCDebug "Debug"
#define XtNpixmapWidthInCells "pixmapWidthInCells"
#define XtCPixmapWidthInCells "PixmapWidthInCells"
#define XtNpixmapHeightInCells "pixmapHeightInCells"
#define XtCPixmapHeightInCells "PixmapHeightInCells"
#define XtNcellSizeInPixels "cellSizeInPixels"
#define XtCCellSizeInPixels "CellSizeInPixels"

static XtResource resources[] = {
    {
        XtNforeground,
        XtCForeground,
        XtRPixel,
        sizeof(Pixel),
        XtOffsetOf(AppData, copy_fg),
        XtRString,
        XtDefaultForeground
    },
    {
        XtNbackground,
        XtCBackground,
        XtRPixel,
        sizeof(Pixel),
        XtOffsetOf(AppData, copy_bg),
        XtRString,
        XtDefaultBackground
    },
    {
        XtNpixmapWidthInCells,
        XtCPixmapWidthInCells,
        XtRInt,
        sizeof(int),
        XtOffsetOf(AppData, pixmap_width_in_cells),
        XtRImmediate,
        (XtPointer) 32,
    },
    {
        XtNpixmapHeightInCells,
        XtCPixmapHeightInCells,
        XtRInt,
        sizeof(int),
        XtOffsetOf(AppData, pixmap_height_in_cells),
        XtRImmediate,
        (XtPointer) 32,
    },

    {
        XtNcellSizeInPixels,
        XtCCellSizeInPixels,
        XtRInt,
        sizeof(int),
        XtOffsetOf(AppData, cell_size_in_pixels),
        XtRImmediate,
        (XtPointer) 30,
    },
    {
        XtNdebug,
        XtCDebug,
        XtRBoolean,
        sizeof(Boolean),
        XtOffsetOf(AppData, debug),
        XtRImmediate,
        (XtPointer) False,
    },
};

A resource list entry has the following fields:

Table 3-1 lists Motif and standard Xt resource types and the C data types they represent.

Once the application data structure and resource list are set up, you pass pointers to them to XtGetApplicationResources(), just after calling XtAppInitialize(). XtGetApplicationResources() will search the databases for any matching resource settings and set the fields in the application data structure.

The last requirement is that you check the values specified by the user to make sure they are acceptable. Example 3-15 shows these two steps from xbitmap4.

     .
     .
     .

AppData app_data;
     .
     .
     .

main(argc, argv)
int argc;
char *argv[];
{
    XtAppContext app_context;
    Widget toplevel, vpane, buttonbox, quit, output;
        .
        .
        .

    /* call XtAppInitialize here */

    XtVaGetApplicationResources(toplevel,
            &app_data,
            resources,
            XtNumber(resources),
            /* varargs list here for making
             * application resources
             * non-user-configurable */
            NULL);        /* terminate varargs list */

    /*
     * We must check the application resource values here.
     * Otherwise, user could supply out of range values.
     * Conversion routines do this automatically, so
     * colors are already checked.
     */
    if ((app_data.pixmap_width_in_cells > MAXBITMAPWIDTH) ||
            (app_data.pixmap_width_in_cells < MINBITMAPWIDTH) ||
            (app_data.pixmap_height_in_cells > MAXBITMAPHEIGHT) ||
            (app_data.pixmap_height_in_cells < MINBITMAPHEIGHT)) {
        fprintf(stderr, "xbitmap: error in resource settings:",
                "bitmap dimension must be between %d and %d cells\n",
                MINBITMAPWIDTH, MAXBITMAPHEIGHT);
        exit(1);
    }

    if ((app_data.cell_size_in_pixels < MINCELLSIZE) ||
            (app_data.cell_size_in_pixels > MAXCELLSIZE)) {
        fprintf(stderr, "xbitmap: error in resource settings:",
                "cell size must be between %d and %d pixels\n",
                MINCELLSIZE, MAXCELLSIZE);
        exit(1);
    }
        .
        .
        .
}

Because Xt automatically converts the user's color specifications (such as “blue”) into the form required by X, it warns the user when an unknown color is specified.^[28] Therefore, your code doesn't need to check this kind of validity for values that Xt or Motif converts. However, you may need to check for other kinds of validity of the same values. For example, you may wish to check that two colors are not the same by comparing values after conversion. In this case, only the bitmap dimensions and cell size are checked, since they are critical to the application's operation.

First of all, XtAppInitialize() recognizes the -xrm option for setting any widget or application resource. For example:

spike%  xhello -xrm '*background: blue'

This command-line argument sets all widget resources and application resources that are named background to blue. This option style is awkward. Not only is it long, but csh users must quote the string with right-handed single quotes so that the asterisk (*) is not interpreted by the shell.

XtAppInitialize() also understands some command-line options that were considered so basic that they should be the same for all applications. The above -xrm command line can be replaced by:

spike%  xhello -background blue

or:

spike%  xhello -bg blue

XtAppInitialize() also understands any unique abbreviation of an option name, such as:

spike%  xhello -backg blue

These resources will work with any application written using the X Toolkit--with any widget set. Try the command line above if you have a color screen. If not, try specifying a different font, using the -fn or -font option.

Table 3-2 lists the complete set of standard options.^[29] Resources starting with a dot rather than an asterisk indicate that that option affects only the application's top-level Shell.

Note that many of these command-line options set the resource of every widget in the application to the same value. A few of them set the resources only of the application's top-level Shell widget.

Also note that there is no standard command-line option for the XtNfontSet resource (new in R5). You must use -xrm to set this on the command line.

Supplying your own command-line options allows you to simplify the customization of your application. It also allows the user to customize things that are difficult with the resource database (such as setting different values for the same resource in two instances of the application).

You make XtAppInitialize() understand additional command-line options by initializing a XrmOptionDescRec structure (called the options table) and passing it as an argument to XtAppInitialize(). Example 3-16 shows the code that implements command-line options for the application resources added in Example 3-14.

/* include files, etc. */
      .
      .
      .
#define MINBITMAPWIDTH  2
#define MAXBITMAPWIDTH  1000
#define MINBITMAPHEIGHT  2
#define MAXBITMAPHEIGHT  1000
#define MINCELLSIZE  4
#define MAXCELLSIZE  100

static XrmOptionDescRec options[] = {
    {"-pw",           "*pixmapWidthInCells",  XrmoptionSepArg, NULL},
    {"-pixmapwidth",  "*pixmapWidthInCells",  XrmoptionSepArg, NULL},
    {"-ph",           "*pixmapHeightInCells", XrmoptionSepArg, NULL},
    {"-pixmapheight", "*pixmapHeightInCells", XrmoptionSepArg, NULL},
    {"-cellsize",     "*cellSizeInPixels",    XrmoptionSepArg, NULL},
    {"-fg",           "*foreground",          XrmoptionSepArg, NULL},
    {"-foreground",   "*foreground",          XrmoptionSepArg, NULL},
    {"-debug",        "*debug",               XrmoptionNoArg, "True"},
};

static void Syntax(argc, argv)
int argc;
char * argv[];
{
    int i;
    static int errs = False;

    /* first argument is program name - skip that */
    for (i = 1; i < argc; i++) {
        if (!errs++) /* do first time through */
            fprintf(stderr, "xbitmap4: command line option unknown:\n");

        fprintf(stderr, "option: %s\n", argv[i]);
    }

    fprintf(stderr, "xbitmap understands all standard Xt\
            command-line options.\n");

    fprintf(stderr,"Additional options are as follows:\n");
    fprintf(stderr,"Option        Valid Range\n");
    fprintf(stderr,"-pw           MINBITMAPWIDTH to\
            MAXBITMAPWIDTH\n");
    fprintf(stderr,"-pixmapwidth  MINBITMAPWIDTH to\
            MAXBITMAPWIDTH\n");
    fprintf(stderr,"-ph           MINBITMAPHEIGHT to\
            MAXBITMAPHEIGHT\n");
    fprintf(stderr,"-pixmapheight MINBITMAPHEIGHT to\
            MAXBITMAPHEIGHT\n");
    fprintf(stderr,"-cellsize     MINCELLSIZE to\
            MAXCELLSIZE\n");
    fprintf(stderr,"-fg           color name\n");
    fprintf(stderr,"-foreground   color name\n");
    fprintf(stderr,"-debug        no value necessary\n");
}

main(argc, argv)
int argc;
char *argv[];
{
    XtAppContext app_context;
    Widget toplevel, vpane, buttonbox, quit, output;
      .
      .
      .

    toplevel = XtVaAppInitialize(&app_context;
            "XBitmap4",
            options,             /* command line option table */
            XtNumber(options),
            &argc,
            argv,

            NULL,
            NULL);

    /* XtVaAppInitialize always leaves at least prog name in args */
    if (argc > 1)
        Syntax(argc, argv);
        .
        .
        .
}

Each options table entry consists of four fields:

The enum constants that specify the various command-line argument styles are as shown in Table 3-3.

The options table is passed to XtAppInitialize() as its third argument, and the number of options table entries as the fourth. The XtNumber() macro is a convenient way to count the number of entries (this is only one of many contexts in which you'll see this macro used).

Note that you cannot override the standard options by providing options with the same names in your own parsing table. If you try this, your options with the same names will simply not be set to the values specified on the command line. Instead, the standard options will be set to these values. This was a design decision in Xt, one of the few cases where a user-interface policy is enforced. Uniformity in this basic area was deemed more valuable than flexibility.

Also note that there is no way to instruct Xt to interpret more than one argument format for the same option. For example, you cannot arrange for -size 3 and -size3 both to work.

XtAppInitialize() removes all the arguments it recognizes (including those in your options table) from argv and argc. If all goes well, only the application name will remain in argv, and argc will equal one. It is important to check whether there is more than one argument left after XtAppInitialize() has returned. Command-line options that XtAppInitialize() doesn't recognize will be left in argv and argc. This is your chance to catch this error and tell the user.^[30] The Syntax function shown in Example 3-16 demonstrates code that informs the user of the proper syntax and the option that was not understood. (In response to incorrect command-line options, UNIX programs traditionally print only the correct calling sequence. However, you can be even nicer to the user by printing the option or options that were in error, by passing argv and argc into your Syntax function, as is done in Example 3-16.

Experienced UNIX programmers will note that Xt applications can (but usually don't) use the single-letter command-line arguments mandated by POSIX and the System V Interface Definition. As mentioned earlier, Xt automatically matches any unique abbreviation for any command-line option. For example, by default the -display option can be specified as -d, but only if you haven't included any other option in the options table that also begins with d. You can define the meaning of single-letter options simply by including them verbatim in the options table. In other words, if you specify that -d turns on a debugging resource, Xt will no longer try to match any other, longer option that also begins with d.

Note that the argc and argv arguments of XtAppInitialize() are in the same order as in the call to main. This is the opposite order of arrays and array lengths throughout other Motif, Xt and Xlib routine calls. Also note that the address of argc, not argc itself, is passed to XtAppInitialize(). This is so that XtAppInitialize() can decrement the count to reflect recognized options. Watch out for these snags.

Setting widget resources in XtVaCreateManagedWidget() is the cleanest and most powerful way to do it. You have already seen the style of call shown in Example 3-17, but pay particular attention to the XtVaTypedArg entry. This example also shows the special technique required to set a Motif compound string in the code.

main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, layout, quit;
    XmString text;
      .
      .
      .
    layout = XtVaCreateManagedWidget("layout", formWidgetClass,
            topLevel, NULL);
    text = XmStringCreateLtoR("Quit", XmFONTLIST_DEFAULT_TAG);
    quit = XtVaCreateManagedWidget("quit", xmPushButtonWidgetClass,
            topLevel,
            XmNwidth, 200,
            XtVaTypedArg,     XmNbackground,
            XmRString,        "red", strlen("red")+1,  /* cont'd */
            XmNsensitivity,   True,
            XmNlabelString,   text,
            NULL);
    XmStringFree(text);
      .
      .
      .
}

The standard varargs list entry is a resource name/value pair. The value must be already converted into the type required for that resource (documented on the widget's reference page). XtVaTypedArg (not Xm...) is a special symbol used just before a resource name, which, when encountered, indicates that the next four arguments specify a resource that needs to be converted.^[32] In Example 3-17, the value “red” needs to be converted into a pixel value, which is the index to the colormap register that contains the correct RGB values to display on the screen. The argument XmNbackground is the resource to be set. XmRString is the type of the value to be converted. The final two arguments are the pointer to the value (or the pointer to the pointer to the value if not a string) and the size of the value pointed to in bytes. XtVaTypedArg can be used to convert any string that is valid in a resource file but is otherwise difficult to set in the source file. But don't use XtVaTypedArg unnecessarily, since it adds overhead.

The varargs interfaces will also accept an arglist as one item in the list, using the symbol XtVaNestedList as the resource name. XtVaNestedList allows you to create one argument list and pass it to a series of widget creation routines, instead of listing all the same resource settings in each widget creation routine. For more details on this, see "Chapter 10, Resource Management and Type Conversion."

There is some extra overhead involved in using the varargs interfaces because they massage the arguments into an argument list and call XtCreateWidget(), XtCreateManagedWidget(), XtSetValues(), or XtGetValues(). However, the added convenience seems worth it. Furthermore, the XtVaTypedArg feature is not supported in the ArgList style of call (described in the next section).

Unless you use the XtVaTypedArg feature, no diagnostic is printed when you specify a resource value incorrectly in the argument list. Therefore, make sure you specify the resource values correctly, and recognize this as a possible place to begin looking for bugs. (This is another reason to hardcode resources only when the application is almost ready for release. If you do it all at once in a methodical fashion, you are less likely to make mistakes than if you are always adding, subtracting, and changing values in the argument lists.)

---

Note: If you use the varargs style of arguments, but forget to type the Va in the function name, you can get various types of errors. If you specify resources in the call, you will get a core dump at run time, but you can detect the problem with lint, which will note the function as having a variable number of arguments. If you don't specify resources in the call, the application will run but you will get the message: Warning: argument count > 0 on NULL argument list

---

Widget resources can also be hardcoded by creating an argument list containing the resources to be set and their values, and passing it to XtCreateManagedWidget(). This method of setting resources is less convenient that the varargs technique just described, but it was the only way until R4, and therefore many existing applications use it.

An argument list is just an array of Arg structures, of the same type as you set up to call XtSetValues() or XtGetValues(). Once set, this array is used as an argument to XtCreateManagedWidget(). Each Arg structure contains a resource/value pair. Attributes specified here override the same ones specified from the command line or from resource databases.

Example 3-18 shows an argument list that hardcodes the sensitivity of a PushButton widget and its callback list. Sensitivity is a good thing to hardcode for PushButton widgets, because if accidentally set by the user it could disable an application.^[33] The callback list cannot be specified by the user anyway; setting it here is just an alternative to calling XtAddCallback().

The XtArgVal type used in the callback list aids in porting Toolkit programs to different architectures. It allows the system manufacturer to select the type in the typedef for XtArgVal, so that the application program need not worry about it. The value field of the Arg structure may be a number or a pointer.

Arg quit_args[] = {
    XmNsensitive,     (XtArgVal) True,
    XmNactivateCallback,      (XtArgVal) quit_callback_list,
};

An argument list can be used as an argument in the call to create a widget, as shown in Example 3-19.

/* define quit_args */
main(argc, argv)
int argc;
char *argv[];
{
    Widget quit, box;
    /* create box */
      .
      .
      .
    quit = XtCreateManagedWidget(
            "quit",                     /* widget name */
            xmPushButtonWidgetClass,    /* widget class */
            box,                        /* parent widget */
            quit_args,                  /* argument list */
            XtNumber(quit_args)         /* arglist size */
            );
      .
      .
      .
}

Note the use of the XtNumber() macro to calculate how many arguments there are in the statically initialized argument list. This macro eliminates the need to keep track of the number of resources you have set.

Note also that the value field in the argument list must be in the correct representation type for that resource, which is often not a string. You may need to call XtConvertAndStore() to arrive at the right representation of the data to be placed in the argument list. For details on calling XtConvertAndStore(), see "Chapter 10, Resource Management and Type Conversion." An easier way to do this is to use the XtVaTypedArg feature supported by the varargs interfaces.

As mentioned earlier, unless you invoke a converter, no diagnostic is printed when you specify a resource value incorrectly in the argument list. Therefore, make sure you specify these correctly.

int i;
Arg args[10];
/* XtAppInitialize may be called before or after the XtSetArg calls */
i = 0;
XtSetArg(args[i], XmNactivateCallback, (XtArgVal)
        quit_callback_list); i++;
XtSetArg(args[i], XmNsensitive, (XtArgVal) True); i++;
banner = XtCreateManagedWidget(
        banner,                    /* widget name */
        xmPushButtonWidgetClass,   /* widget class from Label.h */
        toplevel,                  /* parent widget */
        args,                      /* argument list */
        i);                        /* arg list size from XtSetArg counter */

Arg arg[10];
int num_args;
/* This example will NOT work correctly! */
num_args = 0;
/* The next two lines are wrong! */
XtSetArg(args[num_args++], XtNresource1, (XtArgVal) 10);
XtSetArg(args[num_args++], XtNresource2, (XtArgVal) 40);
      .
      .
      .