From: "Jan D." <jan.h.d@swipnet.se>
Subject: Re: GTK documentation in Emacs
Date: Thu, 9 Jan 2003 21:54:21 +0100 (CET) [thread overview]
Message-ID: <200301092150.h09LoDDU029370@stubby.bodenonline.com> (raw)
In-Reply-To: <200301091754.h09HsDDU023888@stubby.bodenonline.com> "from Jan D. at Jan 9, 2003 05:58:06 pm"
[-- Attachment #1: Type: text/plain, Size: 879 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,
Since I just got some new information I have made an update (attached).
It seems that X font names won't work in GTK 2.0 and newer, and Pango
font names is the way to go (the GTK documentation is not correct here).
I also got a pointer to where Pango font names are described (sort of
anyway), so I added this also.
New to me was that you can actually specify a default font for all GTK
widgets without defining a style. Just put the line
gtk-font-name = "Helvetica 14"
in your ~/.gtkrc-2.0 and that's it. This is not that obvious when
reading GTK documentation.
See http://bugzilla.gnome.org/show_bug.cgi?id=102936.
Jan D.
[-- Attachment #2: xresources.texi.diff --]
[-- Type: text/plain, Size: 13010 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 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 {@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}. 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 @code{@{ 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.
+
[-- 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 prev parent reply other threads:[~2003-01-09 20:54 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-01-09 16:58 GTK documentation in Emacs Jan D.
2003-01-09 20:54 ` Jan D. [this message]
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=200301092150.h09LoDDU029370@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).