Index: man/xresources.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/xresources.texi,v
retrieving revision 1.13
diff -c -c -r1.13 xresources.texi
*** man/xresources.texi	6 Jan 2003 01:03:44 -0000	1.13
--- man/xresources.texi	9 Jan 2003 20:46:30 -0000
***************
*** 18,23 ****
--- 18,24 ----
  * Face Resources::      X resources for customizing faces.
  * Lucid Resources::     X resources for Lucid menus.
  * LessTif Resources::   X resources for LessTif and Motif menus.
+ * GTK resources::       Resources for GTK widgets.
  @end menu
  
  @node Resources
***************
*** 520,522 ****
--- 521,858 ----
  @item topShadowColor
  The color for the border shadow, on the top and the left.
  @end table
+ 
+ @node GTK resources, GTK widget paths, LessTif Resources, X Resources
+ @appendixsec GTK resources
+ @cindex GTK resources
+ @cindex GTK customize
+ @cindex GTK resource files
+ @cindex @file{~/.gtkrc-2.0} file
+ @cindex @file{~/emacs.d/gtkrc} file
+ 
+   If the Emacs installed at your site was built to use the GTK widget set,
+ then the menu bar, scroll bar and the dialogs can be customized with
+ the standard GTK @file{~/.gtkrc-2.0} file or with the Emacs specific
+ @file{~/.emacs.d/gtkrc} file.  Note that this is only for 
+ customizing specific GTK widget features.  To customize Emacs font,
+ background, faces etc., use the normal X resources, see @ref{Resources}.
+ 
+ In these files one first defines a style and then apply that style 
+ to widget paths.  Here is an example of how to change the font for
+ Emacs menus:
+ 
+ @smallexample
+ # This is a comment.
+ style "menufont"
+ @{
+   font_name = "helvetica bold 14"  # This is a Pango font name
+ @}
+ 
+ widget "*emacs-menuitem*" style "menufont"
+ 
+ @end smallexample
+ 
+   There are some items you can set without using any style or widget path,
+ that affects GTK as a whole.  Most of these are poorly documented but
+ can be found as properties in the documentation for @code{GtkSetting} in the
+ GTK document references below.
+ One property of interest is gtk-font-name which sets
+ a default font.  You have to use Pango font names, see @ref{GTK styles}.
+ A @file{~/.gtkrc-2.0} file that just sets a default font looks like this:
+ @smallexample
+ gtk-font-name = "courier 12"
+ @end smallexample
+ 
+ 
+   The syntax for GTK resource files is fully described in the GTK
+ API reference manual.  You may have this on your site as:
+ 
+ @file{prefix/share/gtk-doc/html/gtk/gtk-resource-files.html},
+ 
+ @noindent
+ where ``prefix'' is where GTK is installed, usually @file{/usr}.
+ You can find this online at
+  
+ @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
+ 
+ 
+ @menu
+ * GTK widget paths::      How widgets in GTK are named in general.
+ * GTK names in Emacs::    GTK widget names in Emacs.
+ * GTK styles::            What can be customized in a GTK widget.
+ @end menu
+ 
+ 
+ @node GTK widget paths, GTK names in Emacs, GTK resources, GTK resources
+ @appendixsec GTK widget paths
+ @cindex GTK widget names
+ @cindex GTK widget classes
+ 
+ Widgets can be specified by widget class or by
+ widget name.  Widgets have pathnames made from how they are contained.
+ For example, if a @code{GtkWindow} contains a @code{GtkVBox} which in turn
+ contains a @code{GtkMenuBar}, the class path would then be:
+ @smallexample
+ GtkWindow.GtkVBox.GtkMenuBar
+ @end smallexample
+ 
+ @noindent
+ If the widgets are named ``top'', ``box'' and ``menubar'', the widget
+ path then becomes:
+ @smallexample
+ top.box.menubar
+ @end smallexample
+ 
+   When assigning a style to a path, one can use the class path,
+ the widget path, or a mixture of both.  The key word 
+ @code{widget_class} matches only against the class path.  The key word
+ @code{widget} matches first against the name and secondly against the
+ class.
+ 
+   Matching is done with shell ``glob'' syntax, that is *
+ matches zero or more characters, ? matches one character.  So
+ this assigns @code{base_style} to all widgets:
+ 
+ @smallexample
+ widget "*" style "base_style"
+ @end smallexample
+ 
+   Given the class path @code{GtkWindow.GtkVBox.GtkMenuBar} and the widget
+ path @code{top.box.menubar}, these all assign @code{my_style} to the menu bar:
+ 
+ @smallexample
+ widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
+ widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
+ widget_class "*GtkMenuBar" style "my_style"
+ widget "GtkWindow*menubar" style "my_style"
+ widget "*top.menubar" style "my_style"
+ widget "*menubar" style "my_style"
+ widget "*menu*" style "my_style"
+ @end smallexample
+ 
+ @node GTK names in Emacs, GTK styles, GTK widget paths, GTK resources
+ @appendixsec GTK names in Emacs
+ @cindex GTK widget names
+ @cindex GTK widget classes
+ 
+   In Emacs the top level widget for a frame is a @code{GtkWindow} that
+ contains a @code{GtkVBox}.  The @code{GtkVBox} contains the 
+ @code{GtkMenuBar} and a @code{GtkFixed} widget.  
+ The vertical scroll bars, @code{GtkVScrollbar},
+ are contained in the @code{GtkFixed} widget.
+ The text you write in Emacs is drawn in the @code{GtkFixed} widget.
+ 
+   Dialogs in Emacs are @code{GtkDialog} widgets.  The file dialog is a
+ @code{GtkFileSelection} widget.
+ 
+ @noindent
+ To set a style for the menu bar using the full class path, use:
+ 
+ @smallexample
+ widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
+ @end smallexample
+ 
+ @noindent
+ And for the scroll bar, the full path is:
+ 
+ @smallexample
+ widget_class 
+   "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
+      style "my_style"
+ @end smallexample
+ 
+   The names for the widgets are:
+ 
+ @multitable address@hidden and some} address@hidden plus}}
+ @item @code{GtkFileSelection}
+ @tab @code{emacs-filedialog}
+ @item @code{GtkDialog}
+ @tab @code{emacs-dialog}
+ @item @code{GtkWindow}
+ @tab @code{Emacs}
+ @item @code{GtkVHbox}
+ @tab @code{pane}
+ @item @code{GtkFixed}
+ @tab @code{emacs}
+ @item @code{GtkMenuBar}
+ @tab @code{menubar}
+ @item @code{GtkVScrollbar}
+ @tab @code{verticalScrollbar}
+ @item anything in menus
+ @tab @code{emacs-menuitem}
+ @end multitable
+ 
+   Thus, for Emacs you can write the two examples above as:
+ 
+ @smallexample
+ widget "Emacs.pane.menubar" style "my_style"
+ widget "Emacs.pane.emacs.verticalScrollbar" style "my_style"
+ @end smallexample
+ 
+   GTK absolute paths are quite strange when it comes to menus
+ and dialogs.  The paths do not start with 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
+ 
+   An alternative is to put customization into @file{~/.emacs.d/gtkrc}.
+ This file is only read by Emacs, so anything in it affects Emacs but
+ leaves other applications unaffected.
+ For example, the drop down menu in the file dialog can not
+ be customized by any widget path, only by a class path.  It does not
+ have a name and it is not contained by the Emacs GtkWindow.
+ To have all menus in Emacs look the same, use:
+ 
+ @smallexample
+ widget "*Menu*" style "my_menu_style"
+ @end smallexample
+ 
+ @node GTK styles,  , GTK names in Emacs, GTK resources
+ @appendixsec GTK styles
+ @cindex GTK style
+ 
+   This is mostly taken from the GTK reference documentation.
+ Within a style declaration, the possible elements are:
+ 
+ @table @code
+ @item bg[state] = color
+ Sets the color used for the background of most widgets.  The widget where
+ you edit text in Emacs ignores this.  Use X resources (i.e.
+ @code{Emacs.background: color}) for this, see @ref{Resources}.  The values
+ for @code{state} are enumerated below.
+ 
+ @item fg[state] = color
+ Sets the color used for the foreground of most widgets.  The widget where
+ you edit text in Emacs ignores this.  Use X resources (i.e.
+ @code{Emacs.foreground: color}) for this, see @ref{Resources}.
+ 
+ @item base[state] = color
+ Sets the color used for the background of widgets displaying editable
+ text. In Emacs, this color is used for the background of the text
+ fields in the file dialog.
+ 
+ @item text[state] = color
+ Sets the color used for foreground of widgets using base for the background
+ color.  In Emacs, this color is used for the text color in
+ fields in the file dialog.
+ 
+ @item bg_pixmap[state] = pixmap
+ Sets a background pixmap to be used in place of the background color.
+ The special value @code{<parent>}
+ may be used to indicate that the widget should use the same background
+ pixmap as its parent. The special value @code{<none>} may be used to
+ indicate no background pixmap.
+ 
+   The place to find the pixmap seems
+ to be the directory where the gtkrc file is.  So if you have this
+ in @file{~/.emacs.d/gtkrc}, the pixmap is looked for in
+ @file{~/.emacs.d}.  It does not seem possible to refer to a
+ file by its absolute path name.
+ 
+ @item font_name = font
+ Sets the font for a widget.  The font must be a Pango font name,
+ for example ``Sans Italic 10'', ``Helvetica Bold 12'', ``Courier 14'',
+ ``Times 18''.  See below for exact syntax.  The names are case insensitive.
+ @end table
+ 
+   The colors and background pixmaps are specified as a function of the state
+ of the widget. The states are:
+ 
+ @table @code
+ @item NORMAL
+ A color used for a widget in its normal state.
+ @item ACTIVE
+ A variant of the @code{NORMAL} color used when the widget is in the
+ active state, and also for the trough of a scroll bar, i.e.
+ @code{bg[ACTIVE] = "red"} sets the scroll bar trough to red.
+ Buttons that have been pressed but not released yet (``armed'') are in
+ active state.
+ @item PRELIGHT
+ A color used for widgets in the prelight state. This state is
+ the used for buttons and menu items that have the mouse cursor over them.
+ Also when the mouse is over the thumb in the scroll bar.
+ @item SELECTED
+ A color used to highlight data selected by the user. for instance, 
+ the selected items in a list widget, and the selection in an editable widget.
+ There is no place in Emacs where this setting has any effect.
+ @item INSENSITIVE
+ A color used for the background of widgets that have been set insensitive,
+ for example text for menu items that are not available can be set to
+ yellow with @code{fg[INSENSITIVE] = "yellow"}.
+ @end table
+ 
+   Colors can be specified as a string containing a color name (GTK knows
+ all names from the X color database @file{rgb.txt}), in one of the
+ hexadecimal forms @code{#rrrrggggbbbb}, @code{#rrrgggbbb}, @code{#rrggbb},
+ or @code{#rgb}, where r, g and b are hex digits, or they can be specified
+ as a triplet @address@hidden r, g, b @}}, where r, g and b are either integers 
+ in the range 0-65535 or floats in the range 0.0-1.0.
+ 
+   Pang font names have the form ``FAMILY-LIST STYLE-OPTIONS SIZE''.
+ 
+ @noindent
+ FAMILY-LIST is a comma separated list of families optionally terminated 
+ by a comma.  This way you can specify several families and the first
+ one found will be used.  The FAMILY corresponds to the second part in
+ an X font name, for example in
+ ``-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1''
+ the family name is ``times''.
+ 
+ @noindent
+ STYLE-OPTIONS is a whitespace separated list of words where each word
+ describes one of style, variant, weight, or stretch.
+ The @code{normal} values below does not need to be specified in a Pango
+ font name, they are the default.
+ 
+ 
+ @noindent
+ Style corresponds to the fourth part of an X font name.  In X font names
+ it is the character ``r'', ``i'' or ``o''.  In Pango font names
+ it is one of
+ @itemize @bullet
+ @item @code{normal}
+ @item @code{italic}
+ @item @code{oblique}
+ @end itemize
+ 
+ @noindent
+ Variant is either @code{normal} or @code{small-caps}.
+ Small caps is a font with the lower case characters replaced by
+ smaller variants of the capital characters.
+ 
+ @noindent
+ Weight describes the ``boldness'' of a font.  It corresponds to the third
+ part of an X font name.  It is one of
+ @itemize @bullet
+ @item @code{ultra-light}
+ @item @code{light}
+ @item @code{normal}
+ @item @code{bold}
+ @item @code{ultra-bold}
+ @item @code{heavy}
+ @end itemize
+ 
+ @noindent
+ Stretch gives the width of the font relative to other designs within a 
+ family.  It corresponds to the fifth part of an X font name.
+ It is one of
+ @itemize @bullet
+ @item @code{ultra-condensed}
+ @item @code{extra-condensed}
+ @item @code{condensed}
+ @item @code{semi-condensed}
+ @item @code{normal}
+ @item @code{semi-expanded}
+ @item @code{expanded}
+ @item @code{extra-expanded}
+ @item @code{ultra-expanded}
+ @end itemize
+ 
+ @noindent
+ SIZE is a decimal number that describes the font size in points.
+