X Resource Syntax (Unix Power Tools, 3rd Edition)

6.3. X Resource Syntax

Virtually all X Window System clients are customizable.[25] You can specify how a client looks on the screen -- its size and placement, its border and background color or pattern, whether the window has a scrollbar, and so on. This article introduces X resources and shows their syntax.

[25]Not to be confused with the extensive customization of window decorations and the like now possible with window managers such as Enlightenment, Afterstep, FVWM, or Sawfish. If you have a difficult time visualizing what is affected by these resource assignments apart from the fancy decoration around the windows themselves, try killing your window manager and viewing just the X clients themselves, in all of their sparse glory.

Traditional Unix applications rely on command-line options to allow users to customize the way they work. X applications support command-line options too, but often not for all features. Almost every feature of an X program can be controlled by a variable called a resource; you can change the behavior or appearance of a program by changing the value associated with a resource variable.

Resource variables may be Boolean (such as scrollBar: True) or take a numeric or string value (borderWidth: 2 or foreground: blue). What's more, in applications written with the X Toolkit (or an Xt-based toolkit such as the Motif toolkit), resources may be associated with separate objects (or "widgets") within an application. There is a syntax that allows for separate control over both a class of objects in the application and an individual instance of an object. This is illustrated by these resource specifications for a hypothetical application called xclient:

xclient*Buttons.foreground:     blue
xclient*help.foreground:        red

The first resource specification makes the foreground color blue for all buttons in the xclient application (in the class Buttons); the second resource specification makes the foreground color red for the help button in this application (an instance of the class Buttons). Resource settings can be even simpler than this.

The values of resources can be set as application defaults using a number of different mechanisms, including resource files in your home directory and a program called xrdb (X resource database manager). As we'll see, the xrdb program stores resources directly in the X server, making them available to all clients, regardless of the machine on which the clients run.[26]

[26]Remember, in X the client server model is the inverse of what you may be used to; the server is local, and displays clients that may be running remotely.

Placing resources in files allows you to set many resources at once without the restrictions encountered when using command-line options. In addition to a primary resource file (often called .Xdefaults, .Xresources, or xrdb) in your home directory, which determines defaults for the clients you yourself run, the system administrator can create system-wide resource files to set defaults for all instances of the application run on this machine. It is also possible to create resource files to set some resources for just the local machine, some for all machines in a network, and some for one or more specific machines.[27]

[27]While this is often okay for applications such as xterm that have not been modified much since the early nineties, app-defaults files can be more trouble than they're worth in a rapid application development environment, as they can quickly get out of sync with changes in the application itself from one version to the next.

The various resource files are automatically read in and processed in a certain order within an application by a set of routines called the resource manager. The syntax for resource specifications and the rules of precedence by which the resource manager processes them are intended to give you the maximum flexibility in setting resources with the minimum amount of text. You can specify a resource that controls only one feature of a single application, such as the red help button in the hypothetical xclient settings listed earlier. You can also specify a resource that controls one feature of multiple objects within multiple applications with a single line.

Command-line options normally take precedence over any prior resource settings; so you can set up the files to control the way you normally want your application to work and then use command-line options (in an alias or shell function (Section 29.1), for instance) to specify changes you need for only one or two instances of the application.

The basic syntax of a resource definition file is fairly simple. Each client recognizes certain resource variables that can be assigned a value; see the client's manpage for a list.

Toolkits are a mechanism for simplifying the design and coding of applications and making them operate in a consistent way. Toolkits provide a standard set of objects or widgets, such as menus, command buttons, dialog boxes, scrollbars, and so on. If a client was built with the X Toolkit, this should be noted on its manual page. In addition to certain application-specific resource variables, most clients that use the X Toolkit recognize a common set of resource variables.

The most basic line you can have in a resource definition file consists of the name of a client, followed by a dot (.) or an asterisk (*), and the name of a variable. A colon (:) and whitespace separate the client and variable names from the actual value of the resource variable. The following line gives a scrollbar to all instances of the xterm client:

xterm*scrollBar:        True

If the name of the client is omitted, the variable is global: it applies to all instances of all clients (in this case, all clients that can have a scrollbar). If the same variable is specified as a global variable and a client-specific variable, the value of the client-specific variable takes precedence for that client. However, if the name of the client is omitted, the line should generally begin with an asterisk.

Be sure not to omit the colon inadvertently at the end of a resource specification. This is an easy mistake to make, and the resource manager provides no error messages. If there is an error in a resource specification (including a syntax error such as the omission of the colon or a misspelling), the specification is ignored. The value you set will simply not take effect.

A line starting with an exclamation point (!) is ignored as a comment. If the last character on a line is a backslash (\), the resource definition on that line is assumed to continue on the next line.

--VQ and SJC