gtkrc.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<!-- ##### SECTION Title ##### -->
Resource Files

<!-- ##### SECTION Short_Description ##### -->
Routines for handling resource files

<!-- ##### SECTION Long_Description ##### -->
<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 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> files
can be retrieved with gtk_rc_get_default_files()
and modified with gtk_rc_add_default_file() and
gtk_rc_set_default_files().
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>

<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 #GtkEntry widgets which are part of a #GtkWindow 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 gtk_widget_set_name() 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 #GtkLabel widgets which are contained in any kind of menu item.
</para>
<para>
So, if you have a #GtkEntry 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 #GtkButton widgets, but also #GtkToggleButton and
#GtkCheckButton widgets, since those 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 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 #GtkWindow
("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 #GtkHBox and #GtkVBox.
  </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, #GtkText, #GtkEntry, #GtkList, and #GtkCList.
       </para>
     </listitem>
  </varlistentry>