Resource Specification Syntax

To understand how to assign a resource value, a description of the resource specification syntax is first provided. You assign resource values through this syntax, especially when using resource specification files.

An application's resource specification syntax is composed of the name of the application (or client), its child widgets, and the resource that is being specified. It depends on how the components of an application are organized; in other words, the hierarchical relationship between the parent and child widgets. For example, in a mail program there might be a MainWindow containing several PushButtons. Each PushButton might have an associated subwindow that contains any number of Menus. If you want to specify the font size for a single Menu in one of the subwindows, you need to know the names of all the widgets and their positions in the widget hierarchy.

These hierarchical components of a resource specification syntax are separated by one of three separators.

.

The dot is used between either an instance or class name and the lower widgets of a hierarchy to indicate a tight binding, where the presented hierarchy must be in the correct order. Usually the name of a class or an instance of the application comes first, followed by the name of the highest widget in the widget hierarchy. The name of the top widget in the hierarchy is followed by the specification of any number of widgets lower in the hierarchy. Finally, the resource to be specified is placed at the end of this hierarchical specification.

*

The asterisk is used between either an instance or class name and any of the lower widgets of a hierarchy, or the resource itself, to indicate a loose binding, where the asterisk acts as a wildcard. The asterisk substitutes for any number of components in the widget hierarchy. It can also be used as the first component in a resource specification, without an preceding instance or class name.

Note that using the * (asterisk) causes the system to assume that the resource value being set is to apply to all the represented components. Because of this capability, you should be careful of unexpected results from overuse of the * (asterisk). For example, if you specify a resource specification of the following:

*Foreground:    Purple

this would make the foreground of any client/application that had a foreground resource be purple.

?

Unlike the preceding two separators, the question mark is used between two dots, and substitutes for a single widget or class name. It can also substitute for the first component in the resource specification, be followed by an asterisk, and not have a preceding period.

A resource specification syntax can be expressed by using any combination of these separators.

Every application and resource in X has both an instance name and a class name. The instance name identifies each application and resource individually. The class name specifies the general category to which each individual instance of an application or resource belongs. For example, the class name Mailer specifies all instances of an application called mailer. Class names always begin with an uppercase letter and instance names always begin with a lowercase letter. If the instance name of a specific component is a compound word, like pushButton, the second word usually begins with an uppercase letter. The class name and the instance name for an application are often the same, except for the case of the initial character(s). The instance name for an application is usually the name of the command that is used to start the application. The specification of an instance and its classes can be a hierarchical one, where an instance can have multiple classes.

The presence of the ? (question mark) separator slightly changes the existing X11 rules for matching components when an application looks up the value for a resource. When a resource match is requested, the system performs a left-to-right scan of the resource specification supplied by the application. When there is some ambiguity in the matching process, such as that caused by use of one of the wildcards, the following rules are followed to determine the priority order for specifying the resource value:

1. A resource match by the current component's name has priority over a match with the same component by class. A match by either component name or class takes precedence over a match by the ? (question mark) substitution character, and any of the three matches has priority over an * (asterisk) substitution.
2. A resource that uses a. (dot) to precede the current component has a higher priority than one that uses an * (asterisk) in the same position.

Using #include in Resource Files

When using the xrdb client program, resource files can also use the

#include "filename"

directive to include other resource files into the current resource file. This can be used to reduce duplicate entries in resource files. For example, if there is a base resource file for an application, and you simply want to reset the values of some of the base resources for this application, you can simply use

#include

to put the file into your own application-specific resource file and change just the resource values you want to change, leaving the other resources as they are.

Assigning Resource Values

This section provides examples of how to use the resource specification syntax. In general, these syntaxes are most important when used in resource specification files. Most of the examples illustrate typical lines you might use in a resource specification file. However, as shown in Section 4.3, if you are using an application's command line to set resource values, using fuller resource specifications in the command line can ensure that these settings override existing ones.

The following is a format that uses a. (dot) as a separator.

Client.
 
widget1.
 
widget2. ...
 
resource: 
 
value

As an example, you could use the following specifications in your .Xdefaults file to set resources for xcal clients on your system:

XCal.edit.geometry: 350x200

In this example, the specification states that only the geometry resource for the edit child widget of the XCal parent widget is to be set with the size of 350 by 200 pixels. XCal is the class name.

The following is a format that uses an * (asterisk) as a separator. It illustrates a general, abbreviated format:

Client*
 
resource: 
 
value

As an example, you could use the following specifications in your .Xdefaults file to set resources for xterm clients on your system:

XTerm*background:       Wheat
 
XTerm*foreground:       Navy
 
XTerm*font:             fixed
 
XTerm*scrollBar:        true
 
Xterm*geometry:         80x30

In this example, every instance of an xterm window on your system appears with a wheat-colored background and navy-colored foreground (the color of any text or graphics that appear in the window), uses the font named fixed, has a size of 80 by 30 pixels, and provides a ScrollBar. XTerm is the class name.

When using an * (asterisk) to substitute for the class name, the resource specification line would appear as the following:

*Foreground: Blue

This specification ensures that the foreground (text and graphics) in all clients will be blue.

You can use the following specification in your .Xdefaults file to set the font for every window in every instance of the mailer application:

Mailer*fontList: fixed

The next example shows how you would specify the font only for the area in which you compose mail messages in the mailer application:

Mailer*messageArea*fontList: fixed

The following is a format that uses the ? (question mark) separator.

Client.?.
 
resource: 
 
value

As an example, you can use the following resource specification to set the background color for all of the widgets that are grandchildren of the top widget in the hierarchy for the application:

Mailer.?.?.Background: Red

With X11R5 and the xrdb client program, you can now also use C preprocessor commands in your .Xdefaults file to specify per-screen resources. For example, you can separate resource specifications for color screens from monochrome screens as follows:

#ifdef COLOR
 
*Background: Grey
 
*Foreground: Navy
 
#else
 
*reverseVideo: True
 
#endif

You can also specify unit types in your .Xdefaults file for any resource that is of type Dimension or Position with the following format:

<floating value><unit>

where:

unit

is <"", pixels, inches, centimeters, millimeters, points, font units

pixels

is <pix, pixel, pixels>

inches

is < in, inch, inches>

centimeter

is < cm, centimeter, centimeters>

millimeters

is < mm, millimeter, millimeters>

points

is < pt, point, points>

font units

is < fu, font_unit, font_units>

float

is {"+"|"-"}{{<"0"-"9">*}.}<"0"-"9">*

Note that the type Dimension must always be positive.

For example,

xmfonts*XmMainWindow.height: 10.4cm
 
*PostIn.width: 3inches

The documentation for an application should provide the instance and class names of any components that the application allows you to customize. When appropriate, use the class name in a resource specification to ensure that all instances will use the same resource values. Chapters 5, 6, and 7 provide additional information about the specification of particular resources for mwm and Motif applications.