As discussed in Chapter 2, each entry in the merged database (and in the source databases) is a resource specification/value pair. For application resources, the specification is the application name followed by a period and the resource name. The value to which the resource is to be set follows, after a colon and optional white space.^[62]For example:

xterm.scrollBar:  on

An asterisk can be used as a “wildcard” in place of the application name. For example:

*scrollBar:  on

would set a resource named scrollBar to “on” in any application that recognized a resource of that name.

For widget resources, the specification leading up to the resource name may contain a widget instance or class hierarchy (or a mixed instance/class hierarchy). Some examples are shown below. (Remember that instance names begin with a lowercase letter, while class names begin with an uppercase letter.)

specification                               value
       |                                      |
xbitmap.rowColumn.quit.labelString:          Quit     fully-specified instance hierarchy
XBitmap.RowColumn.PushButton.Foreground:     blue     fully-specified class hierarchy
XBitmap.RowColumn.quit.foreground:           blue     mixed class and instance hierarchy

An instance hierarchy describes the instance names of the widget's ancestors. A class hierarchy describes the class names of the widget's ancestors. This portion of the resource specification may consist of a mixture of instance names and class names (each of which describes one generation in the widget's hierarchy), separated by periods or asterisks.

A tight binding means the left component must be the parent of the right component in the instance hierarchy. A loose binding means the left component must only be an ancestor of the right component; there can be any number of levels in the hierarchy between the two.

Loose bindings are preferable because they stand a better chance of working when the instance hierarchy changes. Tight bindings are rarely necessary at every position in the resource specification, since widget names are usually unique and single widgets can be identified by name. Furthermore, it takes more text to specify the complete instance hierarchy for every widget to be set.

Using loose bindings, the instance, class, or instance/class hierarchy may be abbreviated to the point where specifying the hierarchy as a single asterisk would indicate that any instance or class hierarchy (any widget in the application) will match. However, care should be taken when using loose bindings. One common mistake is to abbreviate a hierarchy too much, so that resource settings that were supposed to apply to only one widget now apply to several. This can be particularly serious (and hard to trace) when the resources being set are translation tables or constraints.

The resource name must be the string that appears in the resource name or resource class field in a resource list. This is the value of the XmN or XmC symbolic constant used in that field of the resource list.

Any entry that is not a resource specification/value pair or does not match any resource for any widget in the application or any application resource is quietly ignored (no warning message is printed). This means that a slight error in the resource specification of an entry will cause that entry to be quietly and completely ignored. It is often difficult to detect such errors.

Lines beginning with an exclamation point (!) are treated as comments. Some people have been using # instead, since it is currently supported in MIT's sample implementation of Xt. But # is not mandated in the Xt specification and therefore may be eliminated in future sample implementations from MIT or in a vendor's implementation. You are advised to use the exclamation point. (Even in the MIT implementation, # elicits warning messages from xrdb.)

R5 (and later) resource databases allow the character ? to be used to wildcard a single component (name or class) in a resource specification. Thus the specification:

xmail.?.?.Background: antique white

sets the background color for all widgets (and only those widgets) that are grandchildren of the top-level shell of the application xmail. And the specification:

xmail.?.?*Background: brick red

sets the background color of the grandchildren of the shell and all of their descendants. It does not set the background color for the child of the top-level shell or for any popup shells. These kinds of specifications simply cannot be done without the ? wildcard; sometimes the * wildcard does not provide the necessary fine-grained control. To set the background of all the grandchildren of an application shell widget without the ? wildcard, it would be necessary to specify the background for each grandchild individually.

There is one obvious restriction on the use of the ? wildcard: it cannot be used as the final component in a resource specification--you can wildcard widget names, but not the resource name itself. Also, remember that the wildcard ? (like the wildcard *) means a different thing in a resource file than it does on a UNIX command line.

The ? wildcard is convenient in cases like those above, but it has more subtle uses that have to do with its precedence with respect to the * wildcard, as discussed later. First, note the important distinctions between the ? and the * wildcards: a ? wildcards a single component name or class and falls between two periods (unless it is the first component in a specification), while the * indicates a “loose binding” (in the terminology of the resource manager) and falls between two component names or classes. A ? does not specify the name or class of a resource component, but does at least specify the existence of a component. The * on the other hand only specifies that zero or more components have been omitted from the resource.

XtAppInitialize() constructs the resource database by consulting the following sources of resource settings, in the order shown in the list below. The effect is that if there is a specification that applies to a particular resource of a particular widget instance in more than one of these locations, and these specifications are of equal precedence, then the first one in this list is the one used (the previous edition of this book presented this list in the reverse order). The unfamiliar topics touched upon in this list are discussed in detail in the following sections.

The list shows the R5 merging of files. This has changed since R4, but the result is the same accept as affected by the new customization resource or by the new screen-dependent resources. All filenames and environment variables are for a POSIX-based system.

The order in which these various sources are loaded, as shown in the list above, is the order of their priority. That is, those that are loaded first override those loaded later if both specifications have the same precedence and affect the same widget or widgets.

If a resource value is hardcoded in the arguments of the call to create a widget, that value takes precedence over any value for that resource in the resource database. If a widget is created and no setting exists in the database for a particular resource, the value pointed to by the default_address field of the resource list in the widget is used. This is also true for application resources and subresources.

Figure 10-1 shows where Xt looks for resource files and in what order, on most UNIX-based systems. The exact directories are operating system and implementation dependent. Remember that the app-defaults file is written by the application writer, and all the rest of the resource sources are for the user. In practice, few users use more than one or two of these sources of resource settings.

Figure 10-1. Typical resource setting search path on UNIX-based systems

The environment variables listed above that describe paths allow a special syntax involving % (the percent symbol) to substitute various elements into the path.

For example, the XFILESEARCHPATH environment variable is a colon separated path. Under Sun OpenWindows, the openwin script appends the string “/usr/openwin/lib/%T/%N%S” to the XFILESEARCHPATH variable. The effect is that app-defaults files are found in the directory /usr/openwin/lib/app-defaults.

XtDisplayInitialize() reads the environment variables, makes the % syntaxes into paths with XtResolvePathname(), and uses XtFindFile() to actually find the files. %T becomes the type arg of XtResolvePathname(), %S becomes the suffix arg, and %N is the filename arg. Type is a category of files, such as app-defaults, help or bitmap. Suffix is file suffix such as .txt. So in your example, %T is app-defaults, and %N%S is the complete filename.

This syntax can get much more complicated when it includes %l, %L, %t, and %c, all of which have to do with internationalization, and %C, which is for specifying different files for different types of displays (usually color and mono), as described in Section 10.2.11, "Customized Resource Files."

The Xrm functions that read resources from files, XrmGetFileDatabase() and XrmCombineFileDatabase() (the latter new in R5), recognize a line of the form:

#include "filename"

as a command to include the named file at that point. The directory of the included file is interpreted relative to the directory of the file in which the include statement occurred. Included files may themselves contain #include directives, and there is no specified limit to the depth of this nesting. Note that the C syntax #include <filename> is not supported; neither Xlib nor Xt defines a search path for included files.

The ability to include files is useful when producing a special app-defaults file for use on a color screen, for example, you can simply include the monochrome app-defaults file and then set or override the color resources as you desire. This technique is particularly useful when producing app-defaults files for use with the customization resource described below. Example 10-2 shows a hypothetical color resource file for the “xmail” application.

! include the basic (monochrome) defaults
#include "XMail"
! and augment them with color
*Background: tan
*Foreground: navy blue
*Command*Foreground: red
*to*Background: grey
*subject*Background: grey

Do not confuse this file inclusion syntax with the #include, #ifdef, etc. syntax provided by the program xrdb. That program invokes the C preprocessor to provide C include, macro, and conditional processing. The include functionality described here is provided directly by Xlib.

Xt's resource handling is designed to support resource files in different languages. The goal is to have all the language dependencies of an application in files, so that just by selecting a different set of resource files and localization files at run time, the application will operate correctly in another language.^[63]

The language to use is selected with a language string, which is an application resource defined by Xt: “xnlLanguage” (no symbol XmNxnlLanguage is defined for it). The default language string is NULL, which makes Xt operate in English, with all files in the locations used prior to when the internationalization features were added. But when the *xnlLanguage resource, or the LANG environment variable, is set to a language name such as “spanish,” Xt looks first in certain directories for the Spanish app-defaults and user defaults files, before defaulting to the normal app-defaults or user defaults directories.

Note that all app-defaults and user defaults files have the same name (the class name of the application); only the directory in which they are first examined for changes according to the language string. Therefore it is possible to have all the files for all the languages installed on a system at the same time.

The search path for resource files is implementation dependent, but it is always begins with a language string-based directory. Each app-defaults file on UNIX-based systems is normally in a directory /usr/lib/X11/$LANG/app-defaults. When the user sets LANG to “spanish,” for example, Xt looks for an app-defaults file first in /usr/lib/X11/spanish/app-defaults.

The path searched for user defaults files (which have the same name as the app-defaults file) is more complicated. If the XUSERFILESEARCHPATH environment variable is defined, Xt follows that path. If it is not defined but the XAPPLRESDIR environment variable is defined, Xt will look in $XAPPLRESDIR/LANG first before looking in $XAPPLRESDIR. If XAPPLRESDIR is not defined either, Xt looks in $HOME/LANG and then $HOME.

The remaining resource setting sources are not affected by the language string. As described in the previous section, the next source of resource settings merged is the RESOURCE_ MANAGER property set with xrdb, or if not set, .Xdefaults, followed by the file specified by the XENVIRONMENT environment variable, or if not set, the .Xdefaults-host file.

For a summary of the path of resource files searched by Xt, see Figure 10-1.

Most western languages other than English use characters with accents or other marks. These are non-ASCII characters, in the second half of the ISO Latin-1 character set. Most fonts now in the X distribution provide glyphs (bitmaps) for these characters. Therefore, all you have to do is specify these characters in your app-defaults file in the directory named for the desired language. However, most standard English keyboards do not provide a way to type non-ASCII characters (and some computers can't store them). Because of this, the resource file format has been augmented to provide a special syntax for specifying non-ASCII characters. Each character is specified using a backslash followed by a three-character octal number that represents the character. You can use xfd to determine the proper octal number to use. Just click on the desired character to have its index displayed. This index is the number you enter in the app-defaults file. For example, Example 10-3 shows a Spanish app- defaults for xhello.

*hello.fontList:      *courier-bold*18*iso8859-1
*hello.labelString:   \161Hola, Mundo!

The sequence \161 produces the inverted exclamation point that begins the Spanish exclamatory sentence. It is important to know for sure that the font you choose has the desired glyphs. Note that iso8859-1 means ISO Latin-1, so that if you specify it in your font name, you are guaranteed to have all ISO-Latin-1 characters. Many of the fonts in the misc directory (such as the standard terminal fonts) do not include these characters. Also note that strings such as \161 may not work on systems that can only handle seven bit (ASCII) characters (they ignore the eighth bit).

The (pre-R5) function, XResourceManagerString(), returns the contents of the RESOURCE_MANAGER property on the root window of the default screen of the display. This property contains the user's resource customizations in string form, and is usually set with the program xrdb. It is read by XtDisplayInitialize() when creating the resource database to be used by an application. Until R5 this single RESOURCE_MANAGER property contained resources for all screens of a display, and there was no way for a user to specify different resources for different screens (for example, color vs. monochrome).

In R5, xrdb can set resources in the SCREEN_RESOURCES property on the root window of each screen of a display. XtDisplayInitialize() reads the SCREEN_RESOURCES specifications and uses them to override the screen-independent RESOURCE_MANAGER specifications. The resource database that is created in this way is the database of the screen, rather than the database of the display. If the same application is executed on different screens of a display, or if a single application creates shell widgets on more than one screen of a display, a resource database will be created for each screen, and the application instances or shell widgets will find resources in them that are appropriate for that screen.

Recall that XtDisplayInitialize() creates databases using resources from a number of sources other than these window properties, so in many cases resource databases on different screens will contain substantially the same values. Note, however, that the SCREEN_RESOURCES property can be used to set the customization resource and thereby cause different app-defaults files to be merged into different screen databases. Screen-specific resource databases are created by Xt only as needed, so an application running exclusively on the default screen of a two-screen system will not have the overhead of maintaining two per-screen databases.

Two new functions support screen-dependent resources and resource databases. The contents of the SCREEN_RESOURCES property on the root window of a screen are returned by the function XScreenResourceString(). The database of a screen may be obtained with the function XtScreenDatabase(). The function XtDatabase(), which prior to R5 returned the (single) database of the display, is now specified to return the database of the default screen of the display.

The client xrdb has been rewritten for R5 to handle the new screen-specific properties. Any load, merge, or query operation can now be performed on the global RESOURCE_MANAGER property, a specific screen property, all screen properties, or all screen properties plus the global property. This last option is the default and “does the right thing"--the input file is processed through the C preprocessor once for each screen, and resource specifications that would appear in all of the per-screen properties are placed in the global property and removed from the screen-specific properties. With this new system, a defaults file which uses #ifdef COLOR to separate color from monochrome resource specifications can be used to correctly set the values of the screen-dependent and screen-independent properties for a two-screen monochrome-and-color display. An application can then be run on either screen and find the correct user defaults for that screen. Example 10-4 shows a user default file that takes advantage of the new xrdb functionality and the customization resource to set different defaults on color and monochrome screens.

! generic, non-color resources
*Font: -*-courier-medium-r-*-*-*-180-75-75-*-*-iso8859-1
xclock.geometry: -0+0
#ifdef COLOR
! resources for color screens here
*Background: grey
*Foreground: navy blue
XTerm*Foreground: maroon
#else
! resources for monochrome screens here
XTerm*reverseVideo: true
#endif
! set the customization resource to get
! special app-defaults, if they exist.
#ifdef COLOR
*customization: -color
#else
*customization: -mono
#endif

When an Xt application creates a shell widget with XtAppCreateShell(), the value of the XtNscreen resource is used to determine what screen the shell should be created on and which screen's resource database should be used to look up the widget's resources. But the value of the XtNscreen resource must be looked up itself. The Xt specification resolves this circular problem by stating that the value of the XtNscreen resource is looked up first in the argument list passed to XtAppCreateShell(), and then in the resource database of the default screen of the display. If it is found, then all further resources are looked up in the resource database for that particular screen. If the XtNscreen is not found, then the widget is created on the default screen, using the database for that screen.

As you may recall from Chapters 2, 3, and 4, XtAppInitialize() has an argument in which you can specify fallback resources, which we didn't use. Many applications won't operate properly without their app-defaults file. Fallback resources are a defense in case the user doesn't install the app-defaults file, or if something happens to prevent access to it. They provide minimal application-specific resource settings that either allow the application to run safely or instruct the user to install the app-defaults file properly.

If your app-defaults file is small, you can (and should) put the whole app-defaults file in the fallback resources. However, if your app-defaults is large, it probably makes more sense just to set one or more labels in the application to tell the user that the app-defaults file is not installed properly or cannot be accessed. Remember that the fallback resources are used only if the app-defaults file is not found. Fallback resources are a NULL-terminated list of strings, each containing a resource setting. Example 10-5 shows how they are declared and then passed to XtVaAppInitialize().

main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, hello;
    static String fallback_resources[] = {
        "*hello.labelString: App-defaults file not installed or not\
             accessible.",
        "*hello.fontList: *courier-bold*18*iso8859-1",
        NULL,         /* Must be NULL terminated */
    };
	XtSetLanguageProc(NULL, (XtLanguageProc)NULL, NULL);
    topLevel = XtVaAppInitialize(
            &app_context,        /* Application context */
            "NoFile",            /* Application class */
            NULL, 0,             /* command-line option list */
            &argc, argv,         /* command line args */
            fallback_resources,  /* for missing app-defaults file */
            NULL);               /* terminate varargs list */
    .
    .
}

Note that there is also a separate function, XtAppSetFallbackResources(), that can be used to set the fallback resources separately from the XtAppInitialize() call.

When a widget is created, its expanded instance hierarchy and class hierarchy together with its resource names and classes are compared to each entry in the merged resource database. To demonstrate how matches are made, we'll look at a sample widget hierarchy and follow the process of finding the value for one resource of one widget from the merged resource database. Figure 10-2 shows the widget instance hierarchy for the quit widget in the xrowcolumn application shown in Chapter 3, More Techniques for Using Widgets. The figure also shows the corresponding fully specified instance and class names for the quit widget. This section describes how this widget's resources are set by the resource manager.^[64]

Figure 10-2. The quit widget in a sample widget hierarchy

We know that quit is a Command class widget and therefore that Xt will be searching the resource database for each resource in Command's resource list (and the resources in its superclasses' resource lists). It will search for one resource at a time. To demonstrate the conflicts that can occur, we'll use the Core resource XmNbackground, which is common to all widgets. It will appear in the resource database as background.

The matching process can be thought of as a process of elimination. Let's assume the merged resource database is as shown in Example 10-6.

*rowColumn.background:                blue             (entry 1)
*background:                          red              (entry 2)
*quit.background:                     green            (entry 3)
*quit.labelString:                    Quit             (entry 4)
*XmPushButton.background:             yellow           (entry 5)
*XmRowColumn.XmPushButton.background: violet           (entry 6)
*rowColumn*background:                pink             (entry 7)
xrowcolumn.background:                orange           (entry 8)
*?.background:                        purple           (entry 9)

Only resource database entries that specify background as the last element before the colon are possible matches. That eliminates entry 4. The fully specified instance and class hierarchies are then compared with each possible match, beginning with the first component in each hierarchy.

Because of the way merging works, no two resource specifications in the merged resource database will be alike. (Remember that we are using the term specification for the part of the resource setting up to and including the colon.) For example, the merged database could never contain both of the following:

XBitmap*rowColumn*background: green
XBitmap*rowColumn*background: red

because the merging process would remove the setting that appeared earlier in the list of database sources (or that appeared later in a single file).

However, the database could contain two or more resource settings that apply to the same resource of the same widget, because of differences in the widget class or instance hierarchy or the bindings. For example, the database could contain:

XBitmap*rowColumn*background: green
XBitmap*quit.background: red

If the quit button is a child of rowColumn, both settings apply to the quit button's background.

The resource manager provides a set of rules that govern which setting takes precedence in cases where there are two settings for the same resource of the same widget. Here are the three rules:

Situations where both rule 2 and rule 3 apply often cause confusion. In these cases, remember that rule 2 takes precedence since it occurs earlier in the list above. Here is an example:

*box*background:                   takes precedence over
*box.Background:

To understand the application of these rules, let's return to our extended example. In the course of developing that example, we eliminated information about the level at which components occurred. However, the actual process of matching applies the precedence rules at each step. As a result, let's start again with the original appearance of the entries that pass the matching test. The remaining five as they appeared originally are shown in Example 10-9.

*background:                          red            (entry 2)
*quit.background:                     green          (entry 3)
*XmPushButton.background:             yellow         (entry 5)
*XmRowColumn.XmPushButton.background: violet         (entry 6)
*rowColumn*background:                pink           (entry 7)

From here on, we will determine not only which one of these five will take effect, but the actual precedence of the five. In other words, once the one with highest precedence is determined, we'll see which would take effect if that one was commented out, and so on.

The precedence rules are applied in order to determine the order of the finalist entries.

Therefore, the final precedence is as shown here:

1.    *rowColumn*background:                pink    (entry 7)
2.    *XmRowColumn.XmPushButton.background: violet  (entry 6)
3.    *quit.background:                     green   (entry 3)
4.    *XmPushButton.background:             yellow  (entry 5)
5.    *background:                          red     (entry 2)

People get used to the fact that they can set the resources of all the children of rowColumn with something like entry 7, but then are shocked to find that nothing happens when they attempt to override entry 7 with entry 3--entry 3 seems more specific to them. Even the following entry (using a class name) takes precedence over entry 3 because the rule about being higher in the widget hierarchy carries more weight than the rule that instance names take precedence over class names:

*XmRowColumn*background:    pink        (entry 7)

Finally, a note about creating app-defaults files. Consider what happens when users specify a line like *Background: grey in their personal resource files. They would like to set the background of all widgets in all applications to grey, but if the app-defaults file for the application “xmail” has a specification of the form *Dialog*Background: peach, the background of the dialog boxes in the xmail application will be peach-colored, because this second specification is more specific. So if they really don't like those peach dialog boxes, (pre-R5) users will have to add a line like XMail*Background: grey to their personal resource files, and will have to add similar lines for any other applications that specify colors like “xmail” does. The reason this line works is rule 1 above: at the first level of the resource specification, “XMail” is a closer match than *.

This brings us to the specific reason that the ? wildcard was introduced in R5: any resource specification that “specifies” an application name with a ? takes precedence over a specification that omits the application name with a *, no matter how specific the rest of that specification is. So in R5, the frustrated users mentioned above could add the single line:

?*Background: grey

to their personal resource files and achieve the desired result. The sequence ?* is odd-looking, but correct. The ? replaces a component name, and the * is resource binding, like a dot (.).

The solution described above relies, of course, on the assumption that no app-defaults files will specify an application name in a more specific way than the user's ?. If the “xmail” app-defaults file contained one of the following lines:

xmail*Dialog*Background: peach
XMail*Background: maroon

then the user would be forced to explicitly override them, and the ? wildcard would not help. To allow for easy customization, programmers should write app-defaults files that do not use the name or class of the application, except in certain critical resources that the user should not be able to trivially or accidentally override. The standard R5 clients have app-defaults files written in this way.

The moral of this story is that you should choose the bindings in your resource file to reflect how easy (or difficult) you want to make it for users to override your specifications. (But of course, even a specification containing only tight bindings can still be overridden by a user specification that also includes all tight bindings.)

Be careful with tight bindings, however. Since there are no messages telling you which resource specifications are actually being used, you can be tricked into thinking that you have set resources that you actually haven't.

Figure 10-3. Steps in matching resource entries for one resource of widget being created

A useful tool for figuring out the priority of resource files is the appres utility. You specify the class name of the application on the command line, and appres shows you what resource settings that application will see when run. Note, however, that this does not tell you how these resource settings will actually apply to the widgets in the application, since appres has no knowledge of the widget instance hierarchy in your application.

Another tactic in tracing resource settings is to build a routine into your application that gets and prints all the critical resources of a widget. Using XtGetResourceList() you can get the list of resources supported by a widget class. Then you can query each of those resources and print most of them out. Remember that certain resources are compiled into internal forms, so you can't print out translation tables, accelerator tables, or callback lists. It may also be difficult to interpret other values, since many of them will have already been converted from the string form in the resource file into the most convenient internal form. For example, colors will have been changed from strings such as “red” into a pixel value (a number which could change each time the application is run).

In X11R4, it was possible to install an application with multiple app-defaults files so that users could use the xnlLanguage resource to specify what language the application should display itself in. But it was not possible to install one app-defaults file for use on monochrome screens and another for use on color screens and allow the user to specify, through a resource, which file was to be used. Applications are moved between color and monochrome environments far more often than they are ported to other languages, and in X11R5 the X Toolkit allows a user to easily specify which resources should be used.

You may recall that XtResolvePathname() searches for a file by performing printf-type string substitutions on a specified or default directory path. The string “%L” is replaced with the language string (the value of the xnlLanguage resource), for example, and the string “%T” is replaced with the type of the file--"app-defaults,” “bitmap,” “help,” etc. In X11R5, XtResolvePathname() supports a new substitution variable “%C,” which is replaced with the value of the application resource named customization and of class Customization. It is intended that the default or user-provided XFILESEARCHPATH will contain filename path components of the form %N%C%S--name, customization, suffix. Then a system administrator could install app-defaults files (which do not have suffixes) like XMail-color and XMail-mono and a user could run the xmail application as follows:

xmail -xrm "*customization: -color" &

in order to get the app-defaults file with color defaults. (Unfortunately, X11R5 Xt does not define a standard -customization command-line option to set the value of this resource.) The system administrator would also have to install an uncustomized app-defaults file, XMail, for use when no customization is set. This file could be a symbolic link to the monochrome file, or it could be a base resource file that contains all the resources except those that affect color. Then the customized files could simply include the base file with the new #include feature. The hyphen in the customization name (-color) is not part of the Xt specification; it is simply a useful convention that makes for legible customized resource filenames (like XMail-color).

The customization resource was designed primarily to allow color customizations, but there are other possibilities as well: app-defaults files with customized translations that work with a single-button mouse might be installed with a -single-button customization, or files customized for use within a specific group or department of an organization could be selected by department name. Note, however, that because there is no way to specify multiple customizations with the single customization resource, (e.g., users couldn't specify that they wanted both color resources and single button translations) this technique should not be overused. In general, it should be reserved for the color vs. monochrome customization for which it was designed.

A related change in X11R5 is to the Xt specification of the default paths to be used when the environment variables, XFILESEARCHPATH and XUSERFILESEARCHPATH (on UNIX systems), are not defined. In X11R4, these paths were required to contain specific directories in a specific order. The individual directories in X11R4 had a fixed substitution order: language (optionally), type, name, and suffix. This order meant that an application's auxiliary files (app-default, bitmaps, help text, etc.) had to be installed in scattered locations throughout a file system. In X11R5, the default paths still have a required number of entries in a specified order, but the order in which substitutions appear in these path entries is no longer specified. This means that vendors may choose default paths for their implementations that allow auxiliary files to be installed in a single directory. The MIT implementation retains the substitution order of X11R4, except for the insertion of the “%C” customization substitution between the name and suffix substitutions. When using a vendor-supplied X11R5, be sure to check your documentation for the default file search path. When writing a Makefile or Imakefile to distribute with an application, bear in mind that app-defaults files, bitmap files, help files, and so on may not be installed in the “usual” places on all systems.

Until R5, there was an annoying problem with specifying translation tables as resources. Because a translation table is a multi-line resource, it is useful to be able to override or add individual lines to the table rather than always replace the table. Application developers often do this in their application's app-defaults file, using the #override or #augment directive as part of the XtNtranslations resource value. Sometimes, though, users would also like to add or override individual translations, but if they specify a value for the XtNtranslations resource in a personal resource file, it will take precedence over the resource in the application's app-defaults file, and the application's customizations will be lost from the database before the widget ever sees them. So until R5, users had to duplicate the application's translation settings in its app-defaults file and then modify their copy.

In R5, there is a new resource, XtNbaseTranslations, that can be used by an application developer to specify a base set of translations that will be correctly overridden, augmented, or replaced by the value of the XtNtranslations resource. Note that this is an Xrm resource, but is not a widget resource in the usual Xt sense of the word (the Xt specification uses the term “pseudo-resource”)--it does not correspond to an instance field in Core or any other widget class, and it cannot be set with XtSetValues() or queried with XtGetValues(). The value of the translations field of the Core widget is handled specially by the Xt resource management code. The final value for a widget's translations are obtained as follows:

For maximum flexibility to the user, all R5 applications should specify translations in a resource file using the XtNbaseTranslations resource rather than with XtNtranslations. If the same resource file is to be used by applications compiled under both the R5 and R4 versions of the Intrinsics, then the resource file should specify the application's translations as the value of both resources. Under R4, the XtNbaseTranslations resource will be ignored, and under R5, any value of the XtNtranslations resource specified by the user will override the value specified in the application's app-defaults file.

The primary purpose of converters is to allow resource files to contain string values for nonstring program variables. (They are also used internally to convert default values that cannot be specified easily in the desired data type.) Secondly, converters confine the details of data conversion to a single routine that is registered with Xt. This is a big benefit because users of the converted types need not know the details of how the conversion takes place, or the internal definition of the target type.

Xt provides converters from XmRString to the representation types listed in Table 10-2. You can use these representation types as target types in resource lists in applications or widgets, without having to register them, if you want the user to be able to specify the resource in a resource file. Note that if you are using standard Xt, the various representation types begin with XtR rather than XmR.

If there is no converter from XmRString to a particular resource type, it may not be possible to specify that resource type in a resource file. For example, there is no converter for XmRCallback since it would be meaningless to specify a function in a resource file. The only ways to set a callback resource are with XtAddCallback() or a static callback list declared in the application.

Most of the Xt converters allow the resources of the base classes Core, Composite, Constraint, and Shell to be set from resource files. Motif provides numerous converters that allow the resources of its widgets to be set from resource files. However, not all Motif widget resources can be set from resource files, because the needed converters are not provided. (As of Motif 1.2, Motif now includes a StringToWidget converter, which allows Form and other constraint resources to be set from resource files.) Motif provides converters from XmRString to Widget, Window, Char, XmFontList, XmString, KeySym, HorizontalPosition, HorizontalDimension, VerticalPosition, VerticalDimension, BooleanDimension, CharSetTable, KeySymTable, ButtonType, XmStringTable, StringTable, AtomList, and Cardinal.

In addition, the Xmu library contains several useful converters. For example, Xmu provides a converter that converts from a filename (string) to a bitmap suitable for use as an icon pixmap. Even though Xmu (like Xaw) is not part of the X Consortium standard, it is part of MIT's core distribution and is available on most systems. However, because the Xmu converters are not built into Xt, you need to register them with a call to XtSetTypeConverter() or XtAddConverter() (from widget code) or XtAppSetTypeConverter() or XtAppAddConverter() (from application code) before using them in an application or widget. (We'll describe the converters and show how to register them in Section 10.3.4, "Registering Type Converters.")

While the conversions from XmRString are the most widely used, since they allow a resource to be specified from a resource file, there are also a number of built-in converters between other data types, for use internally within Toolkit programs.

Most commonly, these converters are used to convert between the resource_type and default_type fields of a resource definition.

Table 10-3 lists those converters automatically recognized by Xt.

For example, the default value of the Core resource XmNborderPixmap is set as shown in Example 10-10.

static XtResource resources[] = {
    .
    .
    .
     {
    XmNborderPixmap,
    XmCPixmap,
    XmRPixmap,
    sizeof(Pixmap),
    XtOffsetOf(CoreRec, core.border_pixmap),
    XtRImmediate,
    (XtPointer) XtUnspecifiedPixmap
     },
    .
    .
    .
}

(Note that the code for the base classes defined by Xt use constants beginning with Xt, not Xm. However, the value of each of these constants is the same in both versions.)

The specified default value XtUnspecifiedPixmap is an integer defined to have a value that does not equal the constant CopyFromParent or any valid Pixmap ID. The initialize method for the Core widget class checks for this value, and does not set the background window attribute unless the application or a resource file has set the XmNborderPixmap resource to some value other than the default.

There are two special values, XmRImmediate and XmRCallProc that can be used only in the default_type field of a resource definition. These values require no type conversion. The value provided in the default_address field must be of the correct type.

The type XmRImmediate means that the value in the default_address field is the default value itself, not its address. For a string, this means that the default_address field is a pointer to the string, not a pointer to a pointer.

In Example 10-11, the value in the default_address field of the XmNheight resource definition is the actual default--in this case, zero.

static XtResource resources[] = {
    .
    .
    .
     {
    XmNheight,
    XmCHeight,
    XmRDimension,
    sizeof(Dimension),
    XmOffsetOf(RectObjRec, rectangle.height),
    XmRImmediate,
    (XtPointer) 0
     },
    .
    .
    .
};

The type XmRCallProc means that the value in the default_address field is a pointer to a function. This function is of type XtResourceDefaultProc,^[65] and it is expected to retrieve the desired default value at run time. When the widget instance is created, the function is automatically invoked with these parameters: the widget ID, the resource offset, and a pointer to the XrmValve in which to store the result. The function should fill in the addr field of the XrmValue with a pointer to the default data in its correct type.

In Example 10-12, the value in the default_address field of the XmNscreen resource definition is the name of a function that retrieves the screen on which the widget is displayed.

static XtResource resources[] = {
    .
    .
     {
    XmNscreen,
    XmCScreen,
    XmRPointer,
    sizeof(int),
    XtOffsetOf(CoreRec, core.screen),
    XmRCallProc,
    (XtPointer) XtCopyScreen
     },
    .
    .
};

Example 10-13 shows an example of an XtResourceDefaultProc.

/*ARGSUSED*/
void XtCopyScreen(widget, offset, value)
     Widget        widget;
     int           offset;
     XrmValue     *value;
{
     value->addr = (XtPointer)(&widget->core.screen);
}

As noted earlier, not every representation type symbol defined in Xm.h is supported by a built-in converter, though Motif and the Xmu library do provide some of the most important converters that are missing in Xt. In addition, you can define your own resource types, and write converter routines to convert from a string representation in a resource file to the appropriate data type. (You can write converters from any type to any other type, but converters from String are by far the most useful.)

Table 10-4 lists the converters from XmRString provided by the Xmu library.

Whether defined in Xmu or in your own program, a converter other than those built into Xt or Motif must be registered with a call to XtAddConverter() or XtSetTypeConverter() before a resource list is used that references the converted types. Resource lists are used when widgets are created or when the application calls XtGetApplicationResources(). In the application, a converter must be registered after XtAppInitialize() but before XtGetApplicationResources().

Within a widget, the class_initialize method is the standard place to register type converters. This method is responsible for doing processing that should be done only once when the first instance of a particular class is created.

Example 10-14 shows the code needed to register the XmuCvtStringToJustify converter in a widget. As noted above, this converter would be used for a resource (such as the Athena Label widget's XtNjustify resource) designed to give the user the option of justifying text (or a graphic object) to the right, left, or center of a widget.^[66]

static void
ClassInitialize()
{
        .
        .
        .
     XtSetTypeConverter(XmRString,   /* source type */
             XmRJustify,             /* target type */
             XmuCvtStringToJustify,  /* converter routine */
             (XtConvertArgList) NULL,
             /* args for converter routine */
             0                       /*# args for converter routine */
             XtCacheAll,             /*  caching instructions */
             NULL);                  /*  destructor function */
}

Note that XtSetTypeConverter() was added to Xt in R4. Its predecessor, XtAppAddConverter(), is still available and can still be used, but has reduced functionality. XtAppAddConverter() cannot be used for conversions that require a server query (such as those involving colors or fonts), and does not provide the caching control provided by XtSetTypeConverter(). Note that the explicit application context version of the call (XtAppSetTypeConverter()) is not used in this case, because the class_initialize method does not pass in a widget from which the application context could be determined.

The first two arguments of XtSetTypeConverter() are the source and target type, respectively, specified using XmR symbolic constants defined in <Xm/Xm.h> (or defined in an application header file or the widget public header file if the type is not standard in Xt).

The third argument is the name of the converter routine, which by convention contains the string Cvt. The Xmu converters all add the prefix Xmu.

The fourth and fifth arguments of XtSetTypeConverter() are an argument list that will be passed to the converter routine when it is called. Some converter routines require information about the context in which the converter is called. This is usually passed in via an XtConvertArgRec structure, as described in the next section. If no arguments are needed, the fourth and fifth arguments of XtSetTypeConverter() can be NULL and 0 respectively.

The sixth argument specifies whether the results of the conversion should be cached. The basic symbols are XtCacheNone, XtCacheAll, and XtCacheByDisplay. Expensive conversions should be cached. Xt caches resource values to avoid repetitive conversions of the same value, which are common in an application made up of many identical widgets. It is especially important to cache conversions that require round-trips to the server, such as color, font, and atom conversions. But it is wasteful of memory to cache silly conversions such as XtCvtStringToGeometry, which actually doesn't do any conversion or even validity checking. (The XmRGeometry representation type is a geometry string, as defined by XParseGeometry(). It takes no conversion to convert XtRString to XtRGeometry. The converter could at least test the string to make sure it looks like a geometry string.) Another benefit of caching is that Xt remembers unsuccessful conversions and efficiently generates warning messages without attempting any conversion more than once.

The symbol XtCacheRefCount can be ORed with any of the above values, in which case Xt keeps track of how many widgets still exist that used a converted value, and frees the cached value when the count reaches zero. The application, if it uses the converted value in a call to XtGetApplicationResources(), is also counted as one reference. Reference counting is needed only if an application destroys widgets whose resource values may take up extensive space. Because reference counting takes up space and requires time, it should not be done unless necessary. To control reference counting on a widget-by-widget basis, an application must explicitly set the XmNinitialResourcesPersistent resource to False for each widget whose conversions are to be reference counted. These should be widgets that might be destroyed before the application exits.

The seventh argument of XtSetTypeConverter() is a pointer to a procedure called a destructor. If the reference count for a particular resource reaches zero, Xt calls the destructor function, and removes the resource value from the conversion cache. The destructor will also be called when XtCloseDisplay() is called if the converter was registered with XtCachePerDisplay. Before calling XtCallConverter() or XtConvertAndStore() to convert a value, the client must allocate memory in which to place the result. The job of the destructor is to deallocate this memory. If you are allowing Xt to convert data automatically, by declaring a resource list, Xt allocates the memory, and you don't need a destructor (so specify NULL). If you plan to call XtCallConverter() from an application, and you allocate memory statically for the converted value, you don't need a destructor function and can specify NULL for this argument. A destructor is needed only if you allocate memory dynamically for an explicit call to XtCallConverter(). (Remember that reference counting happens only if the converter is registered with XtCacheRefCount set and XmNinitialResourcesPersistent set to False for at least one widget. If these conditions are not met, the destructor is only called when XtCloseDisplay() is called and if registered with XtCachePerDisplay.)

Xt provides several functions for manipulating reference counts, which are rather obscure and mentioned here only for completeness. XtAppReleaseCacheRefs() explicitly decrements the reference counts for resource values converted with XtCallConverter(). This would be used in the rare occasion where a value has been cached but you don't want it cached. If this is the last reference to the conversion, the registered destructor is called. Xt also defines two built-in callback functions that decrement reference counts, XtCallbackReleaseCacheRef() and XtCallbackReleaseCacheRefList().

static void ClassInitialize(w)
Widget w;
{
     static XtConvertArgRec parentCvtArgs[] = {
          {
               XtWidgetBaseOffset,
               (XtPointer)XtOffsetOf(CoreRec, core.parent),
               sizeof(CoreWidget)
          }
     };
          .
          .
          .
     XtSetTypeConverter(XtRString,
             XtRWidget,
             XmuCvtStringToWidget,
             parentCvtArgs,
             XtNumber(parentCvtArgs),
             XtCacheAll,
             NULL);
}

typedef struct {
    XtAddressMode address_mode;
    XtPointer address_id;
    Cardinal size;
} XtConvertArgRec, *XtConvertArgList;

typedef enum {
          /* address mode parameter representation */
         XtAddress,             /* address */
         XtBaseOffset,          /* offset */
         XtImmediate,           /* constant */
         XtResourceString,      /* resource name string */
         XtResourceQuark,       /* resource name quark */
         XtWidgetBaseOffset,    /* offset */
         XtProcedureArg         /* procedure to call */
} XtAddressMode;

Converters are normally invoked by Xt because the types they convert are specified in a resource list. But this is not the only way in which converters can be invoked. It is possible to manually invoke type converters, the easiest way being XtConvertAndStore().^[68] This may be useful in an application, such as for reading an icon pixmap from a file using a converter, or you may need to explicitly invoke a converter from within a converter you want to write. (Converter routines can themselves invoke other converters directly.)

One possible manual use of type converter routines is in the processing of the string parameters passed to action routines. Perhaps in the action routine itself it is more convenient to have some parameters converted to another form. For example, if an action is passed the string “True,” the action code might prefer to convert this parameter to a Boolean value. The CvtStringToBoolean converter understands many strings that would be interpreted as Boolean, such as “Off,” “On,” “True,” “False,” “No,” and “Yes,” in upper, lower, or mixed case. It saves code to use the converter rather than comparing a string to all these strings in your own code. Example 10-16 shows an action routine of the Athena Text widget (modified for R4) in which a converter is manually invoked.

static void
DisplayCaret(w, event, params, num_params)
Widget w;
XEvent *event;             /* CrossingNotify special-cased */
String *params;            /* Off, False, No, On, True, Yes, etc. */
Cardinal *num_params;      /* 0, 1 or 2 */
{
      .
      .
      .
    if (*num_params > 0) { /* default arg is "True" */
        XrmValue from, to;
        from.size = strlen(from.addr = params[0]);
        if (XtConvertAndStore(w, XtRString, &from, XtRBoolean, &to)
                == False)
            XtAppError(XtWidgetToApplicationContext(w),
                    "DisplayCaret action: String to Boolean\
                    conversion failed");
        else {
            ; /*
               *      (*(Boolean*)to.addr) has boolean value;
               *              do something with it here */
               */
        }
    }
}

Note that the from and to arguments of XtConvertAndStore() are pointers to structures containing length/pointer pairs--they are not values. The actual data is passed as a pointer to a pointer. Thus the cast to Boolean (in the comment) must dereference the pointer twice.

The widget argument of XtConvertAndStore() is used internally by Xt as the argument for the XtDisplay() macro, to get the pointer to the display structure, and for other purposes. In normal applications you can pass any widget here. (For some converters, the widget may need to be realized.)

XtConvertAndStore() calls a lower-level routine called XtCallConverter().^[69]If you prefer, you can use this routine. Instead of passing it the widget and the source and destination type, you pass it a display, the name of the conversion routine, any arguments to the routine, and storage in which to place the cache reference count. See Volume Five, X Toolkit Intrinsics Reference Manual, for details.

If your application or widget has a data type that you would like the user to be able to set through resource files, and no Xt or Xmu converter exists, you will need to write (and register) a type converter from XtRString to your type. The first step in creating a converter is to decide upon the characteristics of the string you will be converting from, and the C-Language type you will be converting to. Then you can copy an existing similar converter and fill in the code to convert to your desired type. Note that the R5 Athena widgets still use a mixture of the old-style (R3) and new-style converter interfaces. To use the current converter functions XtConvertAndStore() or XtCallConverter(), or any of the cache reference counting features, you must define your converter using the type XtTypeConverter. The difference between new-style and old-style type converters is just that new-style type converters have a display as their first argument, and they must do a display-specific conversion when a server query is involved. The new-style converters also must return TRUE or FALSE to indicate whether the conversion succeeded. Example 10-17 shows an Xmu converter that shows the essential elements of a converter. It has been modified to be compatible with the new-style resource conversion routines such as XtSetTypeConverter(). (The only difference is the presence of a leading Display argument and the return value.)

#define done(address, type) \
        { (*toVal).size = sizeof(type); \
          (*toVal).addr = (XtPointer) address; }
Boolean XmuCvtStringToLong (display, args, num_args, fromVal, toVal)
    Display display;
    XrmValuePtr args;
    Cardinal    *num_args;
    XrmValuePtr fromVal;
    XrmValuePtr toVal;
{
    static long l;
    if (*num_args != 0)
        XtWarningMsg("wrongParameters","cvtStringToLong",
                "XtToolkitError","String to Long\
                conversion needs no extra arguments",
                (String *) NULL, (Cardinal *)NULL);
    if (sscanf((char *)fromVal->addr, "%ld", &l) == 1) {
        done(&l, long);
        return(TRUE);
    } else {
        XtDisplayStringConversionWarning(display, (char *)
                fromVal->addr, XtRLong);
        return(FALSE);
    }
}

Note that Xt manages the cache of converted values: converter routines are not responsible for caching their own returned data. Notice that the XrmValuePtr arguments passed into the converter are pointers to structures, not values. The XrmValue structure contains an address field and a size field.

XtDisplayStringConversionWarning() takes as arguments a pointer to the Display structure, the string that could not be converted, and the type to which it could not be converted. It issues a warning message with name conversionError, type string, class XtToolkitError, and the default message string “Cannot convert "src" to type dst_type.” (See Chapter 14, Miscellaneous Toolkit Programming Techniques, for more information on error and warning messages.)

Many converters need to compare multiple strings in order to convert a value. For example, Motif's string to arrow-direction converter has to determine whether a string matches XmARROW_UP, XmARROW_DOWN, XmARROW_LEFT, or XmARROW_RIGHT. Normally this would require up to four time-consuming string comparisons for each conversion. Instead, converters of this type use a shortcut based on quarks. A quark is a unique integer ID for a string, of type XrmQuark (defined by Xlib). A call to the Xlib routine XrmStringToQuark returns the quark for a string. A converter determines quarks for each of its reference strings (such as XmARROW_UP) only once during run time, and determines a quark for each string to be converted. Then quarks can be compared quickly since they are just integers. (See Volume Two, Xlib Reference Manual, for details on quarks.)

When a nonstandard type converter that uses quarks is defined and registered in widget code, the XrmStringToQuark calls are normally placed in the class_initialize method just before the XtSetTypeConverter() call.

    /*
      * CompareISOLatin1 is an undocumented Xt function, allowed
      * since this converter is within Xt.  In your converters,
      * you would use XmuCompareISOLatin1.
      */
     if (CompareISOLatin1(str, XtDefaultBackground) == 0) {
         *destructor_data = False;
         if (pd->rv)
             done(Pixel, BlackPixelOfScreen(screen))
         else
             done(Pixel, WhitePixelOfScreen(screen));
     }
     if (CompareISOLatin1(str, XtDefaultForeground) == 0) {
         *destructor_data = False;
         if (pd->rv)
             done(Pixel, WhitePixelOfScreen(screen))
         else
             done(Pixel, BlackPixelOfScreen(screen));
     }

The initialize_hook, set_values_hook, and get_values_hook methods are used by widgets that have subparts. They have the same function as their nonhook counterparts, except that they process only the resources of a subpart, and any subpart instance fields that depend on the subpart resources. These methods are called immediately after their nonhook counterparts.

However, the initialize_hook and set_value_hook methods have become obsolete in R4 because their arguments have been added to the initialize and set_values methods. The hook methods are still called for compatibility with existing widgets, but new widgets should move the code that would have been in the hook methods into initialize and set_values.

The get_values_hook method is passed a single copy of the widget instance structure (the new copy already modified in the nonhook methods), and the argument list passed to the Xt routine that triggered the method. The set_values and get_values_hook methods simply take this widget ID and argument list and pass them to XtSetSubvalues() or XtGetSubvalues() respectively. The initialize method uses the contents of the argument list to validate resource settings for subparts and to set nonresource subpart data.

The get_values_hook method is still used in R4. Example 10-19 shows the get_values_hook for the AsciiSrc subpart of the R3 Text widget (somewhat simplified to show the essential elements).

static void
GetValuesHook(src, args, num_args)
XawTextSource src;
ArgList args;
Cardinal * num_args;
{
        .
        .
        .
     XtGetSubvalues((XtPointer) src,
             sourceResources,
             XtNumber(sourceResources),
             args,
             *num_args);
}

Managing subresources is very similar to managing application resources. Like the application, the subpart must have a structure containing the fields to set through resources. In the application you call XtGetApplicationResources() or XtVaGetApplicationResources() to set these fields. In a subpart, the analogous calls are XtGetSubresources() or XtVaGetSubresources(), which is called from the initialize method.

Like widgets, the resources of subparts can be queried and set manually. XtVaGetSubvalues() or XtGetSubvalues() queries the values, and XtVaSetSubvalues() or XtSetSubvalues() sets them. However, because subvalues are not part of any widget, these calls cannot identify what object is being queried or set simply by passing the widget ID. These calls have different arguments than XtSetValues() and XtGetValues(). Instead of the widget ID, you pass the pointer to the data structure, the resource list, and the number of resources. Therefore, XtSetSubvalues() and XtGetSubvalues() can be invoked only from within the widget or subpart. Actually, all these routine do is set or get the value in the specified structure.

Any application using the widget will set or get subresources using XtSetValues() and XtGetValues() as for normal resources, specifying only the coordinating widget as the first argument. These calls are translated into XtSetSubvalues() and XtGetSubvalues() calls by the set_values and get_values_hook methods. These methods are passed the arguments from the XtSetValues() or XtGetValues() calls and translate them into XtSetSubvalues() or XtGetSubvalues() calls by adding the data structure and resource list arguments. But in addition, the set_values method is responsible for validating the resource settings passed in before it calls XtSetSubvalues(), and for changing any nonresource subpart structure fields like GCs that depend on resources.