RESOURCES

To make the tailoring of applications to personal prefernces easier, X provides a mechanism for storing default values for program resources (e.g. background color, window title, etc.) Resources are specified as strings that are read in from various places when an application is run.

Program components are named in a hierarchical fashion, with each node in the hierarchy identified by a class and an instance name. At the top level is the class and instance name of the application itself. By convention, the class name of the application is the same as the program name, but with the first letter capitalized (e.g. Bitmap or Emacs) although some programs that begin with the letter ``x'' also capitalize the second letter for historical reasons.

The precise syntax for resources is:

ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line> a lookComment = "!" {<any character except null or newline>} IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace FileName = <valid filename for operating system> ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value ResourceName = [Binding] {Component Binding} ComponentName Binding = "." | "*" WhiteSpace = {<space> | <horizontal tab>} Component = "?" | ComponentName ComponentName = NameChar {NameChar} NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" Value = {<any character except null or unescaped newline>}

Elements separated by vertical bar (|) are alternatives.

Curly braces ({...}) indicate zero or more repetitions of the enclosed elements.

Square brackets ([...]) indicate that the enclosed element is optional.

Quotes ("...") are used around literal characters. IncludeFile lines are interpreted by replacing the line with the contents of the specified file.

The word "include" must be in lowercase.

The filename is interpreted relative to the directory of the file in which the line occurs (for example, if the filename contains no directory or contains a relative directory specification).

If a ResourceName contains a contiguous sequence of two or more Binding characters, the sequence will be replaced with single "." character if the sequence contains only "." characters, otherwise the sequence will be replaced with a single "*" character. A resource database never contains more than one entry for a given ResourceName. If a resource file contains multiple lines with the same ResourceName, the last line in the file is used. Any whitespace character before or after the name or colon in a ResourceSpec are ignored.

To allow a Value to begin with whitespace, the two-character sequence ``\space'' (backslash followed by space) is recognized and replaced by a space character, and the two-character sequence ``\tab'' (backslash followed by horizontal tab) is recognized and replaced by a horizontal tab character. To allow a Value to contain embedded newline characters, the two-character sequence ``\n'' is recognized and replaced by a newline character. To allow a Value to be broken across multiple lines in a text file, the two-character sequence ``\newine'' (backslash followed by newline) is recognized and removed from the value.

To allow a Value to contain arbirary character codes, the four-character sequence ``\nnn'', where each n is a digit character in the range of ``0'' - ``7'', is recognized and replaced with a single byte that contains the octal value specified by the sequence. Finally, the two-character sequence ``\\'' is recognized and replaced with a single backslash. When an application looks for the value of a resource, it specifies a complete path in the hierarchy, with both class and instance names. However, resource values are usually given with only partially specified names and classes, using pattern matching constructs.

An asterisk (*) is a loose binding and is used to represent any number of intervening components, including none. A period (.) is a tight binding and is used to separate immediately adjacent components.

A question mark (?) is used to match any single component name or class. A database entry cannot end in a loose binding; the final component (which cannot be "?") must be specified. The lookup algorithm searches the resource database for the entry that most closely matches (is most specific for) the full name and class being queried. When more than one database entry matches the full name and class, precedence rules are used to select just one. The full name and class are scanned from left to right (from highest level in the hierarchy to lowest), one component at a time. At each level, the corresponding component and/or binding of each matching entry is determined, and these matching components and bindings are compared according to precedence rules. Each of the rules is applied at each level, before moving to the next level, until a rule selects a single entry over all others.

The rules (in order of precedence) are:

1. An entry that contains a matching component (whether name, class, or "?") takes precedence over entries that elide the level (that is, entries that match the level in a loose binding).
2. An entry with a matching name takes precedence over both entries with a matching class and entries that match using "?". An entry with a matching class takes precedence over entries that match using "?".
3. An entry preceded by a tight binding takes precedence over entries preceded by a loose binding. Programs based on the X Tookit Intrinsics obtain resources from the following sources (other programs usually support some subset of these sources):

RESOURCE_MANAGER root window property

Any global resources that should be available to clients on all machines should be stored in the RESOURCE_MANAGER property on the root window of the first screen using the xrdb program. This is freuently taken care of when the user starts up X through the display manager or xinit.

SCREEN_RESOURCES root window property Any resources specific to a given screen (e.g. colors) that should be available to clients on all machines should be stored in the SCREEN_RESOURCES property on the root window of that screen. The xrdb program will sort resources automatically and place them in RESOURCE_MANAGER or SCREEN_RESOURCES, as appropriate. application-specific files

Directories named by the environment variable XUSER-FILESEARCHPATH or the environment variable XAPPLRESDIR, plus directories in a standard place (usually under /usr/lib/X11/, but this can be overridden with the XFILESEARCHPATH environment variable) are searched for for application-specific resources. For example, application default resources are usually kept in /usr/lib/X11/app-defaults/.

See the X Toolkit Intrinsics - C Language Interface manual for details.

XENVIRONMENT

Any user- and machine-specific resources may be specified by setting the XENVIRONMENT environment variable to the name of a resource file to be loaded by all applications. If this variable is not defined, a file named $HOME/.Xdefaults-hostname is looked for instead, where hostname is the name of the host where the application is executing.

-xrm resourcestring Resources can also be specified from the command line.

The resourcestring is a single resource name and value as shown above. Note that if the string contains characters interpreted by the shell (e.g., asterisk), they must be quoted. Any number of - xrm arguments may be given on the command line. Program resources are organized into groups called classes, so that collections of individual resources (each of which are called instances) can be set all at once. By convention, the instance name of a resource begins with a lower- case letter and class name with an upper case letter. Multiple word resources are concatenated with the first letter of the succeeding words capitalized.

Applications written with the X Toolkit Intrinsics will have at least the following resources:

background (class Background) This resource specifies the color to use for the window background.

borderWidth (class BorderWidth) This resource specifies the width in pixels of the window border.

borderColor (class BorderColor) This resource specifies the color to use for the window border.

Most applications using the X Toolkit Intrinsics also have the resource foreground (class Foreground), specifying the color to use for text and graphics within the window. By combining class and instance specifications, application preferences can be set quickly and easily. Users of color displays will frequently want to set Background and Foreground classes to particular defaults. Specific color instances such as text cursors can then be overridden without having to define all of the related resources.

For example,

bitmap*Dashed: off
XTerm*cursorColor: gold
XTerm*multiScroll: on
XTerm*jumpScroll: on
XTerm*reverseWrap: on
XTerm*curses: on
XTerm*Font: 6x10
XTerm*scrollBar: on
XTerm*scrollbar*thickness: 5
XTerm*multiClickTime: 500
XTerm*charClass: 33:48,37:48,45-47:48,64:48
XTerm*cutNewline: off
XTerm*cutToBeginningOfLine: off
XTerm*titeInhibit: on
XTerm*ttyModes: intr ^c erase ^? kill ^u
XLoad*Background: gold
XLoad*Foreground: red
XLoad*highlight: black
XLoad*borderWidth: 0
emacs*Geometry: 80x65-0-0
emacs*Background: rgb:5b/76/86
emacs*Foreground: white
emacs*Cursor: white
emacs*BorderColor: white
emacs*Font: 6x10
xmag*geometry: -0-0
xmag*borderColor: white

If these resources were stored in a file called .Xresources in your home directory, they could be added to any existing resources in the server with the following command:

% xrdb -merge $HOME/.Xresources

This is frequently how user-friendly startup scripts merge user-specific defaults into any site-wide defaults. All sites are encouraged to set up convenient ways of automatically loading resources.

See the Xlib manual section Resource Manager Functions for more information.