<!-- ##### SECTION Title ##### -->Resource Files<!-- ##### SECTION Short_Description ##### -->Routines for handling resource files<!-- ##### SECTION Long_Description ##### --><para>GTK+ provides resource file mechanism for configuringvarious aspects of the operation of a GTK+ programat runtime.</para><refsect2><title>Default files</title><para>An application can cause GTK+ to parse a specific RCfile 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>&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> filescan be retrieved with gtk_rc_get_default_files()and modified with gtk_rc_add_default_file() andgtk_rc_set_default_files().Additionally, the <envar>GTK2_RC_FILES</envar> environment variablecan be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of filesin 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><para>A resource file defines a number of styles and key bindings andattaches them to particular widgets. The attachment is doneby the <literal>widget</literal>, <literal>widget_class</literal>,and <literal>class</literal> declarations. As an exampleof 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 class</firstterm>matches the <firstterm>pattern</firstterm><literal>"mywindow.*.GtkEntry"</literal>.</para><para>The patterns here are given in the standard shell globsyntax. The <literal>"?"</literal> wildcard matchesany character, while <literal>"*"</literal> matcheszero or more of any character. The three types ofmatching are against the widget path, the<firstterm>class path</firstterm> and the classhierarchy. Both the widget and the class paths consists of a<literal>"."</literal> separated list of all theparents of the widget and the widget itself fromoutermost to innermost. The difference is that inthe widget path, the name assigned bygtk_widget_set_name() is usedif present, otherwise the class name of the widget, whilefor the class path, the class name is always used.</para><para>So, if you have a #GtkEntry named<literal>"myentry"</literal>, inside of a of a windownamed <literal>"mywindow"</literal>, then thewidget path is: <literal>"mwindow.GtkHBox.myentry"</literal>while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.</para><para>Matching against class is a little different. The patternmatch is done against all class names in the widgetsclass hierarchy (not the layout hierarchy) in sequence, so thepattern:<informalexample><programlisting>class "GtkButton" style "my-style"</programlisting></informalexample>will match not just #GtkButton widgets,but also #GtkToggleButton and#GtkCheckButton widgets, sincethose classes derive from #GtkButton.</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 stylesread 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 setsup, and <literal>gtk</literal> is used for stylesthat GTK+ creates internally.</para></refsect2><refsect2><title>Toplevel declarations</title><para>An RC file is a text file which is composed of a sequenceof declarations. <literal>'#'</literal> characters delimit comments andthe portion of a line after a <literal>'#'</literal> is ignored when parsingan 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.</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 widgetswith a <literal>widget</literal>, <literal>widget_class</literal>,or <literal>class</literal> declaration. All stylesapplying to a particular widget are composited togetherwith <literal>widget</literal> declarations overriding<literal>widget_class</literal> declarations which, inturn, override <literal>class</literal> declarations.Within each type of declaration, later declarations overrideearlier ones.</para><para>Within a <literal>style</literal> declaration, the possibleelements 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, #GtkText, #GtkEntry, #GtkList, and #GtkCList.       </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 #GtkText,         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          pango_font_description_from_string().       </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>engine <replaceable>"engine"</replaceable> { <replaceable>engine-specificsettings</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 thestate 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 %GTK_STATE_ACTIVE 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 %GTK_STATE_PRELIGHT 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 gtk_widget_set_sensitive().      </para>    </listitem>  </varlistentry></variablelist></para><para><anchor id="color-format"/>Colors can be specified as a string containing a color name (GTK+ knowsall 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> arehex 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>In a <literal>stock</literal> definition, icon sources are specified as a4-tuple of image filename or icon name, text direction, widget state, and size, in thatorder.  Each icon source specifies an image filename or icon name to use with a givendirection, state, and size. Filenames are specified as a string suchas <literal>"itemltr.png"</literal>, while icon names (looked upin 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 awildcard, and if direction/state/size are omitted they default to