6. Using and Specifying X Resources

(See footnote)

The Xlib Resource Manager provides a set of tools for specifying and manipulating user preferences (e.g. geometry, colors, fonts). Simple programming interfaces to it are provided by the X Toolkit and by the Xlib routine XGetDefault.

Resources, also refered to as "defaults" in older versions of X, are simply <name,value> pairs that are frequently used to control the appearence or function of particular program or subsystem. They provide a convenient way to tailor whole collections of applications with a minimal amount of work.

In previous versions of X, defaults were stored in a .Xdefaults file in each user's home directory, on every machine. In addition to requiring duplicate copies of the defaults, it did not lend itself to conditional specifications (particularly if the user used both monochrome and color displays).

In X11, these problems are solved by using the window property mechanism in the X protocol to store resources in the server, where they are available to all clients. As a result, defaults may now be dynamically specified based on the particular display being used. This is particularly useful in setting up different defaults for monochrome and color displays. Furthermore, a new convention for specifying resources from the command line has been established (and is supported by all clients of the X Toolkit).

Resources are usually as "program.name.subname.etc: value", one per line in resource files, or one per -xrm argument. Names are hierarchies, usually corresponding to major structures within an application (where structures are often objects like windows, panels, menus, scrollbars, etc.). The various subnames are called components and are specified left to right from most general to least general.

If we take the "xmh" application as an example, we can see that its display is made up of sections called "panes", some of which in turn contain command buttons. The "include" button (used to retreive new mail) in the "toc" (table of contents) pane could be named as follows:


            program   pane   object group   subobject

              name    name       name          name  

              xmh      toc      buttons      include

An object's fully specified name (such as "xmh.toc.buttons.include" in the example above) is called the "instance" name for that object. In addition, each component belongs to a collection of similar components (such as the set of all panes, the set of all buttons, etc.) that can be specified using a "class" name. In the above example, if we assume that the xmh program is one of possibly several "Xmh" types of programs (just as "gnuemacs" and "microemacs" might be thought of as instances of the class of "Emacs" programs), we could build the following class name:


      application   top level   second level   third level

          type      area type    object type   object type

          Xmh         VPaned         Box       Command ...

By convention, instance name components begin with lowercase letters and class name components begin with uppercase letters. Components that are made up of more than one word have the succeeding words capitalized and concatentated without any spaces. Thus, an instance of an icon pixmap might be called "iconPixmap" whereas the class of icon pixmaps would be called "IconPixmap". The capitalization is important because resource names may contain both instance and class name components within the same specification (for example, "gnuemacs.VPaned.cursorColor: blue").

Class names allow default values to be specified for all versions of given object. Instance names allow a value for a particular version to be given that overrides the class value, and can be used to specify exceptions to the rules outlined by the class names. For example, we could specify that that all command buttons in button boxes in vertical panes should have a background color of blue, except for "include", which should be red: with


 *VPaned.Box.Command.Background:   blue

 xmh.toc.buttons.include.background:   red

Furthermore, resource name hierarchies do not have to be fully specified. In the preceeding example, we listed each of the individual components; however, this can be quite cumbersome. Instead of having to give a full specification for each set of objects (there might be slider bars, or edit windows, or any number of other types), we can just "wildcard", or omit, the intervening components by using the "*" separator in place of the "." separator. In general, it is a good idea to use the "*" instead of "." in case you've forgotten any intervening components or in case new levels are inserted into the middle of the hierarchy.


 Xmh*VPaned*Background:  blue

 xmh*toc.buttons.include.background: red

The distinction between classes and instances is important. For example, many text applications have some notion of background, foreground, border, pointer, and cursor or marker color. Usually the background is set to one color, and all of the other attributes are set to another so that they may be seen on a monochrome display. To allow users of color displays to set any or all of them, the colors may be organized into classes as follows:


                   instance name   class name

                   background      Background

                   foreground      Foreground

                   borderColor     Foreground

                   pointerColor    Foreground

                   cursorColor     Foreground

Then, to configure the application to run in "monochrome" mode, but using two colors, you would only have to use two specifications:


 obj* Background:  blue

 obj* Foreground:  red

Then, if you decided that you wanted the cursor to be yellow, but the pointer and the border to remain the same as the foreground, you would only need one new resource specification:


 obj*cursorColor: yellow

Because class and instance names are distinguishable by case, both types of names may be given in a single resource specification. The Xlib manual gives the following additional examples (note, the "xmh" program may use other names, these are for example only):


 xmh*background:                      red

 *command.font:                       8x13

 *command.background:                 blue

 *Command.Foreground:                 green

 xmh*toc*Command.activeForeground:    black

The resource hierarchy "xmh.toc*Command.activeForeground" specifies a particular color resource (in this case, the active foreground color) of all components of class Command that are contained within the "toc" in the xmh application. Although this is very powerful, figuring out that this can be specified at all, let alone how, is currently a problem with the documentation for many of the more complex clients of the Resource Manager.

Eventually, widgets should be documented just as commands are today: there should be descriptions of the instance names, class names, and allowable values for each of the widget's resources. Application documentation would then only need to describe how widgets are combined. Until then, the best places to look for information on which resources may be specified are:


     1. the manual pages for the application

     2. any documentation for the widgets used by the application

     3. any application resource files in

                      /usr/lib/X11/app-defaults/

     4. any XtResource tables in the the application or

                      the widget sources

Under X11, you have a lot of flexibility as to where defaults are defined. The Resource Manager obtains resource specifications from the following places in the order shown. Therefore the later, more specific user-oriented options override the earlier general system wide options :

(1)
Values set through through the application's fall back mechanism.

(2)
Values set in /usr/lib/$LANG/X11/app-defaults/class if it exists else values in /usr/lib/X11/app-defaults/class. (See footnote)

(3)
Resources pointed to by other environment variables :


            IF $XUSERFILESEARCHPATH is set

                then it contains a list of directories to search.

            ELSE IF $XAPPLRESDIR/$LANG/class is set

                it contains a single directory where resource files must be found.

            ELSE IF $XAPPLRESDIR/class is set

                it contains a single directory where resource files must be found.

            ELSE IF $HOME/$LANG/class is set

                it contains a single directory where resource files must be found.

            ELSE

                Look in $HOME/class

(4)
Resource values set in $HOME/.Xdefaults, provided that the RESOURCE_MANAGER property hasn't been set via the xrdb command.

(5)
Resource values loaded into the Resource Data Base via xrdb.

(6)
Resources pointed to by $XENVIRONMENT if set else $HOME/.Xdefaults-hostname.

(7)
Command line arguments.

(8)
Hard coded values for resources.

Resources are usually loaded from a file into the RESOURCE_MANAGER property using the "xrdb" program from whatever script you use to start up X. Sites that use the xdm Display Manager will most likely provide for loading in user-specified resources automatically.

The xrdb program uses the C preprocessor to provide conditionals based on the configuration of the server being used. This is very useful if you commonly use different types of servers (such as monochrome and color) from the same account. See the xrdb(1) manual page for more details.

The next section is concerned with Xdm - how X initially runs on the workstation.