How do I use X Resources?

Users can customize the look of programs that use an X interface with entries in an X resources file. On Athena, this file is named .Xresources, and needs to reside at the top level of a user's home directory in order for it to work. Examples of customizations include changing the geometry and size of an application, or the colors that the program uses.

WHAT DO I NEED TO KNOW TO USE X RESOURCES?

To specify resources for a program using your .Xresources file, you first must know the resource you want to specify, and the program's instance or class.

You can find the resources for a program by checking the X manual page, for standard resources that are used by programs written with the X Toolkit Intrinsics, and by checking that program's manual page, for resources specific to that program. For example, to find the resources for the program "xterm," you would type:

man xterm

By convention, the default instance for an X program is just its name, and the class is just its name with the first letter capitalized, unless the first letter is an "X," in which case the first two letters are capitalized. For example, the "xterm" program's instance is "xterm" and its class is "XTerm," and the program "mwm" has "mwm" as an instance, and "Mwm" as a class.

The unfortunate thing about finding out the class and instance of a given program is that by convention, many X programmers are unconventional. If this is the case, just start up the X program in question, type "xprop" at a unix prompt, and then click in the window of the X program. This will give you the class and instance of the program. For example, using xprop on an "xterm" window gives:

WM_CLASS(STRING) = "xterm", "XTerm"

HOW DO I USE X RESOURCES?

Entries in the .Xresources file have a variety of different, but similar, forms. Explaining them all here would be take too much detail. If you need more information than what is here, please read the X manual page.

Generally, the forms entries take on are:

class*resource: value
instance*resource: value
class.resource: value
instance.resource: value

The first element in a resource specification is either a "class" or an "instance". A class consists of ALL the invocations of a particular program. An instance is a process which is given a particular name.

For example, XTerm is a class. All xterms you start up, no matter how they are started up fall under this class (and as such all the resources starting with this class will apply to it). However, you can also start up an xterm like this:

xterm -name xterm-big

This process will have a class of XTerm, but an instance of xterm-big. So, you could create resources like this:

XTerm*reverseVideo: on
xterm*VT100.geometry: 80x24
xterm-big*VT100.geometry: 80x48
xterm-small*VT100.geometry: 80x10

where EVERY xterm you start up will have reverse video on, but one started with the '-name xterm-big' option will have one geometry, one started with the '-name xterm-small' option will have another, and one started with no specific name will default to the name 'xterm' and have yet a different geometry. (The VT100 designation is used to indicate that the geometry is for the main text window, and not the menus or subwindows.)

The resource name (e.g. 'geometry' in your above example) is a particular aspect of an X program. Be careful when spelling resource names. Only particular spellings of resources are correct. Example: 'reverseVideo' and 'ReverseVideo' will function correctly as xterm resources, but not other spellings.

Other examples are:

	oneko*tora: true

	matlab*reverseVideo: false   ! matlab windows in "reverse video"

	emacs*Font: 8x13             ! emacs with 8x13 font, 80 columns
	emacs*geometry: 80x48+0+0    !   wide, 48 columns high

	XTerm*scrollBar: on	     ! Xterms with a scrollbar that
	XTerm*saveLines: 250	     !   keep track of last 250 lines

	XTerm*VT100.geometry:80x48+0+0  ! Make only the main xterm
					!   window be 80x48

In these examples, the difference between the "*" (a loose binding) and the "." (a tight binding) is that the * causes the resource to be applied to all the children windows within the top-level window (such as menus), whereas the dot causes the resource to be applied only to the top-level window of the program.

MISCELLANEOUS INFORMATION

The exclamation mark (!), is used to comment a line in the .Xresources file.

Instance names are considered more specific than class names. If you use both the class and instance names of a program to specify a resource with different values, the instance resource value will be used. For example:

xterm*Background: blue

will be used, instead of:

XTerm*Background: green

To re-read your .Xresources file, and throw away your old resources, you can type:

xrdb ~/.Xresources

To re-read your .Xresources file, and keep your old resources, type:

xrdb -merge ~/.Xresources

This will merge any new resources you've put in with the current resources you're using.

For Athena programs, the default resources for programs with an X interface are kept in the directory /usr/athena/lib/X11/app-defaults.

You don't actually need the class or instance name of a program to make a customization. For example, if you wanted to make the same customization for all X-driven programs, you put an entry of the form:

*resource: value

in your .Xresources file.

Avoid blank spaces at the beginning and end of lines in the .Xresources file.

You can find sample Xresources files by typing "attach dotfiles" and looking in the directory /mit/dotfiles/Xresources.

You can change the instance of many X programs by starting them with the -name option. For example, if you start an xterm window by typing "xterm -name XT1", then you can specify resources for it in your .Xresources file with "XT1,", like this:

XT1*Background: yellow