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 16:54:56 -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,800 ---- @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 + + 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}. + + @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{} + may be used to indicate that the widget should use the same background + pixmap as its parent. The special value @code{} 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 = font + Sets the font for a widget. font must be an X font description, + e.g. "-*-helvetica-medium-r-normal--10-*-*-*-*-*-*-*". However, + this does not work, it seems that for GTK 2.0 you have to use + @code{font_name}. + + @item fontset = font + Sets the fontset for a widget. Overrides any font declarations. font + must be a comma-separated list of X font descriptions, + e.g. + @smallexample + "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240, + -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120, + -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240, + -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" + @end smallexample + + @item font_name = font + Sets the font for a widget. Overrides any font or fontset declarations. + Font must be a Pango font name, for example ``Sans Italic 10'', + ``Helvetica Bold 12'', ``Courier 14'', ``Times 18''. 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, address@hidden, where r, g and b are either integers + in the range 0-65635 or floats in the range 0.0-1.0.