From: Richard M. Stallman Date: Sun, 23 Apr 2006 21:51:55 +0000 (+0000) Subject: New file, a shortened version of xresmini.texi. X-Git-Tag: emacs-pretest-22.0.90~2980 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2018683fd4a4e59458ac812b1848068d470f0c74;p=emacs.git New file, a shortened version of xresmini.texi. --- diff --git a/man/xresmini.texi b/man/xresmini.texi new file mode 100644 index 00000000000..d25be5e1091 --- /dev/null +++ b/man/xresmini.texi @@ -0,0 +1,299 @@ +@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}, and @ref{LessTif 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 + +@c Waiting for contents