<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="gtk-Resource-Files">
<refmeta>
<refentrytitle role="top_of_page" id="gtk-Resource-Files.top_of_page">Resource Files</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Resource Files</refname>
<refpurpose>Routines for handling resource files</refpurpose>
</refnamediv>

<refsynopsisdiv id="gtk-Resource-Files.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>
<anchor id="GtkRcStyle"/>
<synopsis>

#include &lt;gtk/gtk.h&gt;

                    <link linkend="GtkRcStyle-struct">GtkRcStyle</link>;
enum                <link linkend="GtkRcFlags">GtkRcFlags</link>;
enum                <link linkend="GtkRcTokenType">GtkRcTokenType</link>;
<link linkend="GScanner">GScanner</link>*           <link linkend="gtk-rc-scanner-new">gtk_rc_scanner_new</link>                  (void);
<link linkend="GtkStyle">GtkStyle</link>*           <link linkend="gtk-rc-get-style">gtk_rc_get_style</link>                    (<link linkend="GtkWidget">GtkWidget</link> *widget);
<link linkend="GtkStyle">GtkStyle</link>*           <link linkend="gtk-rc-get-style-by-paths">gtk_rc_get_style_by_paths</link>           (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         const <link linkend="char">char</link> *widget_path,
                                                         const <link linkend="char">char</link> *class_path,
                                                         <link linkend="GType">GType</link> type);
<link linkend="void">void</link>                <link linkend="gtk-rc-add-widget-name-style">gtk_rc_add_widget_name_style</link>        (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);
<link linkend="void">void</link>                <link linkend="gtk-rc-add-widget-class-style">gtk_rc_add_widget_class_style</link>       (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);
<link linkend="void">void</link>                <link linkend="gtk-rc-add-class-style">gtk_rc_add_class_style</link>              (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);
<link linkend="void">void</link>                <link linkend="gtk-rc-parse">gtk_rc_parse</link>                        (const <link linkend="gchar">gchar</link> *filename);
<link linkend="void">void</link>                <link linkend="gtk-rc-parse-string">gtk_rc_parse_string</link>                 (const <link linkend="gchar">gchar</link> *rc_string);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-rc-reparse-all">gtk_rc_reparse_all</link>                  (void);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-rc-reparse-all-for-settings">gtk_rc_reparse_all_for_settings</link>     (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         <link linkend="gboolean">gboolean</link> force_load);
<link linkend="void">void</link>                <link linkend="gtk-rc-reset-styles">gtk_rc_reset_styles</link>                 (<link linkend="GtkSettings">GtkSettings</link> *settings);
<link linkend="void">void</link>                <link linkend="gtk-rc-add-default-file">gtk_rc_add_default_file</link>             (const <link linkend="gchar">gchar</link> *filename);
<link linkend="gchar">gchar</link>**             <link linkend="gtk-rc-get-default-files">gtk_rc_get_default_files</link>            (void);
<link linkend="void">void</link>                <link linkend="gtk-rc-set-default-files">gtk_rc_set_default_files</link>            (<link linkend="gchar">gchar</link> **filenames);
<link linkend="guint">guint</link>               <link linkend="gtk-rc-parse-color">gtk_rc_parse_color</link>                  (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GdkColor">GdkColor</link> *color);
<link linkend="guint">guint</link>               <link linkend="gtk-rc-parse-color-full">gtk_rc_parse_color_full</link>             (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkRcStyle">GtkRcStyle</link> *style,
                                                         <link linkend="GdkColor">GdkColor</link> *color);
<link linkend="guint">guint</link>               <link linkend="gtk-rc-parse-state">gtk_rc_parse_state</link>                  (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkStateType">GtkStateType</link> *state);
<link linkend="guint">guint</link>               <link linkend="gtk-rc-parse-priority">gtk_rc_parse_priority</link>               (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkPathPriorityType">GtkPathPriorityType</link> *priority);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-find-module-in-path">gtk_rc_find_module_in_path</link>          (const <link linkend="gchar">gchar</link> *module_file);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-find-pixmap-in-path">gtk_rc_find_pixmap_in_path</link>          (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         <link linkend="GScanner">GScanner</link> *scanner,
                                                         const <link linkend="gchar">gchar</link> *pixmap_file);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-get-module-dir">gtk_rc_get_module_dir</link>               (void);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-get-im-module-path">gtk_rc_get_im_module_path</link>           (void);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-get-im-module-file">gtk_rc_get_im_module_file</link>           (void);
<link linkend="gchar">gchar</link>*              <link linkend="gtk-rc-get-theme-dir">gtk_rc_get_theme_dir</link>                (void);
<link linkend="GtkRcStyle">GtkRcStyle</link>*         <link linkend="gtk-rc-style-new">gtk_rc_style_new</link>                    (void);
<link linkend="GtkRcStyle">GtkRcStyle</link>*         <link linkend="gtk-rc-style-copy">gtk_rc_style_copy</link>                   (<link linkend="GtkRcStyle">GtkRcStyle</link> *orig);
<link linkend="void">void</link>                <link linkend="gtk-rc-style-ref">gtk_rc_style_ref</link>                    (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style);
<link linkend="void">void</link>                <link linkend="gtk-rc-style-unref">gtk_rc_style_unref</link>                  (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style);
</synopsis>
</refsynopsisdiv>

<refsect1 id="gtk-Resource-Files.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----GtkRcStyle
</synopsis>
</refsect1>








<refsect1 id="gtk-Resource-Files.description" role="desc">
<title role="desc.title">Description</title>
<para>
GTK+ provides resource file mechanism for configuring
various aspects of the operation of a GTK+ program
at runtime.
</para>
<refsect2><title>Default files</title>
<para>
An application can cause GTK+ to parse a specific RC
file by calling <link linkend="gtk-rc-parse"><function>gtk_rc_parse()</function></link>. In addition to this,
certain files will be read at the end of <link linkend="gtk-init"><function>gtk_init()</function></link>.
Unless modified, the files looked for will be
<filename>&lt;SYSCONFDIR&gt;/gtk-2.0/gtkrc</filename>
and <filename>.gtkrc-2.0</filename> in the users home directory.
(<filename>&lt;SYSCONFDIR&gt;</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 <link linkend="gtk-rc-get-default-files"><function>gtk_rc_get_default_files()</function></link>
and modified with <link linkend="gtk-rc-add-default-file"><function>gtk_rc_add_default_file()</function></link> and
<link linkend="gtk-rc-set-default-files"><function>gtk_rc_set_default_files()</function></link>.
Additionally, the <envar>GTK2_RC_FILES</envar> environment variable
can be set to a <link linkend="G-SEARCHPATH-SEPARATOR-S-separated"><type>G_SEARCHPATH_SEPARATOR_S-separated</type></link> 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>
<refsect2><title>Pathnames and patterns</title>
<anchor id="gtkrc-pathnames-and-patterns"/>
<para>
A resource file defines a number of styles and key bindings and
attaches them to particular widgets. The attachment is done
by the <literal>widget</literal>, <literal>widget_class</literal>,
and <literal>class</literal> declarations. As an example
of such a statement:
<informalexample><programlisting>
widget "mywindow.*.GtkEntry" style "my-entry-class"
</programlisting></informalexample>
attaches the style <literal>"my-entry-class"</literal> to all
widgets  whose <firstterm>widget path</firstterm> matches the
<firstterm>pattern</firstterm> <literal>"mywindow.*.GtkEntry"</literal>.
That is, all <link linkend="GtkEntry"><type>GtkEntry</type></link> widgets which are part of a <link linkend="GtkWindow"><type>GtkWindow</type></link> named
<literal>"mywindow"</literal>.
</para>
<para>
The patterns here are given in the standard shell glob syntax.
The <literal>"?"</literal> wildcard matches any character, while
<literal>"*"</literal> matches zero or more of any character.
The three types of matching are against the widget path, the
<firstterm>class path</firstterm> and the class hierarchy. Both the
widget path and the class path consist of a <literal>"."</literal>
separated list of all the parents of the widget and the widget itself
from outermost to innermost. The difference is that in the widget path,
the name assigned by <link linkend="gtk-widget-set-name"><function>gtk_widget_set_name()</function></link> is used if present, otherwise
the class name of the widget, while for the class path, the class name is
always used.
</para>
<para>
Since GTK+ 2.10,<literal>widget_class</literal> paths can also contain
<literal>&lt;classname&gt;</literal> substrings, which are matching
the class with the given name and any derived classes. For instance,
<informalexample><programlisting>
widget_class "*&lt;GtkMenuItem&gt;.GtkLabel" style "my-style"
</programlisting></informalexample>
will match <link linkend="GtkLabel"><type>GtkLabel</type></link> widgets which are contained in any kind of menu item.
</para>
<para>
So, if you have a <link linkend="GtkEntry"><type>GtkEntry</type></link> named <literal>"myentry"</literal>, inside of a
horizontal box in a window named <literal>"mywindow"</literal>, then the
widget path is: <literal>"mywindow.GtkHBox.myentry"</literal>
while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.
</para>
<para>
Matching against class is a little different. The pattern match is done
against all class names in the widgets class hierarchy (not the layout
hierarchy) in sequence, so the pattern:
<informalexample><programlisting>
class "GtkButton" style "my-style"
</programlisting></informalexample>
will match not just <link linkend="GtkButton"><type>GtkButton</type></link> widgets, but also <link linkend="GtkToggleButton"><type>GtkToggleButton</type></link> and
<link linkend="GtkCheckButton"><type>GtkCheckButton</type></link> widgets, since those classes derive from <link linkend="GtkButton"><type>GtkButton</type></link>.
</para>
<para>
Additionally, a priority can be specified for each pattern, and styles
override other styles first by priority, then by pattern type and then
by order of specification (later 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>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 styles
read from an RC file, <literal>theme</literal>
is the default for styles read from theme RC files,
<literal>application</literal>
should be used for styles an application sets
up, and <literal>gtk</literal> is used for styles
that GTK+ creates internally.
</para>
</refsect2>
<refsect2>
<anchor id="optimizing-rc-style-matches"/>
<title>Optimizing RC Style Matches</title>
<para>
Everytime a widget is created and added to the layout hierarchy of a <link linkend="GtkWindow"><type>GtkWindow</type></link>
("anchored" to be exact), a list of matching RC styles out of all RC styles read
in so far is composed.
For this, every RC style is matched against the widgets class path,
the widgets name path and widgets inheritance hierarchy.
As a consequence, significant slowdown can be caused by utilization of many
RC styles and by using RC style patterns that are slow or complicated to match
against a given widget.
The following ordered list provides a number of advices (prioritized by
effectiveness) to reduce the performance overhead associated with RC style
matches:
<orderedlist>
  <listitem><para>
  Move RC styles for specific applications into RC files dedicated to those
  applications and parse application specific RC files only from
  applications that are affected by them.
  This reduces the overall amount of RC styles that have to be considered
  for a match across a group of applications.
  </para></listitem>
  <listitem><para>
  Merge multiple styles which use the same matching rule, for instance:
<informalexample><programlisting>
     style "Foo" { foo_content }
     class "X" style "Foo"
     style "Bar" { bar_content }
     class "X" style "Bar"
</programlisting></informalexample>
   is faster to match as:
<informalexample><programlisting>
     style "FooBar" { foo_content bar_content }
     class "X" style "FooBar"
</programlisting></informalexample>
  </para></listitem>
  <listitem><para>
  Use of wildcards should be avoided, this can reduce the individual RC style
  match to a single integer comparison in most cases.
  </para></listitem>
  <listitem><para>
  To avoid complex recursive matching, specification of full class names
  (for <literal>class</literal> matches) or full path names (for
  <literal>widget</literal> and <literal>widget_class</literal> matches)
  is to be preferred over shortened names
  containing <literal>"*"</literal> or <literal>"?"</literal>.
  </para></listitem>
  <listitem><para>
  If at all necessary, wildcards should only be used at the tail or head
  of a pattern. This reduces the match complexity to a string comparison
  per RC style.
  </para></listitem>
  <listitem><para>
  When using wildcards, use of <literal>"?"</literal> should be preferred
  over <literal>"*"</literal>. This can reduce the matching complexity from
  O(n^2) to O(n). For example <literal>"Gtk*Box"</literal> can be turned into
  <literal>"Gtk?Box"</literal> and will still match <link linkend="GtkHBox"><type>GtkHBox</type></link> and <link linkend="GtkVBox"><type>GtkVBox</type></link>.
  </para></listitem>
  <listitem><para>
  The use of <literal>"*"</literal> wildcards should be restricted as much
  as possible, because matching <literal>"A*B*C*RestString"</literal> can
  result in matching complexities of O(n^2) worst case.
  </para></listitem>
</orderedlist>
</para>
</refsect2>
<refsect2><title>Toplevel declarations</title>
<para>
An RC file is a text file which is composed of a sequence
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>
<para>
The possible toplevel declarations are:
<variablelist>
  <varlistentry>
    <term><literal>binding <replaceable>name</replaceable>
     { ... }</literal></term>
    <listitem>
      <para>Declares a binding set.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>class <replaceable>pattern</replaceable>
          [ style | binding ][ : <replaceable>priority</replaceable> ]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <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>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>
    <listitem>
      <para>Sets a path (a list of directories separated
      by colons) that will be searched for theme engines referenced in
      RC files.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <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
      RC files.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>im_module_file <replaceable>pathname</replaceable></literal></term>
    <listitem>
      <para>Sets the pathname for the IM modules file. Setting this from RC files
      is deprecated; you should use the environment variable <envar>GTK_IM_MODULE_FILE</envar>
      instead.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>style <replaceable>name</replaceable> [ =
    <replaceable>parent</replaceable> ] { ... }</literal></term>
    <listitem>
      <para>Declares a style.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>widget <replaceable>pattern</replaceable>
          [ style | binding ][ : <replaceable>priority</replaceable> ]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <para>Specifies a style or binding set for a particular
     group of widgets by matching on the widget pathname.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>widget_class <replaceable>pattern</replaceable>
          [ style | binding ][ : <replaceable>priority</replaceable> ]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <para>Specifies a style or binding set for a particular
     group of widgets by matching on the class pathname.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>setting</replaceable> = <replaceable>value</replaceable></term>
    <listitem>
      <para>Specifies a value for a <link linkend="GtkSettings">setting</link>.
        Note that settings in RC files are overwritten by system-wide settings
        (which are managed by an XSettings manager on X11).</para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2><title>Styles</title>
<para>
A RC style is specified by a <literal>style</literal>
declaration in a RC file, and then bound to widgets
with a <literal>widget</literal>, <literal>widget_class</literal>,
or <literal>class</literal> declaration. All styles
applying to a particular widget are composited together
with <literal>widget</literal> declarations overriding
<literal>widget_class</literal> declarations which, in
turn, override <literal>class</literal> declarations.
Within each type of declaration, later declarations override
earlier ones.
</para>
<para>
Within a <literal>style</literal> declaration, the possible
elements are:
<variablelist>
  <varlistentry>
    <term><literal>bg[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Sets the color used for the background of most widgets.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>fg[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Sets the color used for the foreground of most widgets.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>base[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Sets the color used for the background of widgets displaying
         editable text. This color is used for the background
         of, among others, <link linkend="GtkText"><type>GtkText</type></link>, <link linkend="GtkEntry"><type>GtkEntry</type></link>, <link linkend="GtkList"><type>GtkList</type></link>, and <link linkend="GtkCList"><type>GtkCList</type></link>.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>text[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Sets the color used for foreground of widgets using
         <literal>base</literal> for the background color.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>xthickness =
      <replaceable>number</replaceable></literal></term>
     <listitem>
       <para>
         Sets the xthickness, which is used for various horizontal padding
         values in GTK+.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>ythickness =
      <replaceable>number</replaceable></literal></term>
     <listitem>
       <para>
         Sets the ythickness, which is used for various vertical padding
         values in GTK+.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>bg_pixmap[<replaceable>state</replaceable>] =
      <replaceable>pixmap</replaceable></literal></term>
     <listitem>
       <para>
         Sets a background pixmap to be used in place of
         the <literal>bg</literal> color (or for <link linkend="GtkText"><type>GtkText</type></link>,
         in place of the <literal>base</literal> color. The special
         value <literal>"&lt;parent&gt;"</literal> may be used to indicate that the widget should
         use the same background pixmap as its parent. The special value
         <literal>"&lt;none&gt;"</literal> may be used to indicate no background pixmap.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>font = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Starting with GTK+ 2.0, the "font" and "fontset"
         declarations are ignored; use "font_name" declarations instead.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>fontset = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Starting with GTK+ 2.0, the "font" and "fontset"
         declarations are ignored; use "font_name" declarations instead.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>font_name = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Sets the font for a widget. <replaceable>font</replaceable> must be
         a Pango font name, e.g. <literal>"Sans Italic 10"</literal>.
         For details about Pango font names, see
         <link linkend="pango-font-description-from-string"><function>pango_font_description_from_string()</function></link>.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
     <listitem>
       <para>
        Defines the icon for a stock item.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>color[<replaceable>"color-name"</replaceable>] = <replaceable>color specification</replaceable></literal></term>
     <listitem>
       <para>
        Since 2.10, this element can be used to defines symbolic colors. See below for
        the syntax of color specifications.
       </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>
The colors and background pixmaps are specified as a function of the
state of the widget. The states are:
<variablelist>
  <varlistentry>
    <term><literal>NORMAL</literal></term>
    <listitem>
      <para>
        A color used for a widget in its normal state.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>ACTIVE</literal></term>
    <listitem>
      <para>
        A variant of the <literal>NORMAL</literal> color used when the
        widget is in the <link linkend="GTK-STATE-ACTIVE--CAPS"><literal>GTK_STATE_ACTIVE</literal></link> state, and also for
        the trough of a ScrollBar, tabs of a NoteBook
        other than the current tab and similar areas.
        Frequently, this should be a darker variant
        of the <literal>NORMAL</literal> color.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>PRELIGHT</literal></term>
    <listitem>
      <para>
        A color used for widgets in the <link linkend="GTK-STATE-PRELIGHT--CAPS"><literal>GTK_STATE_PRELIGHT</literal></link> state. This
        state is the used for Buttons and MenuItems
        that have the mouse cursor over them, and for
        their children.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>SELECTED</literal></term>
    <listitem>
      <para>
        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.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>INSENSITIVE</literal></term>
    <listitem>
      <para>
        A color used for the background of widgets that have
        been set insensitive with <link linkend="gtk-widget-set-sensitive"><function>gtk_widget_set_sensitive()</function></link>.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
<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>&num;rrrrggggbbbb</literal>,
<literal>&num;rrrgggbbb</literal>, <literal>&num;rrggbb</literal>,
or <literal>&num;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>, where <literal>r</literal>,
<literal>g</literal> and <literal>b</literal> are either integers in
the range 0-65535 or floats in the range 0.0-1.0.
</para>
<para>
Since 2.10, colors can also be specified by refering to a symbolic color, as
follows: <literal>@<!-- -->color-name</literal>, or by using expressions to combine
colors. The following expressions are currently supported:
  <variablelist>
    <varlistentry>
      <term>mix (<replaceable>factor</replaceable>, <replaceable>color1</replaceable>, <replaceable>color2</replaceable>)</term>
      <listitem><para>
        Computes a new color by mixing <replaceable>color1</replaceable> and
        <replaceable>color2</replaceable>. The <replaceable>factor</replaceable>
        determines how close the new color is to <replaceable>color1</replaceable>.
        A factor of 1.0 gives pure <replaceable>color1</replaceable>, a factor of
        0.0 gives pure <replaceable>color2</replaceable>.
      </para></listitem>
    </varlistentry>
    <varlistentry>
      <term>shade (<replaceable>factor</replaceable>, <replaceable>color</replaceable>)</term>
      <listitem><para>
        Computes a lighter or darker variant of <replaceable>color</replaceable>.
        A <replaceable>factor</replaceable> of 1.0 leaves the color unchanged, smaller
        factors yield darker colors, larger factors yield lighter colors.
      </para></listitem>
    </varlistentry>
    <varlistentry>
      <term>lighter (<replaceable>color</replaceable>)</term>
      <listitem><para>
        This is an abbreviation for
        <literal>shade (1.3, <replaceable>color</replaceable>)</literal>.
      </para></listitem>
    </varlistentry>
    <varlistentry>
      <term>darker (<replaceable>color</replaceable>)</term>
      <listitem><para>
        This is an abbreviation for
        <literal>shade (0.7, <replaceable>color</replaceable>)</literal>.
      </para></listitem>
    </varlistentry>
  </variablelist>
</para>
<para>
Here are some examples of color expressions:
<informalexample><programlisting>
 mix (0.5, "red", "blue")
 shade (1.5, mix (0.3, "&num;0abbc0", { 0.3, 0.5, 0.9 }))
 lighter (@<!-- -->foreground)
</programlisting></informalexample>
</para>
<para>
In a <literal>stock</literal> definition, icon sources are specified as a
4-tuple of image filename or icon name, text direction, widget state, and size, in that
order.  Each icon source specifies an image filename or icon name to use with a given
direction, state, and size. Filenames are specified as a string such
as <literal>"itemltr.png"</literal>, while icon names (looked up
in the current icon theme), are specified with a leading
<literal>@</literal>, such as <literal>@"item-ltr"</literal>.
The <literal>*</literal> character can be used as a
wildcard, and if direction/state/size are omitted they default to
<literal>*</literal>. So for example, the following specifies different icons to
use for left-to-right and right-to-left languages:
<informalexample><programlisting>
stock["my-stock-item"] =
{
  { "itemltr.png", LTR, *, * },
  { "itemrtl.png", RTL, *, * }
}
</programlisting></informalexample>
This could be abbreviated as follows:
<informalexample><programlisting>
stock["my-stock-item"] =
{
  { "itemltr.png", LTR },
  { "itemrtl.png", RTL }
}
</programlisting></informalexample>
</para>
<para>
You can specify custom icons for specific sizes, as follows:
<informalexample><programlisting>
stock["my-stock-item"] =
{
  { "itemmenusize.png", *, *, "gtk-menu" },
  { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting></informalexample>
The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
<literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
<literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
can define other sizes.
</para>
<para>
It's also possible to use custom icons for a given state, for example:
<informalexample><programlisting>
stock["my-stock-item"] =
{
  { "itemprelight.png", *, PRELIGHT },
  { "iteminsensitive.png", *, INSENSITIVE },
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting></informalexample>
</para>
<para>
When selecting an icon source to use, GTK+ will consider text direction most
important, state second, and size third. It will select the best match based on
those criteria. If an attribute matches exactly (e.g. you specified
<literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
if the attribute matches with a wildcard, GTK+ will scale or modify the image to
match the state and size the user requested.
</para>
</refsect2>
<refsect2><title>Key bindings</title>
<para>
Key bindings allow the user to specify actions to be
taken on particular key presses. The form of a binding
set declaration is:
</para>
<informalexample><programlisting>
binding <replaceable>name</replaceable> {
  bind <replaceable>key</replaceable> {
    <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
    ...
  }
  ...
}
</programlisting></informalexample>
<para>
<replaceable>key</replaceable> is a string consisting of a
series of modifiers followed by the name of a key. The
modifiers can be:
<simplelist>
<member><literal>&lt;alt&gt;</literal></member>
<member><literal>&lt;ctl&gt;</literal></member>
<member><literal>&lt;control&gt;</literal></member>
<member><literal>&lt;meta&gt;</literal></member>
<member><literal>&lt;hyper&gt;</literal></member>
<member><literal>&lt;super&gt;</literal></member>
<member><literal>&lt;mod1&gt;</literal></member>
<member><literal>&lt;mod2&gt;</literal></member>
<member><literal>&lt;mod3&gt;</literal></member>
<member><literal>&lt;mod4&gt;</literal></member>
<member><literal>&lt;mod5&gt;</literal></member>
<member><literal>&lt;release&gt;</literal></member>
<member><literal>&lt;shft&gt;</literal></member>
<member><literal>&lt;shift&gt;</literal></member>
</simplelist>
<literal>&lt;shft&gt;</literal> is an alias for
<literal>&lt;shift&gt;</literal>,
<literal>&lt;ctl&gt;</literal> is an alias for
<literal>&lt;control&gt;</literal>,
 and
<literal>&lt;alt&gt;</literal> is an alias for
<literal>&lt;mod1&gt;</literal>.
</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 <link linkend="g-signal-new"><function>g_signal_new()</function></link>). 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
parameters of the signal.
</para>
<para>
Binding sets are connected to widgets in the same manner as styles,
with one difference: Binding sets override other binding sets first
by pattern type, then by priority and then by order of specification.
The priorities that can be specified and their default values are the
same as for styles.
</para>
</refsect2>
</refsect1>

<refsect1 id="gtk-Resource-Files.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkRcStyle-struct" role="struct">
<title>GtkRcStyle</title>
<indexterm zone="GtkRcStyle-struct"><primary sortas="RcStyle">GtkRcStyle</primary></indexterm><programlisting>typedef struct {
  gchar *name;
  gchar *bg_pixmap_name[5];
  PangoFontDescription *font_desc;

  GtkRcFlags color_flags[5];
  GdkColor   fg[5];
  GdkColor   bg[5];
  GdkColor   text[5];
  GdkColor   base[5];

  gint xthickness;
  gint ythickness;
} GtkRcStyle;
</programlisting>
<para>
The <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> structure is used to represent a set
of information about the appearance of a widget.
This can later be composited together with other
<link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> structures to form a <link linkend="GtkStyle"><type>GtkStyle</type></link>.
</para></refsect2>
<refsect2 id="GtkRcFlags" role="enum">
<title>enum GtkRcFlags</title>
<indexterm zone="GtkRcFlags"><primary sortas="RcFlags">GtkRcFlags</primary></indexterm><programlisting>typedef enum
{
  GTK_RC_FG		= 1 &lt;&lt; 0,
  GTK_RC_BG		= 1 &lt;&lt; 1,
  GTK_RC_TEXT		= 1 &lt;&lt; 2,
  GTK_RC_BASE		= 1 &lt;&lt; 3
} GtkRcFlags;
</programlisting>
<para>
The <link linkend="GtkRcFlags"><type>GtkRcFlags</type></link> enumeration is used as a bitmask
to specify which fields of a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> have been
set for each state.
</para><variablelist role="enum">
<varlistentry id="GTK-RC-FG--CAPS" role="constant">
<term><literal>GTK_RC_FG</literal></term>
<listitem><simpara>If present, the foreground color has been set for this state.
</simpara></listitem>
</varlistentry>
<varlistentry id="GTK-RC-BG--CAPS" role="constant">
<term><literal>GTK_RC_BG</literal></term>
<listitem><simpara>If present, the background color has been set for this state.
</simpara></listitem>
</varlistentry>
<varlistentry id="GTK-RC-TEXT--CAPS" role="constant">
<term><literal>GTK_RC_TEXT</literal></term>
<listitem><simpara>If present, the text color has been set for this state.
</simpara></listitem>
</varlistentry>
<varlistentry id="GTK-RC-BASE--CAPS" role="constant">
<term><literal>GTK_RC_BASE</literal></term>
<listitem><simpara>If present, the base color has been set for this state.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GtkRcTokenType" role="enum">
<title>enum GtkRcTokenType</title>
<indexterm zone="GtkRcTokenType"><primary sortas="RcTokenType">GtkRcTokenType</primary></indexterm><programlisting>typedef enum {
  GTK_RC_TOKEN_INVALID = G_TOKEN_LAST,
  GTK_RC_TOKEN_INCLUDE,
  GTK_RC_TOKEN_NORMAL,
  GTK_RC_TOKEN_ACTIVE,
  GTK_RC_TOKEN_PRELIGHT,
  GTK_RC_TOKEN_SELECTED,
  GTK_RC_TOKEN_INSENSITIVE,
  GTK_RC_TOKEN_FG,
  GTK_RC_TOKEN_BG,
  GTK_RC_TOKEN_TEXT,
  GTK_RC_TOKEN_BASE,
  GTK_RC_TOKEN_XTHICKNESS,
  GTK_RC_TOKEN_YTHICKNESS,
  GTK_RC_TOKEN_FONT,
  GTK_RC_TOKEN_FONTSET,
  GTK_RC_TOKEN_FONT_NAME,
  GTK_RC_TOKEN_BG_PIXMAP,
  GTK_RC_TOKEN_PIXMAP_PATH,
  GTK_RC_TOKEN_STYLE,
  GTK_RC_TOKEN_BINDING,
  GTK_RC_TOKEN_BIND,
  GTK_RC_TOKEN_WIDGET,
  GTK_RC_TOKEN_WIDGET_CLASS,
  GTK_RC_TOKEN_CLASS,
  GTK_RC_TOKEN_LOWEST,
  GTK_RC_TOKEN_GTK,
  GTK_RC_TOKEN_APPLICATION,
  GTK_RC_TOKEN_THEME,
  GTK_RC_TOKEN_RC,
  GTK_RC_TOKEN_HIGHEST,
  GTK_RC_TOKEN_ENGINE,
  GTK_RC_TOKEN_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_FILE,
  GTK_RC_TOKEN_STOCK,
  GTK_RC_TOKEN_LTR,
  GTK_RC_TOKEN_RTL,
  GTK_RC_TOKEN_COLOR,
  GTK_RC_TOKEN_UNBIND,
  GTK_RC_TOKEN_LAST
} GtkRcTokenType;
</programlisting>
<para>
The <link linkend="GtkRcTokenType"><type>GtkRcTokenType</type></link> enumeration represents the tokens
in the RC file. It is exposed so that theme engines
can reuse these tokens when parsing the theme-engine
specific portions of a RC file.
</para></refsect2>
<refsect2 id="gtk-rc-scanner-new" role="function">
<title>gtk_rc_scanner_new ()</title>
<indexterm zone="gtk-rc-scanner-new"><primary sortas="rc_scanner_new">gtk_rc_scanner_new</primary></indexterm><programlisting><link linkend="GScanner">GScanner</link>*           gtk_rc_scanner_new                  (void);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-style" role="function">
<title>gtk_rc_get_style ()</title>
<indexterm zone="gtk-rc-get-style"><primary sortas="rc_get_style">gtk_rc_get_style</primary></indexterm><programlisting><link linkend="GtkStyle">GtkStyle</link>*           gtk_rc_get_style                    (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Finds all matching RC styles for a given widget,
composites them together, and then creates a 
<link linkend="GtkStyle"><type>GtkStyle</type></link> representing the composite appearance.
(GTK+ actually keeps a cache of previously 
created styles, so a new style may not be
created.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkWidget"><type>GtkWidget</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the resulting style. No refcount is added
  to the returned style, so if you want to save this
  style around, you should add a reference yourself.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-style-by-paths" role="function">
<title>gtk_rc_get_style_by_paths ()</title>
<indexterm zone="gtk-rc-get-style-by-paths"><primary sortas="rc_get_style_by_paths">gtk_rc_get_style_by_paths</primary></indexterm><programlisting><link linkend="GtkStyle">GtkStyle</link>*           gtk_rc_get_style_by_paths           (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         const <link linkend="char">char</link> *widget_path,
                                                         const <link linkend="char">char</link> *class_path,
                                                         <link linkend="GType">GType</link> type);</programlisting>
<para>
Creates up a <link linkend="GtkStyle"><type>GtkStyle</type></link> from styles defined in a RC file by providing
the raw components used in matching. This function may be useful
when creating pseudo-widgets that should be themed like widgets but
don't actually have corresponding GTK+ widgets. An example of this
would be items inside a GNOME canvas widget.
</para>
<para>
The action of <link linkend="gtk-rc-get-style"><function>gtk_rc_get_style()</function></link> is similar to:
<informalexample><programlisting>
 gtk_widget_path (widget, NULL, &amp;path, NULL);
 gtk_widget_class_path (widget, NULL, &amp;class_path, NULL);
 gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), 
                            path, class_path,
                            G_OBJECT_TYPE (widget));
</programlisting></informalexample></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>settings</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkSettings"><type>GtkSettings</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>widget_path</parameter>&#160;:</term>
<listitem><simpara> the widget path to use when looking up the style, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
              if no matching against the widget path should be done
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>class_path</parameter>&#160;:</term>
<listitem><simpara> the class path to use when looking up the style, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
              if no matching against the class path should be done.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara> a type that will be used along with parent types of this type
       when matching against class styles, or <link linkend="G-TYPE-NONE--CAPS"><type>G_TYPE_NONE</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A style created by matching with the supplied paths,
  or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if nothing matching was specified and the default style should
  be used. The returned value is owned by GTK+ as part of an internal cache,
  so you must call <link linkend="g-object-ref"><function>g_object_ref()</function></link> on the returned value if you want to
  keep a reference to it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-add-widget-name-style" role="function" condition="deprecated:Use gtk_rc_parse_string() with a suitable string instead.">
<title>gtk_rc_add_widget_name_style ()</title>
<indexterm zone="gtk-rc-add-widget-name-style" role="deprecated"><primary sortas="rc_add_widget_name_style">gtk_rc_add_widget_name_style</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_add_widget_name_style        (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);</programlisting>
<warning><para><literal>gtk_rc_add_widget_name_style</literal> is deprecated and should not be used in newly-written code. Use <link linkend="gtk-rc-parse-string"><function>gtk_rc_parse_string()</function></link> with a suitable string instead.</para></warning>
<para>
Adds a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> that will be looked up by a match against
the widget's pathname. This is equivalent to a:
 <literal>widget PATTERN style STYLE</literal>
statement in a RC file.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_style</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> to use for widgets matching <parameter>pattern</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>the pattern
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-add-widget-class-style" role="function" condition="deprecated:Use gtk_rc_parse_string() with a suitable string instead.">
<title>gtk_rc_add_widget_class_style ()</title>
<indexterm zone="gtk-rc-add-widget-class-style" role="deprecated"><primary sortas="rc_add_widget_class_style">gtk_rc_add_widget_class_style</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_add_widget_class_style       (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);</programlisting>
<warning><para><literal>gtk_rc_add_widget_class_style</literal> is deprecated and should not be used in newly-written code. Use <link linkend="gtk-rc-parse-string"><function>gtk_rc_parse_string()</function></link> with a suitable string instead.</para></warning>
<para>
Adds a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> 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</literal>
statement in a RC file.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_style</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> to use for widgets matching <parameter>pattern</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>the pattern
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-add-class-style" role="function" condition="deprecated:Use gtk_rc_parse_string() with a suitable string instead.">
<title>gtk_rc_add_class_style ()</title>
<indexterm zone="gtk-rc-add-class-style" role="deprecated"><primary sortas="rc_add_class_style">gtk_rc_add_class_style</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_add_class_style              (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style,
                                                         const <link linkend="gchar">gchar</link> *pattern);</programlisting>
<warning><para><literal>gtk_rc_add_class_style</literal> is deprecated and should not be used in newly-written code. Use <link linkend="gtk-rc-parse-string"><function>gtk_rc_parse_string()</function></link> with a suitable string instead.</para></warning>
<para>
Adds a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> 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</literal>
statement in a RC file.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_style</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> to use for widgets deriving from <parameter>pattern</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>the pattern
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-parse" role="function">
<title>gtk_rc_parse ()</title>
<indexterm zone="gtk-rc-parse"><primary sortas="rc_parse">gtk_rc_parse</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_parse                        (const <link linkend="gchar">gchar</link> *filename);</programlisting>
<para>
Parses a given resource file.
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara>the filename of a file to parse. If <parameter>filename</parameter> is not absolute, it
  is searched in the current directory.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-parse-string" role="function">
<title>gtk_rc_parse_string ()</title>
<indexterm zone="gtk-rc-parse-string"><primary sortas="rc_parse_string">gtk_rc_parse_string</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_parse_string                 (const <link linkend="gchar">gchar</link> *rc_string);</programlisting>
<para>
Parses resource information directly from a string.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_string</parameter>&#160;:</term>
<listitem><simpara>a string to parse.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-reparse-all" role="function">
<title>gtk_rc_reparse_all ()</title>
<indexterm zone="gtk-rc-reparse-all"><primary sortas="rc_reparse_all">gtk_rc_reparse_all</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_rc_reparse_all                  (void);</programlisting>
<para>
If the modification time on any previously read file for the
default <link linkend="GtkSettings"><type>GtkSettings</type></link> has changed, discard all style information
and then reread all previously read RC files.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>  <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the files were reread.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-reparse-all-for-settings" role="function">
<title>gtk_rc_reparse_all_for_settings ()</title>
<indexterm zone="gtk-rc-reparse-all-for-settings"><primary sortas="rc_reparse_all_for_settings">gtk_rc_reparse_all_for_settings</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_rc_reparse_all_for_settings     (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         <link linkend="gboolean">gboolean</link> force_load);</programlisting>
<para>
If the modification time on any previously read file
for the given <link linkend="GtkSettings"><type>GtkSettings</type></link> has changed, discard all style information
and then reread all previously read RC files.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>settings</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkSettings"><type>GtkSettings</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>force_load</parameter>&#160;:</term>
<listitem><simpara> load whether or not anything changed
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the files were reread.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-reset-styles" role="function" condition="since:2.4">
<title>gtk_rc_reset_styles ()</title>
<indexterm zone="gtk-rc-reset-styles" role="2.4"><primary sortas="rc_reset_styles">gtk_rc_reset_styles</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_reset_styles                 (<link linkend="GtkSettings">GtkSettings</link> *settings);</programlisting>
<para>
This function recomputes the styles for all widgets that use a
particular <link linkend="GtkSettings"><type>GtkSettings</type></link> object. (There is one <link linkend="GtkSettings"><type>GtkSettings</type></link> object
per <link linkend="GdkScreen"><type>GdkScreen</type></link>, see <link linkend="gtk-settings-get-for-screen"><function>gtk_settings_get_for_screen()</function></link>); It is useful
when some global parameter has changed that affects the appearance
of all widgets, because when a widget gets a new style, it will
both redraw and recompute any cached information about its
appearance. As an example, it is used when the default font size
set by the operating system changes. Note that this function
doesn't affect widgets that have a style set explicitely on them
with <link linkend="gtk-widget-set-style"><function>gtk_widget_set_style()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>settings</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkSettings"><type>GtkSettings</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-rc-add-default-file" role="function">
<title>gtk_rc_add_default_file ()</title>
<indexterm zone="gtk-rc-add-default-file"><primary sortas="rc_add_default_file">gtk_rc_add_default_file</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_add_default_file             (const <link linkend="gchar">gchar</link> *filename);</programlisting>
<para>
Adds a file to the list of files to be parsed at the
end of <link linkend="gtk-init"><function>gtk_init()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> the pathname to the file. If <parameter>filename</parameter> is not absolute, it
   is searched in the current directory.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-default-files" role="function">
<title>gtk_rc_get_default_files ()</title>
<indexterm zone="gtk-rc-get-default-files"><primary sortas="rc_get_default_files">gtk_rc_get_default_files</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             gtk_rc_get_default_files            (void);</programlisting>
<para>
Retrieves the current list of RC files that will be parsed
at the end of <link linkend="gtk-init"><function>gtk_init()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of filenames. This memory
is owned by GTK+ and must not be freed by the application.
If you want to store this information, you should make a copy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-set-default-files" role="function">
<title>gtk_rc_set_default_files ()</title>
<indexterm zone="gtk-rc-set-default-files"><primary sortas="rc_set_default_files">gtk_rc_set_default_files</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_set_default_files            (<link linkend="gchar">gchar</link> **filenames);</programlisting>
<para>
Sets the list of files that GTK+ will read at the
end of <link linkend="gtk-init"><function>gtk_init()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filenames</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of filenames.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-parse-color" role="function">
<title>gtk_rc_parse_color ()</title>
<indexterm zone="gtk-rc-parse-color"><primary sortas="rc_parse_color">gtk_rc_parse_color</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_rc_parse_color                  (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
Parses a color in the <link linkend="color=format">format</link> expected
in a RC file. 
</para>
<para>
Note that theme engines should use <link linkend="gtk-rc-parse-color-full"><function>gtk_rc_parse_color_full()</function></link> in 
order to support symbolic colors.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>scanner</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GScanner"><type>GScanner</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter>&#160;:</term>
<listitem><simpara> a pointer to a <link linkend="GdkColor"><type>GdkColor</type></link> structure in which to store the result
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-TOKEN-NONE--CAPS"><literal>G_TOKEN_NONE</literal></link> if parsing succeeded, otherwise the token
    that was expected but not found
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-parse-color-full" role="function" condition="since:2.12">
<title>gtk_rc_parse_color_full ()</title>
<indexterm zone="gtk-rc-parse-color-full" role="2.12"><primary sortas="rc_parse_color_full">gtk_rc_parse_color_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_rc_parse_color_full             (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkRcStyle">GtkRcStyle</link> *style,
                                                         <link linkend="GdkColor">GdkColor</link> *color);</programlisting>
<para>
Parses a color in the <link linkend="color=format">format</link> expected
in a RC file. If <parameter>style</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, it will be consulted to resolve
references to symbolic colors.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>scanner</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GScanner"><type>GScanner</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>style</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter>&#160;:</term>
<listitem><simpara> a pointer to a <link linkend="GdkColor"><type>GdkColor</type></link> structure in which to store the result
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-TOKEN-NONE--CAPS"><literal>G_TOKEN_NONE</literal></link> if parsing succeeded, otherwise the token
    that was expected but not found

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="gtk-rc-parse-state" role="function">
<title>gtk_rc_parse_state ()</title>
<indexterm zone="gtk-rc-parse-state"><primary sortas="rc_parse_state">gtk_rc_parse_state</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_rc_parse_state                  (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkStateType">GtkStateType</link> *state);</programlisting>
<para>
Parses a <link linkend="GtkStateType"><type>GtkStateType</type></link> variable from the format expected
in a RC file.
</para><variablelist role="params">
<varlistentry><term><parameter>scanner</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkScanner"><type>GtkScanner</type></link> (must be initialized for parsing an RC file)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara>A pointer to a <link linkend="GtkStateType"><type>GtkStateType</type></link> variable in which to
store the result.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-parse-priority" role="function">
<title>gtk_rc_parse_priority ()</title>
<indexterm zone="gtk-rc-parse-priority"><primary sortas="rc_parse_priority">gtk_rc_parse_priority</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_rc_parse_priority               (<link linkend="GScanner">GScanner</link> *scanner,
                                                         <link linkend="GtkPathPriorityType">GtkPathPriorityType</link> *priority);</programlisting>
<para>
Parses a <link linkend="GtkPathPriorityType"><type>GtkPathPriorityType</type></link> variable from the format expected
in a RC file.
</para><variablelist role="params">
<varlistentry><term><parameter>scanner</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkScanner"><type>GtkScanner</type></link> (must be initialized for parsing an RC file)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara>A pointer to <link linkend="GtkPathPriorityType"><type>GtkPathPriorityType</type></link> variable in which
to store the result.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-find-module-in-path" role="function">
<title>gtk_rc_find_module_in_path ()</title>
<indexterm zone="gtk-rc-find-module-in-path"><primary sortas="rc_find_module_in_path">gtk_rc_find_module_in_path</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_find_module_in_path          (const <link linkend="gchar">gchar</link> *module_file);</programlisting>
<para>
Searches for a theme engine in the GTK+ search path. This function
is not useful for applications and should not be used.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>module_file</parameter>&#160;:</term>
<listitem><simpara> name of a theme engine
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The filename, if found (must be freed with <link linkend="g-free"><function>g_free()</function></link>),
  otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-find-pixmap-in-path" role="function">
<title>gtk_rc_find_pixmap_in_path ()</title>
<indexterm zone="gtk-rc-find-pixmap-in-path"><primary sortas="rc_find_pixmap_in_path">gtk_rc_find_pixmap_in_path</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_find_pixmap_in_path          (<link linkend="GtkSettings">GtkSettings</link> *settings,
                                                         <link linkend="GScanner">GScanner</link> *scanner,
                                                         const <link linkend="gchar">gchar</link> *pixmap_file);</programlisting>
<para>
Looks up a file in pixmap path for the specified <link linkend="GtkSettings"><type>GtkSettings</type></link>.
If the file is not found, it outputs a warning message using
<link linkend="g-warning"><function>g_warning()</function></link> and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>settings</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkSettings"><type>GtkSettings</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>scanner</parameter>&#160;:</term>
<listitem><simpara> Scanner used to get line number information for the
  warning message, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pixmap_file</parameter>&#160;:</term>
<listitem><simpara> name of the pixmap file to locate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the filename. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-module-dir" role="function">
<title>gtk_rc_get_module_dir ()</title>
<indexterm zone="gtk-rc-get-module-dir"><primary sortas="rc_get_module_dir">gtk_rc_get_module_dir</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_get_module_dir               (void);</programlisting>
<para>
Returns a directory in which GTK+ looks for theme engines.
For full information about the search for theme engines,
see the docs for <envar>GTK_PATH</envar> in
<xref linkend="gtk-running"/>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the directory. (Must be freed with <link linkend="g-free"><function>g_free()</function></link>)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-im-module-path" role="function">
<title>gtk_rc_get_im_module_path ()</title>
<indexterm zone="gtk-rc-get-im-module-path"><primary sortas="rc_get_im_module_path">gtk_rc_get_im_module_path</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_get_im_module_path           (void);</programlisting>
<para>
Obtains the path in which to look for IM modules. See the documentation
of the <link linkend="im-module-path"><envar>GTK_PATH</envar></link>
environment variable for more details about looking up modules. This
function is useful solely for utilities supplied with GTK+ and should
not be used by applications under normal circumstances.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing the path in which to 
   look for IM modules.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-im-module-file" role="function">
<title>gtk_rc_get_im_module_file ()</title>
<indexterm zone="gtk-rc-get-im-module-file"><primary sortas="rc_get_im_module_file">gtk_rc_get_im_module_file</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_get_im_module_file           (void);</programlisting>
<para>
Obtains the path to the IM modules file. See the documentation
of the <link linkend="im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
environment variable for more details.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing the name of the file
listing the IM modules available for loading
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-get-theme-dir" role="function">
<title>gtk_rc_get_theme_dir ()</title>
<indexterm zone="gtk-rc-get-theme-dir"><primary sortas="rc_get_theme_dir">gtk_rc_get_theme_dir</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              gtk_rc_get_theme_dir                (void);</programlisting>
<para>
Returns the standard directory in which themes should
be installed. (GTK+ does not actually use this directory
itself.)
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The directory (must be freed with <link linkend="g-free"><function>g_free()</function></link>).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-style-new" role="function">
<title>gtk_rc_style_new ()</title>
<indexterm zone="gtk-rc-style-new"><primary sortas="rc_style_new">gtk_rc_style_new</primary></indexterm><programlisting><link linkend="GtkRcStyle">GtkRcStyle</link>*         gtk_rc_style_new                    (void);</programlisting>
<para>
Creates a new <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> with no fields set and
a reference count of 1.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the newly-created <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-style-copy" role="function">
<title>gtk_rc_style_copy ()</title>
<indexterm zone="gtk-rc-style-copy"><primary sortas="rc_style_copy">gtk_rc_style_copy</primary></indexterm><programlisting><link linkend="GtkRcStyle">GtkRcStyle</link>*         gtk_rc_style_copy                   (<link linkend="GtkRcStyle">GtkRcStyle</link> *orig);</programlisting>
<para>
Makes a copy of the specified <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>. This function
will correctly copy an RC style that is a member of a class
derived from <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>orig</parameter>&#160;:</term>
<listitem><simpara> the style to copy
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the resulting <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-style-ref" role="function" condition="deprecated:Use g_object_ref() instead">
<title>gtk_rc_style_ref ()</title>
<indexterm zone="gtk-rc-style-ref" role="deprecated"><primary sortas="rc_style_ref">gtk_rc_style_ref</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_style_ref                    (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style);</programlisting>
<warning><para><literal>gtk_rc_style_ref</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-object-ref"><function>g_object_ref()</function></link> instead</para></warning>
<para>
Increments the reference count of a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_style</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-rc-style-unref" role="function" condition="deprecated:Use g_object_unref() instead">
<title>gtk_rc_style_unref ()</title>
<indexterm zone="gtk-rc-style-unref" role="deprecated"><primary sortas="rc_style_unref">gtk_rc_style_unref</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_rc_style_unref                  (<link linkend="GtkRcStyle">GtkRcStyle</link> *rc_style);</programlisting>
<warning><para><literal>gtk_rc_style_unref</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-object-unref"><function>g_object_unref()</function></link> instead</para></warning>
<para>
Decrements the reference count of a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link> and
frees if the result is 0.
</para><variablelist role="params">
<varlistentry><term><parameter>rc_style</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkRcStyle"><type>GtkRcStyle</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
