An application can cause GTK+ to parse a specific RC
file by calling gtk_rc_parse(). In addition to this,
certain files will be read at the end of gtk_init().
-Unless modified, the files looked for will be <filename>.gtkrc</filename>
-in the users home directory, and
-<filename>$localstatedir/gtk/gtkrc</filename>
-(<literal>$localstatedir</literal> defaults to
-<filename>/usr/local/etc</filename>).
+Unless modified, the files looked for will be
+<filename><SYSCONFDIR>/gtk-2.0/gtkrc</filename>
+and <filename>.gtkrc-2.0</filename> in the users home directory.
+(<filename><SYSCONFDIR></filename> defaults to
+<filename>/usr/local/etc</filename>. It can be changed with the
+<option>--prefix</option> or <option>--sysconfdir</option> options when
+configuring GTK+.) Note that although the filenames contain the version
+number 2.0, all 2.x versions of GTK+ look for these files.
</para>
<para>
The set of these <firstterm>default</firstterm> files
can be retrieved with gtk_rc_get_default_files()
and modified with gtk_rc_add_default_file() and
gtk_rc_set_default_files().
-</para>
-<para>
-For each default file, in addition to the file itself,
-GTK+ will look for a locale-specific file that will
-be parsed in addition to the main file. For instance,
-if <literal>LANG</literal> is set to <literal>ja_JP.ujis</literal>,
-when loading the default file <filename>~/.gtkrc</filename>
-then GTK+ looks for <filename>~/.gtkrc.ja_JP.ujis</filename>,
-<filename>~/.gtkrc.ja_JP</filename>, and
-<filename>~/.gtkrc.ja</filename>, and parses the
-first one it finds.
+Additionally, the <envar>GTK2_RC_FILES</envar> environment variable
+can be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of files
+in order to overwrite the set of default files at runtime.
+</para>
+<para><anchor id="locale-specific-rc"/>
+For each RC file, in addition to the file itself, GTK+ will look for
+a locale-specific file that will be parsed after the main file.
+For instance, if <envar>LANG</envar> is set to <literal>ja_JP.ujis</literal>,
+when loading the default file <filename>~/.gtkrc</filename> then GTK+ looks
+for <filename>~/.gtkrc.ja_JP</filename> and <filename>~/.gtkrc.ja</filename>,
+and parses the first of those that exists.
</para>
</refsect2>
parents of the widget and the widget itself from
outermost to innermost. The difference is that in
the widget path, the name assigned by
-<function>gtk_widget_set_name()</function> is used
+gtk_widget_set_name() is used
if present, otherwise the class name of the widget, while
for the widget path, the class name is always used.
</para>
<para>
-So, if you have a <classname>GtkEntry</classname> named
+So, if you have a #GtkEntry named
<literal>"myentry"</literal>, inside of a of a window
named <literal>"mywindow"</literal>, then the
widget path is: <literal>"mwindow.GtkHBox.myentry"</literal>
<informalexample><programlisting>
class "GtkButton" style "my-style"
</programlisting></informalexample>
-will match not just <classname>GtkButton</classname> widgets,
-but also <classname>GtkToggleButton</classname> and
-<classname>GtkCheckButton</classname> widgets, since
-those classes derive from <classname>GtkButton</classname>.
+will match not just #GtkButton widgets,
+but also #GtkToggleButton and
+#GtkCheckButton widgets, since
+those classes derive from #GtkButton.
</para>
</refsect2>
<refsect2><title>Toplevel declarations</title>
<para>
An RC file is a text file which is composed of a sequence
-of declarations. '#' characters delimit comments and
-the portion of a line after a '#' is ignored when parsing
+of declarations. <literal>'#'</literal> characters delimit comments and
+the portion of a line after a <literal>'#'</literal> is ignored when parsing
an RC file.
</para>
<term><literal>binding <replaceable>name</replaceable>
{ ... }</literal></term>
<listitem>
- <para>Declare a binding set</para>
+ <para>Declares a binding set.</para>
</listitem>
</varlistentry>
<varlistentry>
[ style | binding [ : <replaceable>priority</replaceable> ]]
<replaceable>name</replaceable></literal></term>
<listitem>
- <para>Specify a style or binding set for a particular
+ <para>Specifies a style or binding set for a particular
branch of the inheritance hierarchy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>include <replaceable>filename</replaceable></literal></term>
<listitem>
- <para>Parse another file at this point</para>
+ <para>Parses another file at this point. If
+ <replaceable>filename</replaceable> is not an absolute filename,
+ it is searched in the directories of the currently open RC files.
+ </para>
+ <para>GTK+ also tries to load a
+ <link linkend="locale-specific-rc">locale-specific variant</link> of
+ the included file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>module_path <replaceable>path></replaceable></literal></term>
+ <term><literal>module_path <replaceable>path</replaceable></literal></term>
<listitem>
<para>Sets a path (a list of directories separated
by colons) that will be searched for theme engines referenced in
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>pixmap_path <replaceable>path></replaceable></literal></term>
+ <term><literal>pixmap_path <replaceable>path</replaceable></literal></term>
<listitem>
<para>Sets a path (a list of directories separated
by colons) that will be searched for pixmaps referenced in
<term><literal>style <replaceable>name</replaceable> [ =
<replaceable>parent</replaceable> ] { ... }</literal></term>
<listitem>
- <para>Declare a style</para>
+ <para>Declares a style.</para>
</listitem>
</varlistentry>
<varlistentry>
[ style | binding [ : <replaceable>priority</replaceable> ]]
<replaceable>name</replaceable></literal></term>
<listitem>
- <para>Specify a style or binding set for a particular
+ <para>Specifies a style or binding set for a particular
group of widgets by matching on the widget pathname.</para>
</listitem>
</varlistentry>
[ style | binding [ : <replaceable>priority</replaceable> ]]
<replaceable>name</replaceable></literal></term>
<listitem>
- <para>Specify a style or binding set for a particular
+ <para>Specifies a style or binding set for a particular
group of widgets by matching on the class pathname.</para>
</listitem>
</varlistentry>
<replaceable>color</replaceable></literal></term>
<listitem>
<para>
- Set color used for the background of most widgets.
+ Sets the color used for the background of most widgets.
</para>
</listitem>
</varlistentry>
<replaceable>color</replaceable></literal></term>
<listitem>
<para>
- Set color used for the foreground of most widgets.
+ Sets the color used for the foreground of most widgets.
</para>
</listitem>
</varlistentry>
<replaceable>color</replaceable></literal></term>
<listitem>
<para>
- Set color used for the background of widgets displaying
+ Sets the color used for the background of widgets displaying
editable text. This color is used for the background
- of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist.
+ of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkCList.
</para>
</listitem>
</varlistentry>
<replaceable>color</replaceable></literal></term>
<listitem>
<para>
- Set color used for foreground of widgets using
+ Sets the color used for foreground of widgets using
<literal>base</literal> for the background color.
</para>
</listitem>
<replaceable>pixmap</replaceable></literal></term>
<listitem>
<para>
- Set a background pixmap to be used in place of
+ Sets a background pixmap to be used in place of
the <literal>bg</literal> color (or for #GtkText,
in place of the <literal>base</literal> color. The special
- value "<parent>" may be used to indicate that the widget should
+ value <literal>"<parent>"</literal> may be used to indicate that the widget should
use the same background pixmap as its parent. The special value
- "<none>" may be used to indicate no background pixmap.
+ <literal>"<none>"</literal> may be used to indicate no background pixmap.
</para>
</listitem>
</varlistentry>
<term><literal>font = <replaceable>font</replaceable></literal></term>
<listitem>
<para>
- Set the font for a widget.
+ Sets the font for a widget. <replaceable>font</replaceable> must be
+ a XLFD font description, e.g.
+ <literal>"-*-helvetica-medium-r-normal--10-*-*-*-*-*-*-*"</literal>.
</para>
</listitem>
</varlistentry>
<term><literal>fontset = <replaceable>font</replaceable></literal></term>
<listitem>
<para>
- Set the fontset for a widget. Overrides any
- <literal>font</literal> declarations.
+ Sets the fontset for a widget. Overrides any
+ <literal>font</literal> declarations. <replaceable>font</replaceable>
+ must be a comma-separated list of XLFD font descriptions, e.g.
+ <literal>"-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"</literal>.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>font_name = <replaceable>font</replaceable></literal></term>
+ <listitem>
+ <para>
+ Sets the font for a widget. Overrides any
+ <literal>font</literal> or <literal>fontset</literal> declarations.
+ <replaceable>font</replaceable> must be a Pango font name, e.g.
+ <literal>"Sans Italic 10"</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
<listitem>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>engine <replaceable>"engine"</replaceable> { <replaceable>engine-specific
+settings</replaceable> }</literal></term>
+ <listitem>
+ <para>
+ Defines the engine to be used when drawing with this style.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><replaceable>class</replaceable>::<replaceable>property</replaceable> = <replaceable>value</replaceable></literal></term>
+ <listitem>
+ <para>
+ Sets a <link linkend="style-properties">style property</link> for a widget class.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
<para>
<term><literal>NORMAL</literal></term>
<listitem>
<para>
- A color used for a widget in its normal state
+ A color used for a widget in its normal state.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
A color used to highlight data selected by the user.
- for instance, the selected ListItems in a List widget, and the
- selection in an Editable widget.
+ for instance, the selected items in a list widget, and the
+ selection in an editable widget.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
A color used for the background of widgets that have
- been set insensitive with gtk_widget_set_sensitive()
+ been set insensitive with gtk_widget_set_sensitive().
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
-<para>
-Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
-<literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
-or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
-<literal>g</literal>, and <literal>b</literal> are
-hex digits, or they can be specified as a triplet of floats
+<para><anchor id="color-format"/>
+Colors can be specified as a string containing a color name (GTK+ knows
+all names from the X color database
+<filename>/usr/lib/X11/rgb.txt</filename>),
+in one of the hexadecimal forms <literal>#rrrrggggbbbb</literal>,
+<literal>#rrrgggbbb</literal>, <literal>#rrggbb</literal>,
+or <literal>#rgb</literal>, where <literal>r</literal>,
+<literal>g</literal> and <literal>b</literal> are
+hex digits, or they can be specified as a triplet
<literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
-<replaceable>b</replaceable>}</literal>.
+<replaceable>b</replaceable>}</literal>, where <literal>r</literal>,
+<literal>g</literal> and <literal>b</literal> are either integers in
+the range 0-65635 or floats in the range 0.0-1.0.
</para>
<para>
The action that is bound to the key is a sequence
of signal names (strings) followed by parameters for
each signal. The signals must be action signals.
-(See gtk_signal_new()). Each parameter can be
+(See g_signal_new()). Each parameter can be
a float, integer, string, or unquoted string
representing an enumeration value. The types of
the parameters specified must match the types of the
overrides earlier). The priorities that can
be specified are (highest to lowest):
<simplelist>
-<member><literal>HIGHEST</literal></member>
-<member><literal>RC</literal></member>
-<member><literal>APPLICATION</literal></member>
-<member><literal>GTK</literal></member>
-<member><literal>LOWEST</literal></member>
+<member><literal>highest</literal></member>
+<member><literal>rc</literal></member>
+<member><literal>theme</literal></member>
+<member><literal>application</literal></member>
+<member><literal>gtk</literal></member>
+<member><literal>lowest</literal></member>
</simplelist>
-<literal>RC</literal> is the default for bindings
-read from an RC file, <literal>APPLICATION</literal>
+<literal>rc</literal> is the default for bindings
+read from an RC file, <literal>theme</literal>
+is the default for bindings read from theme RC files,
+<literal>application</literal>
should be used for bindings an application sets
-up, and <literal>GTK</literal> is used for bindings
+up, and <literal>gtk</literal> is used for bindings
that GTK+ creates internally.
</para>
</refsect2>
@xthickness:
@ythickness:
-<!-- ##### STRUCT GtkRcStyleClass ##### -->
-<para>
-
-</para>
-
-
<!-- ##### ENUM GtkRcFlags ##### -->
<para>
The #GtkRcFlags enumeration is used as a bitmask
to specify which fields of a #GtkRcStyle have been
set for each state.
</para>
-<variablelist>
- <varlistentry><term> %GTK_RC_FG </term>
- <listitem>
- <para>
- If present, the foreground color has been set for this state.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_BG </term>
- <listitem>
- <para>
- If present, the background color has been set for this state.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_TEXT </term>
- <listitem>
- <para>
- If present, the text color has been set for this state.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_BASE </term>
- <listitem>
- <para>
- If present, the base color has been set for this state.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-@GTK_RC_FG:
-@GTK_RC_BG:
-@GTK_RC_TEXT:
-@GTK_RC_BASE:
+@GTK_RC_FG: If present, the foreground color has been set for this state.
+@GTK_RC_BG: If present, the background color has been set for this state.
+@GTK_RC_TEXT: If present, the text color has been set for this state.
+@GTK_RC_BASE: If present, the base color has been set for this state.
<!-- ##### ENUM GtkRcTokenType ##### -->
<para>
<!-- ##### FUNCTION gtk_rc_add_widget_name_style ##### -->
<para>
-Adds a RcStyle that will be looked up by a match against
+Adds a #GtkRcStyle that will be looked up by a match against
the widget's pathname. This is equivalent to a:
<literal>
widget PATTERN style STYLE
<!-- ##### FUNCTION gtk_rc_add_widget_class_style ##### -->
<para>
-Adds a RcStyle that will be looked up by a match against
+Adds a #GtkRcStyle that will be looked up by a match against
the widget's class pathname. This is equivalent to a:
<literal>
widget_class PATTERN style STYLE
<!-- ##### FUNCTION gtk_rc_add_class_style ##### -->
<para>
-Adds a RcStyle that will be looked up by a matching against
+Adds a #GtkRcStyle that will be looked up by a matching against
the class hierarchy of the widget. This is equivalent to a:
<literal>
class PATTERN style STYLE
Parses a given resource file.
</para>
-@filename: the filename of a file to parse.
+@filename: the filename of a file to parse. If @filename is not absolute, it
+ is searched in the current directory.
<!-- ##### FUNCTION gtk_rc_parse_string ##### -->
<!-- ##### FUNCTION gtk_rc_parse_color ##### -->
<para>
-Parses a color in the format expected in a RC file.
+Parses a color in the <link linkend="color-format">format</link> expected in a RC file.
</para>
@scanner: a #GtkScanner
@color: a pointer to a #GtkColor structure in which to store the result
-@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
+@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
@scanner: a #GtkScanner (must be initialized for parsing an RC file)
@state: A pointer to a #GtkStateType variable in which to
store the result.
-@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
+@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
@scanner: a #GtkScanner (must be initialized for parsing an RC file)
@priority: A pointer to #GtkPathPriorityType variable in which
to store the result.
-@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
+@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
<!-- ##### FUNCTION gtk_rc_find_module_in_path ##### -->
<para>
-Looks up a file in the current module path.
</para>
@module_file: The name of the module to search for.
-@Returns: The filename, if found. (Must be freed with g_free()),
-otherwise %NULL.
+@Returns:
<!-- ##### FUNCTION gtk_rc_find_pixmap_in_path ##### -->
<para>
</para>
-@context:
+@settings:
@scanner: a #GtkScanner. Used for printing out warning messages
if the file is not found.
@pixmap_file: The name of the file to search for.
-@Returns: The filename, if found. (Must be freed with g_free()),
+@Returns: The filename, if found (must be freed with g_free()),
otherwise %NULL.
+<!-- # Unused Parameters # -->
+@context:
<!-- ##### FUNCTION gtk_rc_get_module_dir ##### -->
<para>
-Returns the directory in which GTK+ will look for
-theme engines.
</para>
-@Returns: The directory. (Must be freed with g_free())
+@Returns:
<!-- ##### FUNCTION gtk_rc_get_im_module_path ##### -->
itself.)
</para>
-@Returns: The directory. (Must be freed with g_free())
+@Returns: The directory (must be freed with g_free()).
<!-- ##### FUNCTION gtk_rc_style_new ##### -->
projects / ~andy / gtk / blobdiff