From: "Jan D." <jan.h.d@swipnet.se>
Subject: GTK documentation in Emacs
Date: Thu, 9 Jan 2003 17:58:06 +0100 (CET) [thread overview]
Message-ID: <200301091754.h09HsDDU023888@stubby.bodenonline.com> (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
next reply other threads:[~2003-01-09 16:58 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-01-09 16:58 Jan D. [this message]
2003-01-09 20:54 ` GTK documentation in Emacs Jan D.
2003-01-10 3:27 ` Miles Bader
2003-01-10 17:20 ` Jan D.
2003-01-11 1:27 ` Miles Bader
2003-01-10 19:27 ` Eli Zaretskii
2003-01-10 20:45 ` Jan D.
2003-01-10 19:56 ` Eli Zaretskii
2003-01-11 8:29 ` Jan D.
2003-01-11 9:23 ` Eli Zaretskii
2003-01-11 11:01 ` Jan D.
2003-01-11 14:48 ` Eli Zaretskii
2003-01-11 9:49 ` Kai Großjohann
2003-01-11 10:57 ` Jan D.
-- strict thread matches above, loose matches on Subject: below --
2003-01-11 16:50 Karl Berry
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=200301091754.h09HsDDU023888@stubby.bodenonline.com \
--to=jan.h.d@swipnet.se \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).