Programs running under the X Window System organize their user options under a hierarchy of classes and resources. You can specify default values for these options in your X resource file, usually named ~/.Xdefaults or ~/.Xresources. Changes in this file do not take effect immediately, because the X server stores its own list of resources; to update it, use the command xrdb—for instance, ‘xrdb ~/.Xdefaults’.
(MS-Windows systems do not support X resource files; on Windows, Emacs looks for X resources in the Windows Registry, first under the key ‘HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs’ and then under the key ‘HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs’. The menu and scroll bars are native widgets on MS-Windows, so they are only customizable via the system-wide settings in the Display Control Panel. You can also set resources using the ‘-xrm’ command line option, as explained below.)
Each line in the X resource file specifies a value for one option or for a collection of related options. Each resource specification consists of a program name and a resource name. Case distinctions are significant in each of these names. Here is an example:
The program name is the name of the executable file to which the resource applies. For Emacs, this is normally ‘emacs’. To specify a definition that applies to all instances of Emacs, regardless of the name of the Emacs executable, use ‘Emacs’.
The resource name is the name of a program setting. For instance, Emacs recognizes a ‘borderWidth’ resource that controls the width of the external border for graphical frames.
Resources are grouped into named classes. For instance, the ‘BorderWidth’ class contains both the ‘borderWidth’ resource (which we just described), as well as the ‘internalBorder’ resource, which controls the width of the internal border for graphical frames. Instead of using a resource name, you can use a class name to specify the same value for all resources in that class. Here's an example:
If you specify a value for a class, it becomes the default for all resources in that class. You can specify values for individual resources as well; these override the class value, for those particular resources. The following example specifies 2 as the default width for all borders, but overrides this value with 4 for the external border:
emacs.BorderWidth: 2 emacs.borderWidth: 4
The order in which the lines appear in the file does not matter.
One way to experiment with the effect of different resource settings
is to use the
editres program. See the
editres man page
for more details.
Emacs does not process X resources at all if you set the variable
inhibit-x-resources to a non-
nil value, or if you
specify the ‘-Q’ (or ‘--quick’) command-line argument
(see Initial Options). (The ‘-Q’ argument automatically sets
In addition, you can use the following command-line options to override the X resources file:
If you don't specify this option, the default is to use the Emacs executable's name as the program name.
For consistency, ‘-name’ also specifies the name to use for other resource values that do not belong to any particular frame.
The resources that name Emacs invocations also belong to a class,
named ‘Emacs’. If you write ‘Emacs’ instead of
‘emacs’, the resource applies to all frames in all Emacs jobs,
regardless of frame titles and regardless of the name of the
resource-values should have the same format that you would use inside a file of X resources. To include multiple resource specifications in resource-values, put a newline between them, just as you would in a file. You can also use ‘#include "filename"’ to include a file full of resource specifications. Resource values specified with ‘-xrm’ take precedence over all other resource specifications.