Inessential X Resources for Techno-Dweebs

The Student Information Processing Board

Jake Harris, Yonah Schmeidler, Anyone else

Contents

Introduction

What are X Resources?

This document assumes you have some knowledge and experience with the X window system, your favorite text editor, and some UNIX commands and file conventions. Having stated that disclaimer, now to answer the question above. As stated in the X man page, "To make the tailoring of applications to personal preferences easier, X supports several mechanisms for storing default values for program resources (e.g. background color, window title, etc.)" In other words, X resources exist so users can easily make customizations to their X session's interface.

Where do they go?

X resources should be located in a file titled .Xresources in your home directory. If you are new to using X resources, you probably won't have this file. Fret not; just create one with your favorite text editor. And away you go. Oh, don't forget to make sure the capitalization and spelling are correct. One last thing that you should remember is that the dot in front of the filename also makes it invisible to a casual ls.

Why Use Them?

If it is not evident already, X resources provide a powerful and easy to use tool for customizing your X session. Some of the more astute readers may have noticed that you can also use command line options to customize programs (often in many more ways than available as X resources). While command line options are powerful, and better for customizing individual instantiations of programs, X resources are much better for setting general characteristics.

For example, say you wanted red text on a black background for all your Xterm windows. You could remember to type xterm -fg red -bg black & everytime you want a new xterm window. Or you could just add the lines

Xterm*Foreground: red
XTerm*Background: black
to your .Xresources file. Then whenever you type xterm &, your xterm window will automatically be customized. This is a rather simple and pointless example, but it is quite easy to see other uses (such as zwgc or emacs) for which X resources are a much more practical tool than command line options.

General Use

Basic Format

X resources are specified by the name of the application followed by a variable name followed by a colon, space, and a value. It usually looks like this:

appname*resource*subresource...*subresource: value

Capitalization is important, and make sure that there is a space between the colon and the assigned value. And of course, don't forget the colon; although it may not seem that significant, without the colon your X resource assignment will be ignored. Also, from now on, the subresources mentioned above will be referred to as widgets, as they are called in the X specification.

Instances and Classes

Okay. So it's not entirely as simple as that. No primer on X resources would be complete without a discussion of classes. Each part of a resource has a class associated with it. Classes are there to make it easier to modify many X resources with a single command. For instance, if you were modifying xclock and you wanted to make the foreground tic marks and the hands dark blue, you could type
xclock*foreground: darkblue
xclock*hands: darkblue
xclock*highlight: darkblue
Or you could note that all three resources are in the class Foreground (class names have the first letter capitalized by convention) and just type
xclock*Foreground: darkblue
This command will set all the components of the class Foreground to dark blue, saving you time and typing. Classes can also make your changes much easier to understand and implement. Isn't that neat? :)

xrdb and Other Fun Switches

The X system also provide a few options for maintaining and experimenting with X resources. For starters, all programs written with the X toolkit intrinsics support two additional switches that allow you to modify programs on launch with X resources (essentially combining the flexibility of switches with the power of X resources). This is a wonderful way to test X resources before adding them to your .Xresources file (hint, hint). These two switches that are available are:
-xrm "X resource"
This switch allows you to specify on a command line an X resource in quotes to modify the instantiation on launch.
-name filename
This switch allows you to design and specify a special group of X resources to modify a file on launch.
The xrdb program is an X program that allows you to manage and update the environment from your X resource files. This program is automatically invoked with your .Xresources file on startup, but can be called later at any time. A few of the available switches to use in xrdb are:
-load filename
This loads the file into the internal X resources database and interprets it appropriately.
-query
Using this switch displays all of the X resource modifications from the defaults that are currently loaded and in use. It does not display default X resources (and you should be thankful for that, since it would scroll quite a bit).
-merge filename
This switch is very similar to -load. Except it only loads into the database resources not already modified. No current resources are changed by it.

Data Types Used by X Resources (With Examples)

General X Resource Settings

Every application that uses X Toolkit Intrinsics should support some of the following few X resources, unless they are extremely absurd or flaky (both of which are probably a bad idea to modify with X resources anyway). Just precede them with the name of the application you are modifying.

background: color
Use this switch to set the color of the background of a window. (Default: white)
borderWidth: number
This resource allows you to set the width in pixels of the border around the window.
borderColor: color
This is the resource that sets the color of the aforementioned window border.
foreground: color
Most applications also support this resource, which allows you to set the color of foreground text and occaisionally graphics.
geometry: coordinates
This is also supported by most applications, and lets you specify the position and size.

Terminal Dependent Resources

In addition to specifying customizations on a program by program basis, you can change the resources based on X variables. To see a list of the variables which are set, and their values, for a specific platform use xrdb -symbols. This gives a list of items of the form -Dvariable=value; each of these means that variable is set to value.

To take advantage of these, you can use the following: (these are just standard C preprocessor constructs)

#ifdef variable
resources
#else
other-resources
#endif
This will only load resources if variable is set, and other-resources otherwise. The #'s must be the first characters on their lines. The #else is optional. 
#ifndef variable
resources
#else
other-resources
#endif
This does the opposite of #ifdef, i.e. it loads resources if variable is not defined. 
#if comparison
resources
#else
other-resources
#endif
This loads resources if comparison is true. comparison can be a C comparison statement, and can include variables, such as #if WIDTH < 1000 .... 
variable
The value of variable will be substituted. For example, you could use xterm*title: HOST to have the title of all xterm's be the name of the host you are on. 
#include "filename"
This will include the file filename in the resources being loaded as if it were typed right there. Again, the # must be the first character in its line.

Additional X Resources

In addition to the standard X resources supported by practically all applications, some applictions also have additional X resources that can be modified. Below you can find a few applications and some of the x resources you can modify for them. It is by no means a definitive list, nor does it cover all applications, but it should answer most of your needs.

Athena Dash

Here are some customizations you can make to the Athena Dash program. (All resources preceded by Dash*)

autoRaise: logical
If set to true, any menu window from dash will automatically be brought forward to the front of the screen whenever the mouse enters it. (Default: false)
overrideRedirect: logical
This resource sets whether windows in dash are created with override redirect set, an option which most window managers interpret by not letting the user drag around or decorate the window. (Default: on for the Dash menu bar itself, off for any other windows)
rude: logical
Sets whether Dash keeps the mouse grabbed when a menu is opened or not. (Default: true)
verify: logical
Sets whether dash will ask for confirmation before running most menu items. (Default: true)

Emacs

These resources allow you to make cosmetic changes to the powerful and popular emacs text editor. (resources preceded by emacs*)

Font: font
Sets the window's text font. (Default: fixed)
ReverseVideo: logical
If set to on, the window will be displayed in reverse video
iconsUseBitmap: logical
If set to on, the emacs window will iconify to the "kitchen sink"
BorderWidth: number
Sets the width of the window border in pixels
CursorColor: color
Set the color of the text cursor (default: black)
PointerColor: color
Set the color of the window's mouse cursor. (default: black)

EZ

"For the love of God, montressor!"

Mosaic

These are some important resources to change Mosaic, the popular and splufty web browser from NCSA. Enjoy. (All resources preceded by Mosaic*)

annotationsOnTop: logical
Indicates whether to prepend inlined document annotation hyperlinks to the document as opposed to postpending them. (Default: false)
autoPlaceWindows: logical
If this resource is set to false, any new document windows will not be positioned automatically by Mosaic, but rather left for your window manager to handle. (Default: true)
confirmExit: logical
Toggle for whether or not Mosaic prompts you with the window asking that you're really, really sure that you want to quit. (Default: true)
defaultHeight: number
Default height in pixels for a Document view window. (Default: 680)
defaultHotListFile: string
The name of the file that stores the default hotlist. (Default: a file .mosaic-hotlist-default in your home directory)
defaultWidth: number
The default width of a Documents window. (Default: 620)
delayImageLoads: logical
For users with slow net connections or an aversion to graphics loading. When this option is activated, Mosaic will substitute a small representative icon with an additional arrow icon above if it is a link. Clicking the representative icon will load the image, and clicking on the arrow will follow the link. This can also be changed for individual windows from the menu. (Default: false)
fancySelections: logical
Changes the formatting of cut and paste operations performed in the Mosaic document window. (Default: false)
homeDocument: string
The location of the file that Mosaic starts up in when you run it. Use this to start up Mosaic in your home page for instance. (Default here at MIT: "http://www.mit.edu:8001/")
imageCacheSize: logical
Used to set the size of the inlined-image cache in kilobytes. (Default: 2048 Kb)
initialWindowIconic: logical
If set to true, Mosaic will be iconfied when first opened. (Default: false)
printCommand: string
This is the name of the default command used by the Print menu option. This can also be changed in the print options dialog. (Default: "lpr")
reloadReloadsImages: logical
If this option is activated, Mosaic will delete cached image data for a document on a Reload command, meaning it reloads not only text but also graphics. Useful for developers. (Default: false)
simpleInterface: Boolean
Makes Mosaics menu bar and bottom line options much fewer, for the complexly challenged. (Default: false)
trackfullURLs: logical
Activates that neat function of displaying destination URLs when you move the mouse over hotlinks. (Default: true)
trackVisitedAnchors: logical
Will display visited links in a different format from unvisited links if true. (Default: true)

Xclock

Xclock uses the Athena clock widget, and can be modified in the following ways. (Preceded by a xclock*)

width: number (class Width)
Use this resource to specify the width of the clock window in pixels. (Default: 164 for analog clocks, as large as needed for digital)
height: number (class Height)
This resource specifies the height of the clock in pixels. (Default: 164 for analog, and as large as necessary for digital)
update: number (class Interval)
This number specifies the frequency in seconds that the time should be redisplayed and updated.
foreground: color (class Foreground)
This X resource allows you to specify the color of those wonderful tic marks on the clock that let you read the time accurately. (Default: if reversevideo is on, white. Otherwise, it is black.)
hands: color (class Foreground)
Use this resource to specify the color inside the clock hands. (Default: same as for foreground)
highlight: color (class Foreground)
This determines the color of the outside border of those clock hands. (Default: same as for foreground)
analog: boolean (class Boolean)
Toggles whether the clock is analog (true) or digital (false). (Default: true)
chime: boolean (class Boolean)
This resource toggles whether the chime rings on the hour and half hour or not. (Default: true)
padding: number (class Margin)
This resources sets the size of the window margin in pixels. (Default: 8)
font: font (class Font)
Use this to specify the font used for the digital clock.

Xload

Here are a few resources to modify the xload program, used by the really cool computer nerds on campus. It's a great program to impress the desired sex to be sure. (all resources preceded by xload*)
showLabel: Boolean (class Boolean)
This resource toggles whether the machine name is displayed as a label on the load diagram. (Default: true)

Xmh

These let you play with how your xmh looks and acts. (all resources preceded by xmh*)
banner: string
This controls the text at the top of the window. (Default: "xmh MIT X Consortium R5")
compGeometry: coordinates
The size and/or position for composition windows.
draftsFolder: string
The folder used for message drafts. (Default: drafts)
hideBoringHeaders: boolean
If set, then xmh will attempt to skip the boring header lines in a message by scrolling them off the top of the view. (Default: true)
initialFolder: string
Which folder to display on startup. (Default: inbox)
replyInsertFilter: string
A shell (sh) command to be executed when the Insert button is activated in a composition window. The full path and filename of the source message is appended to the command before it is run. You can use something like sed 's/^/> /' to insert "> " in front of each line. (Default: cat)
showOInInc: boolean
Whether to automatically show the first new message after incorporating new mail. (Default: true)
skipCopied: boolean
skipDeleted: boolean
skipMoved: boolean
Sets whether messages which have been marked for copying, deleting, or moving, respectively, will be skipped when view next or previous message is selected. (Default: true)
tocPercentage: number
The percentage of the main window that is use to display the table of contents (Default: 33)

XTerm

Put something in here.
title: string
cursorColor: color (class: Foreground)
(Default: black)
font: font
jumpScroll: boolean
(Default: true)
pointerColor: color (class: Foreground)
pointerColorBackground: color (class: Background)
pointerShape: cursor
(Default: "xterm")
saveLines: number
(Default: 64)
scrollBar: boolean
(Default: false)
scrollTtyOutput: boolean
(Default: true)
scrollKey: boolean
(Default: false)
visualBell: boolean
(Default: false)

Zephyr X Resources

When most people ask me questions about X resources, it's usually to mess around with their zephyrgrams. This is definitely the most popular customization used. (Resources preceded by zwgc*)

cursorCode: number
Number of a code from the cursorfont to use for the windows
pointerColor: color
Primary mouse pointer color (default: foreground color)
reverseVideo: logical
Activates reverse video. (default: off)
borderWidth: number
Use this resource to specify the primary border width in pixels. (default: 1)
internalBorder: number
Width of the primary border width between edge and text. (default: 2)
resetSaver: logical
Force screen to unsave when a message first appears (default: true)
reverseStack: logical
Specifying true here instructs zwgc to attempt to reverse the message stack so that older messages appear on top of the stack. Some window managers may ignore this, and stifle zwgc's attempts to restack, leading to strange results. In other words, not guaranteed. (default: off)
title: string
Primary window title (default: last pathname component of the program name, usually "zwgc")
minTimeToLive: number
This parameter sets the minimum amount of time in milliseconds that a Windowgram must be on screen before it can be destroyed. Very usueful to avoid accidentally clicking away zephyrs.
cursorCode: number
Character number in the cursor font to use for the mouse cursor in zephyr windows; should be even (Default: 8)
style.stylename.geometry: coordinates
style.stylename.background: color
stylename is class.instance.recipient of the zephyrs to be affected, with .'s replaced by _'s and all letters in lowercase. As always, wildcards can be used. Example: zwgc*style.sipb*geometry: -0+0 will display all zephyrs on class sipb in the upper-right corner of the screen.

Troubleshooting

Okay, now that you know everything you could possible care about on X resources, you sit down and hack your X session to be truly hideous. But then you notice something is wrong...

Some general things which might help:

Where to Go for More Info

This document was meant to be only a basic primer in using X resources and not a comprehensive reference. If you want more depth, more resource options, or just a different source, there are several options you can use.

Last modified: Tues Jan 24 1995 by harrisj@mit.edu