Mercurial > emacs

--- a/man/xresmini.texi	Sat Nov 18 14:48:02 2006 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,432 +0,0 @@
-@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 avoid 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