Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/xresmini.texi	Sun Apr 23 21:51:55 2006 +0000
@@ -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