GTK documentation in Emacs

* GTK documentation in Emacs
@ 2003-01-09 16:58 Jan D.
  2003-01-09 20:54 ` Jan D.
  2003-01-10 19:27 ` Eli Zaretskii
  0 siblings, 2 replies; 15+ messages in thread
From: Jan D. @ 2003-01-09 16:58 UTC (permalink / raw)

[-- Attachment #1: Type: text/plain, Size: 236 bytes --]

Hello.

I will shortly check in the GTK changes in to CVS,  I really would like
some feedback on the documentation I've written (mostly modified from
GTK API reference) so far.  I have attached the diff to this mail.

Thanks,

	Jan D.

[-- Attachment #2: xresources.texi.diff --]
[-- Type: text/plain, Size: 11096 bytes --]

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 {@code{GtkFileSelection} and some} {@code{verticalScrollbar 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{<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 = 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 @code{@{ r, g, b@}}, where r, g and b are either integers 
+ in the range 0-65635 or floats in the range 0.0-1.0.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel

^ permalink raw reply	[flat|nested] 15+ messages in thread