X Options and Resources
***********************

You can customize some X-related aspects of Emacs behavior using X resources, as is usual for programs that use X.  On MS-Windows, you can customize some of the same aspects using the system registry. See MS-Windows Registry.  Likewise, Emacs on MacOS Carbon emulates X resources using the Preferences system.  See Mac Environment Variables.

When Emacs is built using an ``X toolkit'', such as Lucid or LessTif, you need to use X resources to customize the appearance of the widgets, including the menu-bar, scroll-bar, and dialog boxes. This is because the libraries that implement these don't provide for customization through Emacs.  GTK+ widgets use a separate system of ``GTK resources''.  In this chapter we describe the most commonly used resource specifications.  For full documentation, see the online manual.

X Resources
===========

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 resources file, usually named ~/.Xdefaults or ~/.Xresources. If changes in ~/.Xdefaults do not take effect, it is because your X server stores its own list of resources; to update them, use the shell command xrdb---for instance, xrdb ~/.Xdefaults.

Each line in the file specifies a value for one option or for a collection of related options, for one program or for several programs (optionally even for all programs).

MS-Windows systems don't support ~/.Xdefaults files, but Emacs compiled for Windows looks for X resources in the Windows Registry, under the key HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs and then under the key HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs. The menu and scrollbars 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 (see below.)

Applications such as Emacs look for resources with specific names and their particular meanings.  Case distinctions are significant in these names.  Each resource specification in ~/.Xdefaults states the name of the program and the name of the resource.  For Emacs, the program name is Emacs.  It looks like this:

     Emacs.borderWidth: 2

The order in which the lines appear in the file does not matter. Also, command-line options always override the X resources file.

You can experiment with the effect of different resource settings with the editres program.  Select Get Tree from the Commands menu, then click on an Emacs frame.  This will display a tree showing the structure of X toolkit widgets used in an Emacs frame.  Select one of them, such as menubar, then select Show Resource Box from the Commands menu.  This displays a list of all the meaningful X resources for that widget, and allows you to edit them.  Changes take effect when you click on the Apply button.  (See the editres man page for more details.)

Table of X Resources for Emacs
==============================

This table lists the resource names that designate options for Emacs, not counting those for the appearance of the menu bar, each with the class that it belongs to:

background (class Background)
     Background color name.

borderColor (class BorderColor)
     Color name for the external border.

cursorColor (class Foreground)
     Color name for text cursor (point).

font (class Font)
     Font name (or fontset name, see Fontsets) for default font.

foreground (class Foreground)
     Color name for text.

geometry (class Geometry)
     Window size and position.  Be careful not to specify this resource as emacs*geometry, because that may affect individual menus as well as the Emacs frame itself.

     If this resource specifies a position, that position applies only to the initial Emacs frame (or, in the case of a resource for a specific frame name, only that frame).  However, the size, if specified here, applies to all frames.

iconName (class Title)
     Name to display in the icon.

internalBorder (class BorderWidth)
     Width in pixels of the internal border.

lineSpacing (class LineSpacing)
     Additional space (leading) between lines, in pixels.

menuBar (class MenuBar)
     Give frames menu bars if on; don't have menu bars if off.  See Lucid Resources, for how to control the appearance of the menu bar if you have one.

pointerColor (class Foreground)
     Color of the mouse cursor.

screenGamma (class ScreenGamma)
     Gamma correction for colors, equivalent to the frame parameter screen-gamma.

title (class Title)
     Name to display in the title bar of the initial Emacs frame.

toolBar (class ToolBar)
     Number of lines to reserve for the tool bar.  A zero value suppresses the tool bar.  If the value is non-zero and auto-resize-tool-bars is non-nil, the tool bar's size will be changed automatically so that all tool bar items are visible.

useXIM (class UseXIM)
     Turn off use of X input methods (XIM) if false or off. This is only relevant if your Emacs is actually built with XIM support.  It is potentially useful to turn off XIM for efficiency, especially slow X client/server links.

verticalScrollBars (class ScrollBars)
     Give frames scroll bars if on; don't have scroll bars if off.

X Resources for Faces
=====================

You can use resources to customize the appearance of particular faces (see Faces):

FACE.attributeForeground
     Foreground color for face FACE.

FACE.attributeBackground
     Background color for face FACE.

FACE.attributeUnderline
     Underline flag for face FACE.  Use on or true for yes.

FACE.attributeStrikeThrough
FACE.attributeOverline
FACE.attributeBox
FACE.attributeInverse
     Likewise, for other boolean font attributes.

FACE.attributeStipple
     The name of a pixmap data file to use for the stipple pattern, or false to not use stipple for the face FACE.

FACE.attributeBackgroundPixmap
     The background pixmap for the face FACE.  Should be a name of a pixmap file or false.

FACE.attributeFont
     Font name (full XFD name or valid X abbreviation) for face FACE. Instead of this, you can specify the font through separate attributes.

Instead of using attributeFont to specify a font name, you can select a font through these separate attributes:

FACE.attributeFamily
     Font family for face FACE.

FACE.attributeHeight
     Height of the font to use for face FACE: either an integer specifying the height in units of 1/10pt, or a floating point number that specifies a scale factor to scale the underlying face's default font, or a function to be called with the default height which will return a new height.

FACE.attributeWidth
FACE.attributeWeight
FACE.attributeSlant
     Each of these resources corresponds to a like-named font attribute, and you write the resource value the same as the symbol you would use for the font attribute value.

FACE.attributeBold
     Bold flag for face FACE---instead of attributeWeight.  Use on or true for yes.

FACE.attributeItalic
     Italic flag for face FACE---instead of attributeSlant.

Lucid Menu X Resources
======================

If the Emacs installed at your site was built to use the X toolkit with the Lucid menu widgets, then the menu bar is a separate widget and has its own resources.  The resource specifications start with Emacs.pane.menubar---for instance, to specify the font 8x16 for the menu-bar items, write this:

     Emacs.pane.menubar.font:  8x16

Resources for non-menubar toolkit pop-up menus have menu* instead of pane.menubar.  For example, to specify the font 8x16 for the pop-up menu items, write this:

     Emacs.menu*.font:	8x16

For dialog boxes, use dialog*:

     Emacs.dialog*.font:	8x16

The Lucid menus can display multilingual text in your locale.  For more information about fontsets see the man page for XCreateFontSet.  To enable multilingual menu text you specify a fontSet resource instead of the font resource.  If both font and fontSet resources are specified, the fontSet resource is used.

Thus, to specify -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* for both the popup and menu bar menus, write this:

     Emacs*menu*fontSet:  -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*

The *menu* as a wildcard matches pane.menubar and menu....

Experience shows that on some systems you may need to add shell. before the pane.menubar or menu*.  On some other systems, you must not add shell..  The generic wildcard approach should work on both kinds of systems.

Here is a list of the specific resources for menu bars and pop-up menus:

font
     Font for menu item text.

fontSet
     Fontset for menu item text.

foreground
     Color of the foreground.

background
     Color of the background.

buttonForeground
     In the menu bar, the color of the foreground for a selected item.

margin
     The margin of the menu bar, in characters.  Default is 1.

GTK resources
=============

The most common way to customize the GTK widgets Emacs uses (menus, dialogs tool bars and scroll bars) is by choosing an appropriate theme, for example with the GNOME theme selector.  You can also do Emacs specific customization by inserting GTK style directives in the file ~/.emacs.d/gtkrc.  Some GTK themes ignore customizations in ~/.emacs.d/gtkrc so not everything works with all themes.  To customize Emacs font, background, faces, etc., use the normal X resources (see Resources).  We will present some examples of customizations here, but for a more detailed description, see the online manual.

The first example is just one line.  It changes the font on all GTK widgets to courier with size 12:

     gtk-font-name = "courier 12"

The thing to note is that the font name is not an X font name, like -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name.  A Pango font name is basically of the format "family style size", where the style is optional as in the case above.  A name with a style could be for example:

     gtk-font-name = "helvetica bold 10"

To customize widgets you first define a style and then apply the style to the widgets.  Here is an example that sets the font for menus, but not for other widgets:

     # Define the style menufont.
     style "menufont"
     {
       font_name = "helvetica bold 14"  # This is a Pango font name
     }

     # Specify that widget type *emacs-menuitem* uses menufont.
     widget "*emacs-menuitem*" style "menufont"

The widget name in this example contains wildcards, so the style will be applied to all widgets that match "*emacs-menuitem*".  The widgets are named by the way they are contained, from the outer widget to the inner widget. So to apply the style "my_style" (not shown) with the full, absolute name, for the menubar and the scroll bar in Emacs we use:

     widget "Emacs.pane.menubar" style "my_style"
     widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"

But to aoid having to type it all, wildcards are often used.  * matches zero or more characters and ? matches one character.  So "*" matches all widgets.

Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem). You can assign styles by name or by class.  In this example we have used the class:

     style "menufont"
     {
       font_name = "helvetica bold 14"
     }

     widget_class "*GtkMenuBar" style "menufont"

The names and classes for the GTK widgets Emacs uses are:

emacs-filedialog
GtkFileSelection
emacs-dialog
GtkDialog
Emacs
GtkWindow
pane
GtkVHbox
emacs
GtkFixed
verticalScrollBar
GtkVScrollbar
emacs-toolbar
GtkToolbar
menubar
GtkMenuBar
emacs-menuitem
anything in menus

GTK absolute names are quite strange when it comes to menus and dialogs.  The names do not start with Emacs, as they are free-standing windows and not contained (in the GTK sense) by the Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:

     widget "*emacs-dialog*" style "my_dialog_style"
     widget "*emacs-filedialog* style "my_file_style"
     widget "*emacs-menuitem* style "my_menu_style"

If you specify a customization in ~/.emacs.d/gtkrc, then it automatically applies only to Emacs, since other programs don't read that file.  For example, the drop down menu in the file dialog can not be customized by any absolute widget name, only by an absolute class name.  This is because the widgets in the drop down menu do not have names and the menu is not contained in the Emacs GtkWindow.  To have all menus in Emacs look the same, use this in ~/.emacs.d/gtkrc:

     widget_class "*Menu*" style "my_menu_style"

Here is a more elaborate example, showing how to change the parts of the scroll bar:

     style "scroll"
     {
       fg[NORMAL] = "red"     # The arrow color.
       bg[NORMAL] = "yellow"  # The thumb and background around the arrow.
       bg[ACTIVE] = "blue"    # The trough color.
       bg[PRELIGHT] = "white" # The thumb color when the mouse is over it.
     }

     widget "*verticalScrollBar*" style "scroll"