mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-24 10:38:38 +00:00
433 lines
15 KiB
Plaintext
433 lines
15 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003,
|
|
@c 2004, 2005, 2006 Free Software Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node X Resources, Antinews, Emacs Invocation, Top
|
|
@appendix 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.
|
|
@xref{MS-Windows Registry}. Likewise, Emacs on MacOS Carbon emulates X
|
|
resources using the Preferences system. @xref{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.
|
|
|
|
@c Add xref for LessTif/Motif menu resources.
|
|
|
|
@menu
|
|
* Resources:: Using X resources with Emacs (in general).
|
|
* Table of Resources:: Table of specific X resources that affect Emacs.
|
|
* Face Resources:: X resources for customizing faces.
|
|
* Lucid Resources:: X resources for Lucid menus.
|
|
* GTK resources:: Resources for GTK widgets.
|
|
@end menu
|
|
|
|
@node Resources
|
|
@appendixsec X Resources
|
|
@cindex resources
|
|
@cindex X resources
|
|
@cindex @file{~/.Xdefaults} file
|
|
@cindex @file{~/.Xresources} file
|
|
|
|
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 @file{~/.Xdefaults} or @file{~/.Xresources}.
|
|
If changes in @file{~/.Xdefaults} do not
|
|
take effect, it is because your X server stores its own list of
|
|
resources; to update them, use the shell command @command{xrdb}---for
|
|
instance, @samp{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).
|
|
|
|
@cindex Registry (MS-Windows)
|
|
MS-Windows systems don't support @file{~/.Xdefaults} files, but
|
|
Emacs compiled for Windows looks for X resources in the Windows
|
|
Registry, under the key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}
|
|
and then under the key @samp{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 @samp{-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 @file{~/.Xdefaults}
|
|
states the name of the program and the name of the resource. For
|
|
Emacs, the program name is @samp{Emacs}. It looks like this:
|
|
|
|
@example
|
|
Emacs.borderWidth: 2
|
|
@end example
|
|
|
|
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 @code{editres} program. Select @samp{Get Tree} from the
|
|
@samp{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 @samp{menubar}, then select
|
|
@samp{Show Resource Box} from the @samp{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
|
|
@samp{Apply} button. (See the @code{editres} man page for more
|
|
details.)
|
|
|
|
@node Table of Resources
|
|
@appendixsec 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:
|
|
|
|
@table @asis
|
|
@item @code{background} (class @code{Background})
|
|
Background color name.
|
|
|
|
@item @code{borderColor} (class @code{BorderColor})
|
|
Color name for the external border.
|
|
|
|
@item @code{cursorColor} (class @code{Foreground})
|
|
Color name for text cursor (point).
|
|
|
|
@item @code{font} (class @code{Font})
|
|
Font name (or fontset name, @pxref{Fontsets}) for @code{default} font.
|
|
|
|
@item @code{foreground} (class @code{Foreground})
|
|
Color name for text.
|
|
|
|
@item @code{geometry} (class @code{Geometry})
|
|
Window size and position. Be careful not to specify this resource as
|
|
@samp{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.
|
|
|
|
@item @code{iconName} (class @code{Title})
|
|
Name to display in the icon.
|
|
|
|
@item @code{internalBorder} (class @code{BorderWidth})
|
|
Width in pixels of the internal border.
|
|
|
|
@item @code{lineSpacing} (class @code{LineSpacing})
|
|
@cindex line spacing
|
|
@cindex leading
|
|
Additional space (@dfn{leading}) between lines, in pixels.
|
|
|
|
@item @code{menuBar} (class @code{MenuBar})
|
|
@cindex menu bar
|
|
Give frames menu bars if @samp{on}; don't have menu bars if
|
|
@samp{off}. @xref{Lucid Resources}, for how to control the appearance
|
|
of the menu bar if you have one.
|
|
|
|
@item @code{pointerColor} (class @code{Foreground})
|
|
Color of the mouse cursor.
|
|
|
|
@item @code{screenGamma} (class @code{ScreenGamma})
|
|
@cindex gamma correction
|
|
Gamma correction for colors, equivalent to the frame parameter
|
|
@code{screen-gamma}.
|
|
|
|
@item @code{title} (class @code{Title})
|
|
Name to display in the title bar of the initial Emacs frame.
|
|
|
|
@item @code{toolBar} (class @code{ToolBar})
|
|
@cindex tool bar
|
|
Number of lines to reserve for the tool bar. A zero value suppresses
|
|
the tool bar. If the value is non-zero and
|
|
@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
|
|
will be changed automatically so that all tool bar items are visible.
|
|
|
|
@item @code{useXIM} (class @code{UseXIM})
|
|
@cindex XIM
|
|
@cindex X input methods
|
|
@cindex input methods, X
|
|
Turn off use of X input methods (XIM) if @samp{false} or @samp{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.
|
|
|
|
@item @code{verticalScrollBars} (class @code{ScrollBars})
|
|
Give frames scroll bars if @samp{on}; don't have scroll bars if
|
|
@samp{off}.
|
|
@end table
|
|
|
|
@node Face Resources
|
|
@appendixsec X Resources for Faces
|
|
|
|
You can use resources to customize the appearance of particular
|
|
faces (@pxref{Faces}):
|
|
|
|
@table @code
|
|
@item @var{face}.attributeForeground
|
|
Foreground color for face @var{face}.
|
|
@item @var{face}.attributeBackground
|
|
Background color for face @var{face}.
|
|
@item @var{face}.attributeUnderline
|
|
Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
|
|
yes.
|
|
@item @var{face}.attributeStrikeThrough
|
|
@itemx @var{face}.attributeOverline
|
|
@itemx @var{face}.attributeBox
|
|
@itemx @var{face}.attributeInverse
|
|
Likewise, for other boolean font attributes.
|
|
@item @var{face}.attributeStipple
|
|
The name of a pixmap data file to use for the stipple pattern, or
|
|
@code{false} to not use stipple for the face @var{face}.
|
|
@item @var{face}.attributeBackgroundPixmap
|
|
The background pixmap for the face @var{face}. Should be a name of a
|
|
pixmap file or @code{false}.
|
|
@item @var{face}.attributeFont
|
|
Font name (full XFD name or valid X abbreviation) for face @var{face}.
|
|
Instead of this, you can specify the font through separate attributes.
|
|
@end table
|
|
|
|
Instead of using @code{attributeFont} to specify a font name, you can
|
|
select a font through these separate attributes:
|
|
|
|
@table @code
|
|
@item @var{face}.attributeFamily
|
|
Font family for face @var{face}.
|
|
@item @var{face}.attributeHeight
|
|
Height of the font to use for face @var{face}: either an integer
|
|
specifying the height in units of 1/10@dmn{pt}, 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.
|
|
@item @var{face}.attributeWidth
|
|
@itemx @var{face}.attributeWeight
|
|
@itemx @var{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.
|
|
@item @var{face}.attributeBold
|
|
Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for
|
|
yes.
|
|
@item @var{face}.attributeItalic
|
|
Italic flag for face @var{face}---instead of @code{attributeSlant}.
|
|
@end table
|
|
|
|
@node Lucid Resources
|
|
@appendixsec Lucid Menu X Resources
|
|
@cindex Menu X Resources (Lucid widgets)
|
|
@cindex Lucid Widget 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
|
|
@samp{Emacs.pane.menubar}---for instance, to specify the font
|
|
@samp{8x16} for the menu-bar items, write this:
|
|
|
|
@example
|
|
Emacs.pane.menubar.font: 8x16
|
|
@end example
|
|
|
|
@noindent
|
|
Resources for @emph{non-menubar} toolkit pop-up menus have
|
|
@samp{menu*} instead of @samp{pane.menubar}. For example, to specify
|
|
the font @samp{8x16} for the pop-up menu items, write this:
|
|
|
|
@example
|
|
Emacs.menu*.font: 8x16
|
|
@end example
|
|
|
|
@noindent
|
|
For dialog boxes, use @samp{dialog*}:
|
|
|
|
@example
|
|
Emacs.dialog*.font: 8x16
|
|
@end example
|
|
|
|
@noindent
|
|
The Lucid menus can display multilingual text in your locale. For
|
|
more information about fontsets see the man page for
|
|
@code{XCreateFontSet}. To enable multilingual menu text you specify a
|
|
@code{fontSet} resource instead of the font resource. If both
|
|
@code{font} and @code{fontSet} resources are specified, the
|
|
@code{fontSet} resource is used.
|
|
|
|
Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*}
|
|
for both the popup and menu bar menus, write this:
|
|
|
|
@example
|
|
Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*
|
|
@end example
|
|
|
|
@noindent
|
|
The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and
|
|
@samp{menu@dots{}}.
|
|
|
|
Experience shows that on some systems you may need to add
|
|
@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
|
|
some other systems, you must not add @samp{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:
|
|
|
|
@table @code
|
|
@item font
|
|
Font for menu item text.
|
|
@item fontSet
|
|
Fontset for menu item text.
|
|
@item foreground
|
|
Color of the foreground.
|
|
@item background
|
|
Color of the background.
|
|
@item buttonForeground
|
|
In the menu bar, the color of the foreground for a selected item.
|
|
@item margin
|
|
The margin of the menu bar, in characters. Default is 1.
|
|
@end table
|
|
|
|
@node GTK resources
|
|
@appendixsec 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 @file{~/.emacs.d/gtkrc}. Some GTK
|
|
themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything
|
|
works with all themes. To customize Emacs font, background, faces, etc., use
|
|
the normal X resources (@pxref{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:
|
|
|
|
@smallexample
|
|
gtk-font-name = "courier 12"
|
|
@end smallexample
|
|
|
|
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:
|
|
|
|
@smallexample
|
|
gtk-font-name = "helvetica bold 10"
|
|
@end smallexample
|
|
|
|
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:
|
|
|
|
@smallexample
|
|
# @r{Define the style @samp{menufont}.}
|
|
style "menufont"
|
|
@{
|
|
font_name = "helvetica bold 14" # This is a Pango font name
|
|
@}
|
|
|
|
# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
|
|
widget "*emacs-menuitem*" style "menufont"
|
|
@end smallexample
|
|
|
|
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:
|
|
|
|
@smallexample
|
|
widget "Emacs.pane.menubar" style "my_style"
|
|
widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
|
|
@end smallexample
|
|
|
|
But to aoid having to type it all, wildcards are often used. @samp{*}
|
|
matches zero or more characters and @samp{?} 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:
|
|
|
|
@smallexample
|
|
style "menufont"
|
|
@{
|
|
font_name = "helvetica bold 14"
|
|
@}
|
|
|
|
widget_class "*GtkMenuBar" style "menufont"
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The names and classes for the GTK widgets Emacs uses are:
|
|
|
|
@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
|
|
@item @code{emacs-filedialog}
|
|
@tab @code{GtkFileSelection}
|
|
@item @code{emacs-dialog}
|
|
@tab @code{GtkDialog}
|
|
@item @code{Emacs}
|
|
@tab @code{GtkWindow}
|
|
@item @code{pane}
|
|
@tab @code{GtkVHbox}
|
|
@item @code{emacs}
|
|
@tab @code{GtkFixed}
|
|
@item @code{verticalScrollBar}
|
|
@tab @code{GtkVScrollbar}
|
|
@item @code{emacs-toolbar}
|
|
@tab @code{GtkToolbar}
|
|
@item @code{menubar}
|
|
@tab @code{GtkMenuBar}
|
|
@item @code{emacs-menuitem}
|
|
@tab anything in menus
|
|
@end multitable
|
|
|
|
GTK absolute names are quite strange when it comes to menus
|
|
and dialogs. The names do not start with @samp{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:
|
|
|
|
@smallexample
|
|
widget "*emacs-dialog*" style "my_dialog_style"
|
|
widget "*emacs-filedialog* style "my_file_style"
|
|
widget "*emacs-menuitem* style "my_menu_style"
|
|
@end smallexample
|
|
|
|
If you specify a customization in @file{~/.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
|
|
@file{~/.emacs.d/gtkrc}:
|
|
|
|
@smallexample
|
|
widget_class "*Menu*" style "my_menu_style"
|
|
@end smallexample
|
|
|
|
Here is a more elaborate example, showing how to change the parts of
|
|
the scroll bar:
|
|
|
|
@smallexample
|
|
style "scroll"
|
|
@{
|
|
fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
|
|
bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
|
|
bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
|
|
bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
|
|
@}
|
|
|
|
widget "*verticalScrollBar*" style "scroll"
|
|
@end smallexample
|
|
|
|
@ignore
|
|
arch-tag: e1856f29-2482-42c0-a990-233cdccd1f21
|
|
@end ignore
|