[Emacs-diffs] Changes to emacs/man/xresmini.texi

[Jan Djärv]

Index: emacs/man/xresmini.texi
diff -u emacs/man/xresmini.texi:1.3 emacs/man/xresmini.texi:1.4
--- emacs/man/xresmini.texi:1.3 Sat May  6 15:50:25 2006
+++ emacs/man/xresmini.texi     Sun May  7 19:38:49 2006
@@ -296,7 +296,136 @@
 @node GTK resources
 @appendixsec GTK resources
 
address@hidden  Waiting for contents
+  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:
+
address@hidden
+gtk-font-name = "courier 12"
address@hidden 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:
+
address@hidden
+gtk-font-name = "helvetica bold 10"
address@hidden 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:
+
address@hidden
+# @r{Define the style @samp{menufont}.}
+style "menufont"
address@hidden
+  font_name = "helvetica bold 14"  # This is a Pango font name
address@hidden
+
+# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
+widget "*emacs-menuitem*" style "menufont"
address@hidden 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:
+
address@hidden
+widget "Emacs.pane.menubar" style "my_style"
+widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
address@hidden 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:
+
address@hidden
+style "menufont"
address@hidden
+  font_name = "helvetica bold 14"
address@hidden
+
+widget_class "*GtkMenuBar" style "menufont"
address@hidden smallexample
+
address@hidden
+The names and classes for the GTK widgets Emacs uses are:
+
address@hidden address@hidden plus}} address@hidden and some}
address@hidden @code{emacs-filedialog}
address@hidden @code{GtkFileSelection}
address@hidden @code{emacs-dialog}
address@hidden @code{GtkDialog}
address@hidden @code{Emacs}
address@hidden @code{GtkWindow}
address@hidden @code{pane}
address@hidden @code{GtkVHbox}
address@hidden @code{emacs}
address@hidden @code{GtkFixed}
address@hidden @code{verticalScrollBar}
address@hidden @code{GtkVScrollbar}
address@hidden @code{emacs-toolbar}
address@hidden @code{GtkToolbar}
address@hidden @code{menubar}
address@hidden @code{GtkMenuBar}
address@hidden @code{emacs-menuitem}
address@hidden anything in menus
address@hidden 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:
+
address@hidden
+widget "*emacs-dialog*" style "my_dialog_style"
+widget "*emacs-filedialog* style "my_file_style"
+widget "*emacs-menuitem* style "my_menu_style"
address@hidden 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
address@hidden/.emacs.d/gtkrc}:
+
address@hidden
+widget_class "*Menu*" style "my_menu_style"
address@hidden smallexample
+
+  Here is a more elaborate example, showing how to change the parts of
+the scroll bar:
+
address@hidden
+style "scroll"
address@hidden
+  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.}
address@hidden
+
+widget "*verticalScrollBar*" style "scroll"
address@hidden smallexample
 
 @ignore
    arch-tag: e1856f29-2482-42c0-a990-233cdccd1f21