In loading the application class defaults and the user's per-application defaults, XtDisplayInitialize calls XtResolvePathname to determine which files to read. XtResolvePathname uses file search paths. Each path is a set of patterns that may contain special character sequences for which XtResolvePathname substitutes runtime values when it searches for a file. It uses the following substitutions in building the path:

If the language specification is not defined, or if one of its parts is missing, a % element that references it is replaced by NULL.

The paths contain a series of elements separated by colons. Each element denotes a filename, and the filenames are looked up left-to-right until one of them succeeds. Before doing the lookup, substitutions are performed.

---

Note: The Intrinsics use the X/Open convention of collapsing multiple adjoining slashes in a filename into one slash.

---

The XtDisplayInitalize function loads the resource database by merging in resources from these sources, in order of precedence (that is, each component takes precedence over the following components):

XtDisplayInitialize calls the X Resource Manager function XrmParseCommand to extract resource settings from the command line by which the user invoked the application. The arguments and number of arguments on the command line come from the argv and argc arguments to XtAppInitialize, XtOpenDisplay, or XtDisplayInitialize. Xt maintains a standard set of command-line options, such as -background and -geometry, for specifying resource settings. An application can specify additional options in arguments to XtAppInitialize, XtOpenDisplay, or XtDisplayInitialize. The user can supply the -xrm option to set any resource in the database.

To load the per-host user environment resources, XtDisplayInitialize uses the filename specified by the XENVIRONMENT environment variable. If XENVIRONMENT is not defined, XtDisplayInitialize looks for the file $HOME/.Xdefaults-host, where host is the name of the host on which the application is running (that is, the name of the client host, not the server host).

To load screen-specific resources, XtDisplayInitialize looks for a SCREEN_RESOURCES property on the root window of the default screen of the display. The SCREEN_RESOURCES property typically results from invoking the xrdb command when some resources are not defined for all screens.

---

Note: When Xt needs to fetch resources for a screen other than the default screen of the display—for example, when the application creates a widget on another screen—it uses the SCREEN_RESOURCES property of that screen instead of the SCREEN_RESOURCES property of the default screen.

---

To load the server resource property or user preference file, XtDisplayInitialize first looks for a RESOURCE_MANAGER property on the root window of the display's screen 0. The RESOURCE_MANAGER property typically results from invoking the xrdb command when some resources are defined for all screens. If that property does not exist, XtDisplayInitialize looks for the file $HOME/.Xdefaults.

To load the user's application resource file, XtDisplayInitialize performs the following steps:

To load the application-specific class resource file, XtDisplayInitialize performs the appropriate substitutions on the path specified by the XFILESEARCHPATH environment variable. If that fails, or if XFILESEARCHPATH is not defined, XtDisplayInitialize uses an implementation-dependent search path containing at least six entries, in the following order and with the following substitutions:

%C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c
%C, %N, %S, %T, %l
%C, %N, %S, %T
%N, %S, %T, %L or %N, %S, %T, %l, %t, %c
%N, %S, %T, %l
%N, %S, %T

where the substitution for %S is usually NULL and the substitution for %T is usually app-defaults.

If no application-specific class resource file is found, XtDisplayInitialize looks for any fallback resources that may have been defined by a call to XtAppInitialize or XtAppSetFallbackResources.

When an application creates a widget, the creation routine sets the widget's initial resource values from the following sources, in order (that is, each succeeding component takes precedence over preceding components):

Each widget class can have its own initialize procedure. After setting the initial resource values, the widget creation routine calls the initialize procedure for each class in the widget's class hierarchy, in superclass-to-subclass order. The initialize procedure can set new values for resources, possibly based on other resource values in the widget or its ancestors. In some cases, an initialize procedure forces a resource to have a particular value, regardless of whether the user or application has specified another value. In other cases, the initialize procedure might set a resource value only if the user or application has not specified another value.

The documentation for each widget class in the OSF/Motif Programmer's Reference lists the data type and default value for each resource. For resources whose default values are computed dynamically, the documentation describes how the default values are determined.

To specify initial resource values in a call to a widget creation routine, an application supplies two arguments: a list of elements representing resource settings and an integer specifying the number of elements in the list. Each element in the list is a structure of type Arg. This structure has two members: a string representing the name of the resource, and a value specifier representing the resource value. The value specifier is of type XtArgVal. This is a data type large enough to hold a long or one of several types of pointers to other data. If the resource value is of a type small enough to fit into an XtArgVal, the value specifier contains the resource value itself; otherwise, it contains a pointer to the actual value. For most resources, an application supplies integer values (including such types as Position and Dimension) directly in the value specifier; otherwise, the application supplies a pointer to the value.

The most common way to set up a list of resource specifications is to declare a list of Arg elements large enough to hold all the specifications and then to use XtSetArg to insert each specification into the list. An application should always use a sequence of calls to XtSetArg in the following way to avoid mistakes in building the list:

...
Widget      text;
Arg         args[10];
Cardinal    n;
n = 0;
XtSetArg(args[n], XmNrows, 10);         n++;
XtSetArg(args[n], XmNcolumns, 80);      n++;
text = XmCreateText("text", parent, args, n);

Instead of using lists of Arg structures, the variable-argument routines that specify resource values take a variable number of pairs of resource names and values as arguments. The resource value in each pair is of type XtArgVal, with the same meaning as the value in an Arg structure. The application can provide two special strings in place of a resource name. If the name is XtVaNestedList, the next argument is interpreted as a nested list of name-value pairs. If the name is XtVaTypedArg, the next four arguments supply the resource value and cause it to be converted from one data type to another, as described in the following sections.

To specify resource values after a widget has been created, an application uses XtSetValues or XtVaSetValues. XtSetValues takes a list of resource specifications in the same format as that used when creating a widget:

...
Arg         args[10];
Cardinal    n;
n = 0;
XtSetArg(args[n], XmNrows, 10);         n++;
XtSetArg(args[n], XmNcolumns, 80);      n++;
XtSetValues(text, args, n);

Each widget class can have its own set_values procedure. After setting the values specified in the argument list, XtSetValues calls the set_values procedure for each class in the widget's class hierarchy, in superclass-to-subclass order. The set_values procedure can set new values for resources other than those specified in the arguments to XtSetValues. This usually happens when the value of one resource depends on the value of another. Setting a new value for a resource that affects the widget's geometry can also cause Motif to recompute the widget's layout. In some cases a set_values procedure forces a resource to have a particular value, regardless of whether the application has specified another value.

To retrieve resource values, an application uses XtGetValues or XtVaGetValues. The arguments are the same as those for XtSetValues, except that in place of a value for each resource is an address in which Motif stores the requested value:

...
Arg         args[10];
Cardinal    n;
short       nrows, ncolumns;
n = 0;
XtSetArg(args[n], XmNrows, &nrows);            n++;
XtSetArg(args[n], XmNcolumns, &ncolumns);      n++;
XtGetValues(text, args, n);

The documentation for each widget class in the OSF/Motif Programmer's Reference lists the data types to use when setting and retrieving values for resources. The user and application do not always have to supply data of the type documented. Motif has routines, called converters, that convert resource values from one data type to another. For example, when a value for the resource database comes from a file or the command line, Motif processes the value as a string. Motif and Xt have routines to convert strings to most common resource types, including Boolean, Dimension, Position, Pixel, and XmFontList.

When using the standard widget creation routines, XtSetValues, and XtGetValues, an application must supply resource values or addresses of the types the widget expects. But when using the variable-argument versions of these routines, the application can supply values of any types for which routines exist to convert data of those types into values of the expected types. To provide for a resource conversion, the application supplies XtVaTypedArg in place of a resource name in the argument list. In place of the resource value, the application supplies four arguments:

For example, the following call converts the string supplied into the compound string that Motif expects for a PushButton label:

...
char *label = "Button";
XtVaSetValues(button, XtVaTypedArg, XmNlabelString,
    XmRString, label, strlen(label) + 1, NULL);

The application is responsible for allocating and freeing memory needed for resource values it supplies when initializing a widget or setting new values. For most resources whose values are not immediate data, including strings, compound strings, and font lists, Motif makes copies of values the application supplies when it creates a widget or calls XtSetValues. The application can free the allocated memory anytime after the widget creation routine executes or XtSetValues returns:

...
char     *label = "Button";
XmString  label_cs;
label_cs = XmStringCreateSimple(label);
XtVaSetValues(button, XmNlabelString, label_cs, NULL);
XmStringFree(label_cs);

For resources whose values are not immediate data, XtGetValues sometimes makes a copy of values and sometimes does not. For example, Motif always makes copies of compound strings retrieved by XtGetValues, but it does not make copies of lists of compound strings (data of type XmStringTable). Motif usually copies simple strings retrieved by XtGetValues. An application should free compound strings retrieved by XtGetValues, but in general it should not free values of other types unless the documentation for the particular resource in the OSF/Motif Programmer's Reference says the application must free that value.

The standard routines an application should use to allocate memory are XtMalloc and XtNew. The standard routine to free memory is XtFree. Some Motif data types have memory-management routines that an application should use instead of the more general Xt routines. For example, use XmStringFree to free memory for a compound string, and use XmFontListFree to free memory for a font list.