There are several broad categories of errors that may occur in Xt applications. One is the X server error, which is a form of event that tells the client that some parameter in an earlier request was illegal, or that no more server memory is available. A second is the connection failure error generated by Xlib when the connection with the server fails (usually due to a system crash or network interruption). Xlib provides the XSetErrorHandler() and XSetIOErrorHandler() functions to allow the application to provide a routine to handle these two types of errors. Xt provides no interface to these routines--Toolkit applications must use the Xlib routines to customize these error handlers (Xlib uses default error handlers when the application does not use these routines to specify them). For a description of these error handlers and the routines for changing them, see Volume One, Xlib Programming Manual.

A third category is made up of error and warning messages that Xt reports when function parameters are specified improperly, when a translation is incorrectly specified, and for many other reasons. For a complete listing of all errors and warnings that can be generated by Xt, see Volume Five, X Toolkit Intrinsics Reference Manual, Appendix D, Standard Errors and Warnings. Xt provides separate parallel routines for errors and for warnings. The difference between Xt errors and Xt warnings is that errors are fatal and the application exits after printing the error, while warnings are nonfatal and the application continues. The main purpose of these facilities is to generate consistent messages.

Two levels of interface are provided:

These error-reporting interfaces are used internally by Xt, but widget or application code can also use them. For example, when a resource is given an illegal value in a resource file, the widget or application can report the error or warning to the user (which depends on whether the widget or application can continue after the error--most widgets issue only warnings and then fall back on their default value).

The low-level handlers are much easier to use, but they do not support internationalization (alternate languages) at all since the messages are hardcoded in the application. The high-level handlers can potentially support internationalization, but not as elegantly as the normal resource database since Xt searches for the error database file in a fixed location, not using the language string. If you want your application or widget to run in more than one language, you should use the high-level handlers, but only one database for one language can be installed on a system at a time. This is likely to be improved in later releases of Xt.

To use the low-level handlers, you specify the string message as the sole argument to XtAppError() or XtAppWarning().

Contrary to what you might expect, the high-level handlers XtAppErrorMsg() and XtAppWarningMsg() are actually harder to use than the low-level handlers. You must pass six arguments to the calls that generate the errors or warnings, and then to take advantage of their benefits you must set up an error resource database. The first three arguments are the name, type, and class of the error. The use of these three arguments is not yet standardized since they are not widely used. However, in Xt itself, the name identifies the error message, and the type identifies the task that was in progress when the error occurred (or the section of code). The class, within Xt, is always XtToolkitError. The three remaining arguments of XtAppErrorMsg() and XtAppWarningMsg() are a default message, a parameter list, and the number of parameters. The default message will be printed only if no matching message is found in the database. Because Xt does not define or install any error database, it uses these default messages only, and ignores the name, type, and class information. (Xt uses the high-level handlers so that an error resource file can be installed to print all the errors in a foreign language.) The parameter list is used together with the message in the database. The message may be in standard printf format, and the parameters are used to fill in any variable fields.

Example 14-1 shows one of the rare cases where XtAppErrorMsg() is invoked in the Athena widgets.

    if (src->ascii_src.string == NULL)
        XtAppErrorMsg(XtWidgetToApplicationContext(src),
                "NoFile", "asciiSourceCreate", "XawError",
                "Creating a read only disk widget and no file \
                specified.", NULL, 0);

The error resource database is stored in a file, /usr/lib/X11/XtErrorDB, under most UNIX-based operating systems. The MIT distribution does not include an XtErrorDB database, but you can define one. Since this database is made up of one file, you must append the resource settings you need to this file rather than replacing it. The resource name searched for in the database is the concatenation of the name and type arguments specified in the calls to XtAppErrorMsg() or XtAppWarningMsg().

You can redefine the routine that prints the message in order to change the fixed part of the message or to add features like logging of errors and warnings. Use XtAppSetErrorMsgHandler() and XtAppSetWarningMsgHandler() (if you are using the high-level handlers) or XtAppSetErrorHandler() and XtAppSetWarningHandler() (if you are using the low-level handlers). See the reference pages for XtErrorMsgHandler(2) and XtErrorHandler(2) in Volume Five, X Toolkit Intrinsics Reference Manual, for a description of how to define a new error or warning handler. The default error and warning messages printed are:

X Toolkit Error:   message.            (for errors)
X Toolkit Warning: message.            (for warnings)

Remember that Xt itself uses these messages (not just your widget code), so that they must remain appropriate when called from anywhere in the Xt, widget, or application code. If you want the message to identify the name of the widget set or widget, you must include this information in the part of the message filled in from the string you pass or from the resource database.

Table 14-1 summarizes Xt's calls for issuing errors and warnings and for modifying the messages issued.

Note, however, that for the high-level routines that use the error and warning resource database, there is only one database common to all application contexts, at least in the sample implementation of Xt provided by MIT in R4 and R5.

When writing a high-level error or warning handler you will need to call XtGetErrorDatabase() to get a pointer to the error resource database and XtGetErrorDatabaseText() to get the message for a particular set of arguments passed to XtAppErrorMsg() or XtAppWarningMsg(). For details on how to use these functions, see the reference pages in Volume Five, X Toolkit Intrinsics Reference Manual.

XtDisplayStringConversionWarning() is a convenience routine to be used in resource type converters that convert from XmRString to any representation type. It calls XtAppWarningMsg() with the appropriate arguments to issue a suitable warning. Note however, that the class used is XtToolkitError. It may be better to use a class that describes the widget or widget set that defines the converter.

Most of this book describes how to use widgets, which are subclasses of the Core widget class. Chapter 13, Menus, Gadgets, and Cascaded Popups, also discusses using gadgets, which are subclasses of the RectObj widget class. As described there, gadgets are windowless widgets that are especially useful for menu panes, because they cut back on the overhead that would be required to implement the same thing using a widget for each pane.

The third and final Xt class you can subclass is the Object widget class. Objects are windowless widgets like gadgets, but they lack geometry resources, sensitivity resources, and the expose method. They provide support for resources and callbacks, and that is all.

The primary use of objects is to create replaceable subparts of a widget. For example, the R4 Athena Text widget uses objects to implement its source and sink, which control the storage and the display of the data respectively. By replacing the source and sink, you could develop a multi-color or multi-font editor without having to rewrite the central widget which implements all the editing commands.

An object has the following methods: class_initialize, class_part _initialize, set_values, and get_values_hook. All these methods have the same purposes as in widgets.

While a gadget uses part of its parent's window, an object shares its parent's entire window, and is not managed at all by its parent since it has no geometry. The parent of an object is normally a widget that is a subclass of Core but not Composite or Constraint (unlike gadget parents).

But like gadgets, objects depend on cooperation by their parent, and require a specially designed parent. The object parent's methods make calls to functions defined by the object child instead of doing the work themselves. The object child's functions can be either semi-public functions or they can be class methods defined by the object. The latter is done so that subclasses of the object can replace the functions.

As an example, let's look at how the Athena Text widget handles drawing. The drawing is done by the TextSink object, and its subclass AsciiSink. Although an object has no expose method, it provides an equivalent function that draws on the parent. This function is either a semi-public function (public to its parent but not to the application writer), or it is a class method. The Text widget uses both techniques. TextSink provides a semi-public function XawTextSinkDisplayText(), which is called by Text whenever drawing is needed.

XawTextSinkDisplayText() calls one of TextSink's class methods called DisplayText. DisplayText is a class method so that subclasses of TextSink can replace it or inherit it. AsciiSink does replace this method with code that draws the text in a single constant-width font, in the foreground and background colors. So in order to write a Text widget that draws in more than two colors, you would just have to write an object that is a new subclass of TextSink.

When Text calls XawTextSinkDisplayText(), this function calls one of TextSink's class methods called DisplayText. DisplayText is a class method so that subclasses of TextSink can replace it or inherit it. AsciiSink does replace this method with code that draws the text in a single constant-width font, in the foreground and background colors. So in order to write a Text widget that draws in more than two colors, you would just have to write an object that is a new subclass of TextSink.

An object may assume that it should draw on its parent, but this is not necessarily the case, since an object could have an object as its parent. An object also has no idea of its own size, since it has no geometry data in its instance structure, and therefore doesn't by itself know what size window it is drawing into. To solve both these problems, XawTextSinkDisplayText() passes the parent's widget ID and the parent's size into the objects drawing code.

Xt provides several macros and functions for getting information about widgets. Some of these, such as XtIsRealized() and XtIsManaged(), you have seen before in the context of widget methods.

Some of these are macros and some are functions, and some are macros when used in widget code and functions when used in application code. This does not affect how they can be used, so we won't bother to specify which can be both functions and macros. We will use the term “macro” for all of these informational routines. In Volume Five, X Toolkit Intrinsics Reference Manual, they are listed alphabetically, together with all of the Intrinsics functions.

Xt provides two basic macros for determining the class of a widget: XtIsComposite() and XtIsSubclass(). These are primarily used internally by Xt to implement geometry management, but you may find a use for them. For example, you might write a composite widget that uses XtIsComposite() to treat composite children differently than simple children, or uses XtIsSubclass() to treat constraint children or one of your own classes uniquely. There are lots of convenience functions for XtIsSubclass() that determine if a widget is a subclass of a particular class. These are XtIsObject(), XtIsRectObj(), XtIsWidget(), XtIsComposite(), XtIsConstraint(), XtIsShell(), XtIsOverrideShell(), XtIsWMShell(), XtIsVendorShell(), XtIsTransientShell(), XtIsTopLevelShell(), and XtIsApplicationShell().

You have already seen XtIsManaged() used in composite widgets. See Chapter 12, Geometry Management.

You have also already seen XtIsRealized() used in various methods to make sure a widget has a window before operations are attempted on the window. For example, the expose method calls XtIsRealized() before drawing into the window.

XtIsSensitive() checks the value of the XmNsensitive resource for a widget and its ancestors. If any of them is False, it returns False. Remember that sensitivity controls whether a widget responds to user events.

XtHasCallbacks() lets you tell whether a widget class has a callback of a certain resource name, and whether any callback functions have actually been added to it. It returns the enum value XtCallbackNoList if there is no callback list, XtCallbackHasNone if there is a callback list with no functions on it, and XtCallbackHasSome if there is a callback list containing functions pointers.

XtNameToWidget() searches a hierarchy for the widget ID of the specified widget instance name. Its primary use from the application is to get the IDs of the child widgets of a compound widget such as Dialog, so that their resources can be set directly. This is a violation of the rules of data hiding, however, and is not recommended. In widget code, XtNameToWidget() is used to provide a layer of abstraction so that widgets can be identified using string names. For example, it is used by the converter defined by Form that allows widget names to be specified in resource files. The opposite function, which returns a widget instance name given the widget ID, is XtName() (which perhaps should have been called “XtWidgetToName”).

XtWindowToWidget() gives you the Widget which corresponds to the specified X window ID. This is used mainly by Xt, but you may find a use for it.

XtDisplayOfObject(), XtScreenOfObject(), and XtWindowOfObject() search the parental hierarchy of an object to discover the closest windowed ancestor and then return a pointer to a Display structure, a pointer to a Screen structure, or a Window ID. These macros are useful for making Xlib calls from within code that implements a subclass of Object.

XtGetApplicationNameAndClass() returns the name and class strings of an application. The name is usually argv[0] stripped of any directories, while the class is the string passed as the second argument of XtAppInitialize(). These are the name and class used by Xt to look up resources for the application and its widgets. You are not likely to need this function.

The keyboard focus is the window to which the server sends keyboard events. The window manager controls which top-level window gets the keyboard focus (using either a click-to-type or pointer-following model). Once an application's top-level window gets the focus, it can set the focus to one of its children; that's the way Motif's keyboard traversal code works. As described in Chapter 5, More About Motif, within a Motif application, you can have either a click-to-type or pointer-following model, although keyboard operation is only possible if the click-to-type model is used.

The Core class part structure includes a field for the accept_focus method. Theoretically, this method lets a widget set the keyboard focus to one of its children when it gets the keyboard focus. A typical example is an application that wants to set the keyboard focus to the text entry child of a dialog box whenever the dialog box is given the keyboard focus by the window manager. This would be done so that the user can type with the pointer anywhere in the dialog widget instead of just with the pointer in the text entry widget.

To implement this example, the text entry child would need an accept_focus method that would set the keyboard focus to itself using the Xlib call XSetInputFocus(). The dialog box would need an accept_focus method that called XtCallAcceptFocus() on the text entry widget child. The application can call XtCallAcceptFocus() on the dialog widget in response to FocusIn events to start this process, and set the focus back to PointerRoot on FocusOut events. For details on these events, see Volume Two, Xlib Reference Manual. This procedure for giving the child of a dialog the keyboard focus is necessary because the application can't find out the name of the child that should have the focus without breaking widget encapsulation rules.

In reality, none of the Motif widgets (and none of the Athena widgets, for that matter) use the accept_focus method. The keyboard traversal code is implemented separately.

An accept_focus method should return a Boolean value to report whether it succeeded in setting the keyboard focus, and XtCallAcceptFocus() returns this same value.

The XtSetKeyboardFocus() function redirects keyboard events that occur within an application to any widget within that application. This is different from XSetInputFocus() in that no request to the server is made, and the redirection of keyboard events is handled entirely by Xt's event dispatching mechanism. However, XtSetKeyboardFocus() should not be used in Motif applications, since it interferes with the keyboard traversal code.

Keyboard handling in X is designed so that you can write a program that will operate on systems with widely different physical keyboards. To accomplish this, there are several layers of mappings:

Motif adds virtual key bindings to this model, as described in Section 5.9, "Drag and Drop."

When you write an action that accepts key events, you will usually need to interpret the meaning of the key pressed. Xt provides its own interface to XLookupString(): XtTranslateKeycode(). You pass several fields of the key event to XtTranslateKeycode(), and it returns the keysym. However, XtTranslateKeycode() does not return the string interpretation of the key event that would be returned by XLookupString(). If you need that string, you will have to call XLookupString().

Xt provides XtTranslateKeycode() because Xt also provides routines for changing the way the translation returned by XtTranslateKeycode() is done. XtSetKeyTranslator() allows you to specify your own procedure to convert from the key event information to a keysym. The default key event translation procedure is XtTranslateKey(), and so you can restore the default translator if necessary, and so that you can call it from your own translator to get default translations (you need to add only the code that makes the translations not done by the default translator). See XtKeyProc in Volume Five, X Toolkit Intrinsics Reference Manual, for details on providing a key event translation procedure.

Among these routines for modifying the interpretation of key events is a facility for changing the handling of capitalization. For example, most keyboards have the question mark (?) symbol over the slash (/) symbol on one key. The standard case converter converts a press of this key with the Shift key held down to the XK_question keysym. In rare cases a keyboard may have a different symbol over / and put ? somewhere else. Also, some keyboards have two or more symbols on a single key, some of which are not represented at all by standard keysyms. The case converter handles these situations. The case converter is usually called from the key translator described above. To call the case converter, use XtConvertCase(), and to change the case converter, call XtRegisterCaseConverter(). See XtCaseProc in Volume Five, X Toolkit Intrinsics Reference Manual, for details on writing a case converter procedure.

Note that the translation manager uses these same key translation and case converter routines to interpret translation tables. Therefore, make sure that you add features only to them, keeping existing features.

Xt also provides two routines that may help in interpreting key events: XtGetKeysymTable() and XtKeysymToKeycodeList(). The former returns the entire mapping of keycodes to keysyms for the server, while the latter tells you what keycodes are listed for the specified keysym. Neither function is necessary for routine keyboard handling.

From within an action routine, you can call XtGetActionKeysym() to get the keysym that resulted in the action being called. This can be very useful, since the event passed to the action contains only the keycode of the key that was pressed. However, there is another way to achieve a similar result. You can use string parameters of actions to pass in the keysym that you specified in the translation table. For example, if you provide the translation :<Key>q : Quit(q), the Quit action will be passed the string “q” in its params argument. However, XtGetActionKeysym() is very useful if you translate a wide range of key events to one action, and then want to distinguish between them in the action.

Xt provides routines for performing routine memory allocation and deallocation. The routines XtMalloc(), XtCalloc(), XtRealloc(), and XtFree() are equivalents of the standard C routines malloc, calloc, realloc, and free but they add error checking and reporting. The allocation routines make sure the allocation succeeded, and if it did not, they print a (fatal) error message. XtFree() makes sure the passed pointer is not NULL before calling free.

XtNew() is a macro which allocates storage for one instance of the passed type and returns a pointer. For example, XtNew(XtCallbackList) allocates storage for one callback list structure. XtNewString() is a macro that allocates storage for a string, copies the string into the new storage, and returns the pointer. For example, a string can be copied into new storage using the following:

    static String buf[] = "How do you do?";
    String p;
    p = XtNewString(buf);

After this sequence, p points to a separate string that contains “How do you do?” Then buf can be changed without affecting p.

Xt allows you to register any number of functions to be called whenever any action in an application context is invoked. This is done with XtAppAddActionHook(). Note that there is just one “action hook” in the application context, so that all the action hook functions registered for that application context are called whenever any of the actions in that application context are invoked. The registration does not specify any particular action or any particular widget.

The main reason for registering an action hook is to record all the actions that were invoked in an application, so that they can be played back later using XtCallActionProc(). An action hook function is called with all the same arguments that are passed to an action, plus the string name of the action. The action hook function would store this information as a unit each time it was called. When it comes time to play back the recorded actions, it would pass all the information in each unit to XtCallActionProc().

An action hook can be removed with XtRemoveActionHook().

Grabs are used mostly for popup menus and dialog boxes. As described in Chapter 13, Menus, Gadgets, and Cascaded Popups, Xt has its own grab mode that controls the distribution of events within one application, which can be used to restrict events to one popup in a cascade or allow events to go to any popup in a cascade. As also described there, popup menus in particular need a passive global grab of the pointer in order to detect button releases that occur completely outside the application so that menus can be popped down properly. A passive global grab actually instructs the server to redirect events to a certain window. All the grabbing needs of popups are satisfied by the built-in action XtMenuPopup(), or by the function XtPopupSpringLoaded(), which can be used in a callback function. If necessary, you can write your own version of XtMenuPopup() and register it with XtRegisterGrabAction() so that the appropriate passive global grab is in effect.

The above facilities should be quite sufficient for your needs in the area of popups. However, it is possible that you may need an global grab for some other purpose. Perhaps you need all keyboard events in one window for a short time and don't want to change existing translations or accelerators for keyboard events in other widgets. This is only one plausible scenario.

The Xlib functions for grabbing are XGrabKey(), XGrabButton(), XGrabKeyboard(), and XGrabPointer(). Each of these functions has an analogue for ungrabbing. But Xt provides its own version of all eight of these functions. You should use the Xt versions because they are integrated into Xt and take care of things like making sure the widget that is to get the grab has been realized. In other words, if you do need the server to redirect events for you using a grab, use the following functions: XtGrabKey(), XtGrabButton(), XtGrabKeyboard(), XtUngrabKeyboard(), and XtUngrabPointer(). For more on global grabs, see Chapter 8 in Volume One, Xlib Programming Manual.

Xt's facilities for allowing an application to run in different languages are mostly built into the resource database mechanism. Where Xt searches for resource files depends on a language string, which can be set within resources at run time or with an environment variable to affect one user's environment. This is described in Chapter 10, Resource Management and Type Conversion. In R5 and later, Xt also uses the value of the XtNcustomization resource to set the path it uses when looking for application defaults and other files. XtNcustomization is normally used to supply separate sets of resources for color and monochrome screens.

The functions that Xt uses to implement its search for resource files are also available to you for searching for application files. This allows you to provide separate data files for each language for a help system, for example. The primary function you would use to do this is XtResolvePathname(), since it searches directories in a standard order based on X/Open Portability Guide conventions.

If you want to find a file but are not interested in internationalization, you can use XtFindFile(). This function can simplify code that reads files, since it helps handle differences in file systems.

The introduction to application contexts in Section 3.9, "More About Application Contexts" described their use in 99 percent of applications. As you may recall, their purpose is chiefly to attain portability to certain systems that do not provide a separate address space for each process.

Xt provides parallel versions of many routines--one set that uses the default application context, and one set that has an explicit application context argument. The routines that use the default application context are remnants of an earlier release when application contexts did not work properly. To achieve the desired portability, you must now use the versions with the explicit argument. We have done this throughout this book. In Volume Five, X Toolkit Intrinsics Reference Manual, the reference pages for all the functions that use the default application context note the fact that they should no longer be used.

Table 14-2 shows the complete list of routines that have two versions.

Note that XtCreateApplicationShell() and XtAppCreateShell() have names that don't follow the example set by all the rest.

A single application can have more than one top-level window. In other words, you are not restricted to containing your application's entire user interface in a single rectangle. If you have one section of the application that is most appropriate as a long, thin vertical window that looks like a long, permanent menu, and another section that is a long, horizontal bar such as a ruler, each of these could be a separate top-level window. That way, not only is less screen space wasted than if these two windows were placed within a single rectangle, but the user can move the two windows around separately using the window manager. The user can also iconify them separately when not needed.

To create additional top-level application shell widgets, you call XtAppCreateShell() or XtVaAppCreateShell(). (XtCreateApplicationShell() is now superceded.) The class specified in the call should be topLevelShellWidgetClass.

As you may know, a single server may have several screens attached. At present, all shells created will appear on the default screen. There is no way for the application to specify that a shell be created on a particular screen, but then again, doing this is usually unwise anyway because not many users actually have more than one screen. The user can specify which screen is considered the default screen using the -display command-line option.

One of the great features of the server-client model is that a single program can connect to several servers to display on the screens of several users. For example, this would allow you to create an X-based version of the UNIX utility wall in which one user can make a message appear on all user's screens throughout a network. You could also create a conferencing program in which each user has a window on their screen in which they can type and view typing by others in real time, and their typing will appear on all the other user's screens.

The Xt application opens a connection with a server using XtOpenDisplay() (this routine requires an explicit application context argument). Once you have opened the connection, you will want to create a shell widget on the server's default screen using XtCreateApplicationShell() or XtAppCreateShell(). Then, you create widgets for each server simply by using the appropriate Shell widget as parent. Thereafter, XtAppMainLoop() dispatches events from all the connections to the appropriate widget.

X Consortium standards, once adopted, can only be changed in ways that are binary and source compatible with the original standard specification. Xt became an X consortium standard in Release 3. Therefore, Release 4 and later releases are required to be source and binary compatible with Release 3. Source compatibility means that properly coded applications and widgets written to the R3 specification should compile and work under R4 and later releases. Source compatibility is maintained by keeping all programming interfaces intact while adding features with new interfaces. Binary compatibility means that widgets written and compiled with R3 must be able to be linked with R4 or R5 Xt and Xlib libraries and still run. Source compatibility is necessary but not sufficient for binary compatibility. The major addition requirement of binary compatibility is that fields added to structures must be added to the end of the structure.

In Chapter 6, Inside a Widget, you saw how a class structure for a widget class is built by nesting the class part structures of all its superclasses into one big structure, the class record. The X consortium could not simply add fields to the class part structures of the basic Xt classes without breaking binary compatibility with existing subclasses because the class parts of basic Xt classes appear in the middle of the class record of subclasses. Therefore, they used extension structures to add these fields.

Class extension structures allowed the X consortium to add to the class structures of basic Xt classes. The last field of each basic Xt class is called extension. This field can be set to a pointer to the class's extension structure, which contains its added fields. New features that required additional class structure fields were added to the Composite and Constraint classes in R4. Therefore, these two classes now have extension structures.

Some classes, such as Core, do not have an extension structure because no additional class fields have yet been necessary. They still have the extension field, but it is not used.

A class extension structure is defined in the private header file of a widget class. The extension structure for Composite is called CompositeClassExtensionRec as shown in Example 14-2.

typedef struct {
    XtPointer next_extension;/* 1st 4 mandated for all ext rec */
    XrmQuark record_type;    /* NULLQUARK; on CompositeClassPart */
    long version;            /* must be XtCompositeExtensionVersion */
    Cardinal record_size;    /* sizeof(CompositeClassExtensionRec) */
    Boolean accepts_objects;
} CompositeClassExtensionRec, *CompositeClassExtension;

All extension structures start with the same four fields. The only field in this structure actually used by Composite is accepts_objects, the use of which is described in Section 12.4.5, "The class_part_init Method." The accepts_objects field is only used by Composite widgets that have the code necessary to accept gadget children. When a widget class needs an extension feature, the widget class initializes the extension structure in its .c file, and then in the class_ initialize method sets the extension field to point to the extension structure.

When a widget class does not need an extension feature--for example, a Composite widget that does not accept gadget children--the widget class does not provide code in the class_initialize method to set the extension field.

The .c file of all widget classes should initially set all extension fields to NULL. The difference between classes that use extension features and those that don't is only the presence or absence of code in class_initialize to set the extension fields.

The four required fields in an extension structure are:

When you initialize an extension structure of a given class in the .c file, you always set these four fields to the same values. Example 14-3 shows how to initialize the Composite extension structure. The first two fields are usually NULL and NULLQUARK. The reference page for each class that has an extension structure will document how to initialize the third and fourth fields.

CompositeClassExtensionRec extension_rec = {
    /* next_extension */  NULL,
    /* record_type */     NULLQUARK,
    /* version */         XtCompositeExtensionVersion,
    /* record_size */     sizeof(CompositeClassExtensionRec),
    /* accepts_objects */ True,  /* only new field */
};

The next_extension field implies correctly that you can nest extension structures. Perhaps a later release of Xt will require the addition of more Composite class fields. These could be added to the end of the existing extension structure, or a new extension structure could be defined and a pointer to it placed in next_extension. This allows additions to be made to a class structure without breaking binary compatibility.

You may be wondering whether you should use extension structures when extending your own widgets. Probably not. Because you are likely to release your set of widgets as a package, you have no need for binary compatibility with previous releases (of your own). Binary compatibility would only be an advantage if you wanted to replace a few widgets from a former release and save users who may have subclassed the widgets you have replaced from recompiling their widgets. For the trouble involved, the benefit is very small.

editres is a tool for viewing the structure of X Toolkit applications, finding and setting resources, and dynamically see the results of such settings. editres can help programmers create an app-default file and fallback resources and test custom Xt widgets. This section describes how to add support to Motif applications, and how to use editres as an aid in debugging widgets and applications.

A Tour of editres

The editres application is part of the core distribution in Release 5. This section is a brief tour of the editres resource editor. It will illustrate how to use editres to customize an X Toolkit application. When the user starts editres it looks like Figure 14-1.

Figure 14-1. editres immediately after startup

The editres application contains four areas; The Menu Bar, the Panner, the Message Area, and the Tree Display (which is initially empty). You begin by choosing Get Widget Tree from the Command menu and, following the instructions in the Message Area, select an X Toolkit application by clicking a pointer button. Figure 14-2 shows the result of selecting the xman application. (Note that the application must have support for editres. All applications written using the Athena widget set have that support built in as of R5. Applications written using Motif need to have support added, as shown later.

Figure 14-2. editres with widget tree displayed

The Tree Display now contains the widget hierarchy of xman, displayed graphically. You can now see the name of each widget in the application, and the parent-child relationship of each of these widgets. By using the Tree menu or a keyboard accelerator the user can also see the Class names, Widget ID's, or Window ID's. Figure 14-3 shows the same xman application, but with the Window ID's displayed instead of the widget names.

Figure 14-3. editres display window IDs of widget tree

By selecting “Select Widget in Client” from the Tree menu you can click a pointer button anywhere in the application, and editres will highlight the corresponding widget in the Tree Display. Figure 14-4 shows the result of clicking in the topLabel widget of the xman application. Editres can also do the inverse of this; selecting the “Flash Active Widgets” command from the Tree menu will show you (by flashing widgets in the application) which widgets are currently selected in the Tree Display.

Figure 14-4. Flashing widget in application by selecting it in editres

With these two commands you can easily determine the correspondence between the application itself and the Tree Display representation of it. Because a resource specification is simply a description of the widget's locations in the Tree Display and can be constructed by concatenating the names of the widget and it ancestors, editres can easily construct valid resource specifications that apply to the widgets selected. For example, the fully specified resource name of the topLevel widget is xman.topBox.form.topLabel.

Once you find the widget you want to modify you can select the Show Resource Box command to bring up a dialog box that will allow you to set the resource of that widget. A Resource Box is shown in Figure 14-5, as it would look after changing the topLabel widget's resource to “Testing, Testing.”

Figure 14-5. Resource box for the selected Label widget

At the top of the Resource Box is the resource line currently being edited. This is the actual string that will be inserted into the resource file if you decide to save a change. Below this is an area that allows you to modify the widgets to be affected by this change. This area allows you to substitute class names for instance names, and asterisks for periods in the left hand side of the resource specification. These changes will loosen the binding of the resource specification allowing this one resource line to apply to more and more widgets (see Figure 14-6). Note that no matter how the bindings are modified (by changing periods to asterisks) the original widget will always match the specification.

Figure 14-6. Generalizing the widgets affected by the resource specification

When taken to the extreme, the resource specification can apply to every widget in the application. As you change the bindings of the resource specification, the Tree Display is updated to highlight all the widgets that will be affected by the resource line displayed. When this is combined with the Show Highlighted Widgets command, which flashes the widgets in the application that correspond to those highlighted in the Tree Display, you can quickly determine which widgets will match a given resource specification.

The next area contains a complete list of normal and constraint resources that are available for the originally selected widget. This area is used to select the name of the resource that the user wishes to modify. Foreground, for example, will set the foreground color. Below this area is simply a text field to allow the user to enter the string that will represent the resource value. The resource value that is entered here should be exactly what would be entered into a resource file, thus all new lines should be escaped by a backslash (\) and backslash-n (\n) should be used to add a new line to the resource value.

---

Note: Since editres specifies all resources as strings, it can only set those resources that can be set from resource files. Motif 1.1 and 1.2 do not provide support for certain resources to be set in resource files. One example is the XmNleftWidget resource of the Form widget.)

---

The commands at the bottom of the Resource Box allows the user to select the file the resources will be written into, write the resources to the file, apply the resource immediately to the application, or just popdown the resource box.

Note that applying the resource to the application will not always have the same effect as restarting the application with the resource added to the user's customization file. This is a design constraint of the X Toolkit. Some resources are designed to be read once at startup, and trying to coerce them into a dynamic resource editor is problematic. The basic problem is that the editres support in the application uses XtSetValues() to change the resource of the selected widgets. An XtSetValues() call after startup will override any hard-coded application defaults (but not application defaults specified in files or as fallback resources), whereas the same resource specification in a resource file will not. Therefore, the results of applying a resource setting using editres are only a guide.

Those are the basic features of editres. You can see there is much work to be done, but the basic task of finding and setting resource values is much simpler with this tool. This brief tour should give you an idea of the capabilities of the resource editor, and hopefully stir your imagination a bit. I will next describe the method editres uses to communicate with the applications.

   #include <X11/Xmu/Editres.h>


   XtAddEventHandler(shell, (EventMask) 0, True, _XEditResCheckMessages, NULL);

	% cc <objects> -lwidget set library -lXmu -lXt -lX11 -lXext

In X11R5, Xt was modified to better support internationalization. An internationalized application reads the user's language (called a locale) from the environment or a resource file and operates in that language without changes to its binary. X internationalization is based on the ANSI-C internationalization model. The concepts and implementation of X internationalization are described in the Third Edition of Volume One, Xlib Programming Manual. Xt support of internationalization is trivial in most applications: the only code needed is a call to XtSetLanguageProc() just before the call to XtAppInitialize(). However, if your program directly manipulates text from widgets, or you need to write widgets that accept text input or draws text, you'll need to understand Xlib's internationalization features.

main(argc, argv)
int argc;
char **argv;
{
    Widget toplevel;
    /* register the default language proc */
    /* no app-context, no function, no tag */
    XtSetLanguageProc(NULL, (XtLanguageProc)NULL, NULL);
    /* this function invokes XtDisplayInitialize which
     * will call the language procedure. */
    toplevel = XtAppInitialize(...);
      .
      .
      .

imail -xrm "*xtDefaultFontSet: -*-*-*-R-*-*-*-140-100-100-*-*-*-*"