8. The X Resources

We will at this point consider some finer modifications to your system. Configuring the window manager only gets you so far. The window manager lets you customize everything that happens outside the windows, the frames, the borders, the buttons, the desktop... but what about making the inside of the windows pretty? The only way to do this is by modifying the X Resources for your system.

X Resources provide a mechanism for storing default values for program resources and tailoring your windowing environment to your favored look and feel. Resources are specified as text strings that are read in from various places when an application is run. Program components are named in a hierarchical fashion, with each object in the hierarchy identified by a class as well as an instance name. At the top level of the hierarchy 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 (e.g. XTerm).

8.1 X Resources: The Basics

Let's try a few examples to ease you into the world of resources. Start by opening an xterm window. Most likely you have one open already, can open one with a menu selection, or may wish to backtrack a bit in this document to get your bearings! Type something like this into the xterm window:

 xterm -background blue &
 

This command should have resulted in another xterm window popping up on your screen, but this time with a blue background. ``Wow,'' you say, ``that's amazing!'' Yes, indeed it is.

We'll need a little more background for our next example. Type exit in that xterm (which will close that window) and go back to the original window that you typed that command in. Try this: hold the Ctrl key and then hold the left mouse button. Now try that with the middle mouse button. Now the right. All xterm windows give you options to try while they are running. With the right button, for instance, you can change the font of the window. Notice the color of these menus. Now try this example:

 xterm -xrm 'xterm*fontMenu*background: green' &
 

This time, it just looks like a normal xterm window. But if you try holding Ctrl and the right mouse button in that window, you will see that this menu (the ``fontMenu'' mentioned in the above example) is green. What just happened? If you look at the man page for xterm, you will see many command-line options, such as -background or -font, that you can set when you launch any given window in X, listed after the options just for xterm windows. These particular options are called X Toolkit Options, and they apply to just about anything in X.

8.2 Inside The X Resource Database With editres

To really get inside the resources of X, we need to run editres. Go ahead and launch it (and a sample program to play with) now:

 xclock &
 editres &
 

Probably you will see a simple clock, and the rather innocent looking, mostly-blank window of editres. The main window is showing us the resource tree of any given window on our desktop, and upon program launch, there is none. So let's give it one. Hold down the left button on the Commands menu, and select Get Tree. In the top of the window will appear Click the mouse pointer on any toolkit client. This message is more than it seems, and it is a hint to us that not all X applications are toolkit clients (though most of the basic ones are, and the program will usually tell us if it is not in the manual page). The mouse cursor will turn to a crosshair, and wait for you to click on another window.

For this example, let's first click on the xclock. You will see a couple things appear in the editres window. These are the configurable branches that the toolkit sees. Click on the bottom right one (clock). It should invert. Now select ``Show Resource Box'' from the ``Commands'' menu. You will see another window pop up, with the heading ".xclock.clock.unknown". Bingo!

>From here you can toy with the configuration options of the main xclock window. First, click on ``Set Save File'' at the bottom, and put in a filename such as /home/yourname/resources, to indicate that you're testing some of the resources here. Now click on ``foreground'' and put in ``blue'' next to the ``Enter Resource Value:'' prompt. Then hit ``Apply'' at the bottom. The minute notches around the clock should turn blue. Go to ``background'' and enter ``navajowhite'' (or whatever color you prefer). Then apply that. As you can see, we can configure the whole window just fine this way. But if you were to try launching another xclock, it would appear just as this one appeared before any changes. We need to save these changes.

Click ``Save'' and then ``Popdown Resource Box'' (a fancy name indeed for the ``Close'' function!). If you view the file you just created (cat /home/yourname/resources perhaps) you will see all those resources spelled out, in correct X Toolkit format, for your convenience. But that does us little good, for if you try launching another xclock, it will still look Plain Jane. So here is the last and final step in loading in your resources:

 xrdb -merge /home/yourname/resources
 

This command merges the resources we just wrote into the X Resource Database (xrdb) for your session of X Window. That means that for all future invocations of the X applications we modified, our changes will take place, and remain binding. So if you run another xclock, it will look as nice as you have just now set it up, every time you run it. Mind you, xrdb is a complex program, and you may want to have a look at the man page before moving on, or playing around with it some more. If you added the modification to .xinitrc listed earlier in this document, to load the resources automatically on X startup, you should only have to worry about the xrdb command when you make changes during your X session.

8.3 The Anatomy of X Resources

As you can see we have stumbled across a plethora of configuration options here. This method of configuring X, as has been stated, offers nearly limitless possibilities, and an equivalent amount of confusion. To get some picture of the scope of the resources in just the X Toolkit Intrinsics alone, run the program viewres, and play around with it a bit. This program graphically displays the tree of resources in the Xt Library.

If you read the manual page for X, you will find a rather obscure definition of the exact syntax for defining resources it understands. We can simplify this quite a bit and break it down into this essential syntax definition:

<program><binding><widget><binding><widget><...><resource>:<value>

That doesn't really seem that simple, actually. Well, let's define some things about what has just been said, and it will all start to make sense after all. You can peek ahead to the examples in the next section as you read along, if you wish.

The program in this definition is the invocation of an application in the resource database. This would be XTerm for an invocation of xterm, emacs for an invocation of the emacs text editor, or a user-defined name that was given when the applications was launched with the -name command line option. In this way you can define separate resources for xterms which will be used in different ways. Which is pretty cool, really.

The binding can be one of two characters to separate the widgets and such. If you use a . (period), you get a tight binding, which means that one widget is directly above or below the other in the widget hierarchy. This also has the highest precedence of the specification methods. If you use a * (asterisk), you get a so-called loose binding, and you will skip any number of widgets in the hierarchy, and it will attempt to match the next possible widget defined.

The widget entries are items in the widget tree, in order of most-specific to least-specific, that they appear in the widget tree, visible with editres. Any single widget entry can also be replaced with a ? (question mark) to skip a single widget definition, and match any possible widget item.

The resource item must be specified, and cannot be replaced with the ? character. This is the most-specific item in the hierarchy, and usually contains items like the actual color to define, actual font to define, and so forth. In fact, everything else before the resource in this definition can be left out and replaced with a single asterisk, but the actual resource to define must be present. If you just put an asterisk and the most-specific resource name, such as *background: blue, X will attempt to define that resource globally, for all its clients, if possible.

Following the colon is the value entry. This entry defines what the resource will be set to, such as a font name or color value. The value can be specified (depending on context) as a boolean, numeric, or text data type. The value entry, also, cannot be omitted in a valid resource definition.

8.4 Making Your Changes Last With .Xdefaults

There is a magic file you can put in your home directory called .Xdefaults. If you copy the lines in the resources file from the last example into the .Xdefaults in your home directory, you will never have to configure xclock again! While this might not be the finest example of its utility, it makes its point. This file can be crammed full of every option you prefer for every type of program you run in X, and if you take proper care of it, you can still easily go back and make slight changes when you need to. But making lots of changes, and hunting down lots of subtle resources using editres can be an extremely tiring and painstaking procedure. Indeed, sometimes that's too much work, and most of these resources are already waiting for you, neat and orderly, grouped by program, on your system.

In the directory /var/X11R6/lib/app-defaults you will find a great many files, all named after an X Toolkit program. If you examine these files you will find that they contain a great many configuration options for each one, and I do mean a great many! You would not want all of these options from all of these files in your .Xdefaults file, that would be quite tiresome to deal with. These are the defaults, and it is from these that you can decide what you would like to see changed for your particular configuration.

The following are some samples from my .Xdefaults file. Notice a few things we have not yet mentioned about the resource definition files. If a line begins with ! (exclamation point), it is considered a comment, and the rest of the line is ignored. If the line begins with #include filename, that line is an include directive, and at that point in the resources another file will be merged, when it is loaded. This can help keep your resource files from becoming too bloated. And here are some examples:

 ! Default resources for me@localhost xterms
 ! start with the generic, move to the specific...
 *Dialog*Text*font:     -b&h-lucida-medium-r-*-*-12-*-*-*-*-*-*-*
 *dialog*value*background: white
 *Dialog*Label*font:    -adobe-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*
 *MenuButton*font:      -adobe-helvetica-medium-r-*-*-12-*-*-*-*-*-*-*
 *MenuButton*background:        grey80
 *MenuButton*foreground:        black
 *Label.font:           -adobe-helvetica-medium-r-*-*-10-*-*-*-*-*-*-*
 *Label*shadowWidth:    1
 *SmeBSB.font:          -adobe-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*
 *SimpleMenu*font:      -adobe-helvetica-medium-r-*-*-10-*-*-*-*-*-*-*
 *OptionMenu*font:      -adobe-helvetica-medium-r-*-*-10-*-*-*-*-*-*-*
 *Command.font:         -linotype-helvetica-bold-r-narrow-*-12-*-*-*-*-*-*-*
 *commandBox*font:      -b&h-lucida-bold-r-*-*-12-*-*-*-*-*-*-*
 *Toggle.font:          -adobe-helvetica-bold-o-*-*-12-*-*-*-*-*-*-*
 *Form.background:      grey70
 *TransientShell*Dialog.background: grey70
 *Scrollbar.Foreground: grey80
 *Scrollbar.Background: grey50
 *Scrollbar*cursorName: top_left_arrow
 *Scrollbar*width:      16
 *shapeStyle:           Rectangle
 *XlwMenu.shadowThickness: 1
 *shadowWidth:          1
 
 ! xterm stuff
 xterm*scrollbar.background: grey40
 xterm*foreground: grey90
 xterm*background: grey25
 xterm*cursorColor: white
 xterm*visualbell: on
 ! rxvt stuff (a quicker, better xterm)
 rxvt*color12: steelblue
 rxvt*color15: white
 rxvt*color9: rgb:ff/7f/5f
 rxvt*foreground: grey90
 rxvt*background: grey10
 rxvt*cursorColor: white
 rxvt*font: lucidasanstypewriter-12
 rxvt*loginShell: false
 rxvt*saveLines: 1024
 rxvt*title: shell
 rxvt*geometry: 80x25
 ! Make Xman just a little bit more sane
 xman*topBox: false
 xman*background: lightsteelblue
 xman*foreground: black
 ! xcalc is too bland by default...
 xcalc*Command.font: -adobe-helvetica-bold-r-*-*-10-*-*-*-*-*-*-*
 xcalc*customization: -color
 ! Disallow the <blink> tag in Netscape
 Netscape*blinkingEnabled: False
 
 ! Merge other resources (example)
 # include $HOME/.otherXresources
 

One word of warning with regard to X resources, for KDE users. There's a setting in the control panel which will cause all your X Resources to be overwritten in your applications. This can be a really nice feature, but it can also be an annoyance if you have painstakingly configured your resources. Open the control panel and find the ``Fonts etc.'' section. There's an option to ``Apply style to non-KDE apps''. If you turn this on, all your programs will adopt the look and feel configured by KDE (you may need to restart X to notice this). If you leave this option turned off, your resources will remain as you have configured them.

8.5 Your Own User Resource Directory

You can also create a directory of resource files, just like the system-wide app-defaults directory mentioned above, with one file per program. Just create the directory (for our example we'll use app-defaults under your home directory,) and then set the environment variable XAPPLRESDIR to point to it. A good place to set this variable would be in the beginning of your .xinitrc file, for example, put in the line export XAPPLRESDIR=$HOME/app-defaults (if your files are going to be in an app-defaults directory under your home directory).

Now, whenever you start an X program, this directory will be searched for a file with the same name as the resource name of the program, just like the system-wide directory. This is the client name that you used in .Xdefaults files.

For example, a file called XTerm could contain the line *background: gold, and all your xterms would, by default, come up with a gold background. This is a nice alternative to a single .Xdefaults file, and makes it more clear when trying to decide which settings to configure later on, and to find the ones for a certain program. There are still uses for the .Xdefaults, though. It's useful for setting resources not bound to a single program, like modifications that you would make to turn all of a certain kind of button blue, regardless of the application.