path: root/docs/reference/pygtk-gtkrcstyle.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkrcstyle">
  <refnamediv>
    <refname>gtk.RcStyle</refname>
    <refpurpose>an object holding resource styles</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
  <ooclass><classname>gtk.RcStyle</classname></ooclass>
  <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkrcstyle--copy">copy</link></methodname>
    <methodparam></methodparam>
      </methodsynopsis>
</classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-add-default-file">gtk.rc_add_default_file</link></methodname>
    <methodparam><parameter role="keyword">filename</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-set-default-files">gtk.rc_set_default_files</link></methodname>
    <methodparam><parameter role="keyword">filenames</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-default-files">gtk.rc_get_default_files</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-style-by-paths">gtk.rc_get_style_by_paths</link></methodname>
    <methodparam><parameter role="keyword">settings</parameter></methodparam>
    <methodparam><parameter role="keyword">widget_path</parameter></methodparam>
    <methodparam><parameter role="keyword">class_path</parameter></methodparam>
    <methodparam><parameter role="keyword">type</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-reparse-all-for-settings">gtk.rc_reparse_all_for_settings</link></methodname>
    <methodparam><parameter role="keyword">settings</parameter></methodparam>
    <methodparam><parameter role="keyword">force_load</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-reset-styles">gtk.rc_reset_styles</link></methodname>
    <methodparam><parameter role="keyword">settings</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-parse">gtk.rc_parse</link></methodname>
    <methodparam><parameter role="keyword">filename</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-parse-string">gtk.rc_parse_string</link></methodname>
    <methodparam><parameter role="keyword">rc_string</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-reparse-all">gtk.rc_reparse_all</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-find-module-in-path">gtk.rc_find_module_in_path</link></methodname>
    <methodparam><parameter role="keyword">module_file</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-theme-dir">gtk.rc_get_theme_dir</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-module-dir">gtk.rc_get_module_dir</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-im-module-path">gtk.rc_get_im_module_path</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--rc-get-im-module-file">gtk.rc_get_im_module_file</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkrcstyle">gtk.RcStyle</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkrcstyle">
    <title>gtk.RcStyle Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><literal>PyGTK</literal> via <literal>GTK+</literal> provides
resource file mechanism for configuring various aspects of the operation of
a program at runtime.</para>

    <title>Default files</title>

    <para>An application can cause <literal>GTK+</literal> to parse a
specific RC file by calling the <link
linkend="function-gtk--rc-parse"><function>gtk.rc_parse</function>()</link>
function. In addition to this, certain files will be read at the end of
<literal>GTK+</literal> initialization. Unless modified, the files looked
for will be <filename>&lt;SYSCONFDIR&gt;/gtk-2.0/gtkrc</filename> and
.gtkrc-2.0 in the users home directory. (&lt;SYSCONFDIR&gt; defaults to
<filename>/usr/local/etc</filename>.) The set of these default files can be
retrieved with the <link
linkend="function-gtk--rc-get-default-files"><function>gtk.rc_get_default_files</function>()</link> 
function and modified with the <link
linkend="function-gtk--rc-add-default-file"><function>gtk.rc_add_default_file</function>()</link> 
and <link
linkend="function-gtk--rc-set-default-files"><function>gtk.rc_set_default_files</function>()</link> 
functions. Additionally, the <envar>GTK_RC_FILES</envar> environment
variable can be set to a list of files in order to overwrite the set of
default files at runtime.</para>

    <para>For each RC file, in addition to the file itself,
<literal>GTK+</literal> 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 <literal>GTK+</literal> looks for
<filename>~/.gtkrc.ja_JP</filename> and <filename>~/.gtkrc.ja</filename>,
and parses the first of those that exists.</para>

<title>Pathnames and patterns</title>

<para>A resource file defines a number of styles and key bindings and
attaches them to particular widgets. The attachment is done by the widget,
widget_class, and class declarations. As an example of such a
statement:</para>

    <programlisting>
  widget "mywindow.*.GtkEntry" style "my-entry-class"
</programlisting>

<para>attaches the style "my-entry-class" to all widgets whose widget class
matches the pattern "mywindow.*.GtkEntry". The patterns here are given in
the standard shell glob syntax. The "?" wildcard matches any character,
while "*" matches zero or more of any character. The three types of matching
are against the widget path, the class path and the class hierarchy. Both
the widget and the class paths consists of a "." 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 the <link
linkend="method-gtkwidget--set-name"><methodname>set_name</methodname>()</link> 
method is used if present, otherwise the class name of the widget, while for
the widget path, the class name is always used. So, if you have a <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> named
"myentry", inside of a of a window named "mywindow", then the widget path
is: "mwindow.GtkHBox.myentry" while the class path is:
"GtkWindow.GtkHBox.GtkEntry".</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:</para>

    <programlisting>
  class "GtkButton" style "my-style"
</programlisting>

    <para>will match not just <link
linkend="class-gtkbutton"><classname>gtk.Button</classname></link> widgets,
but also <link
linkend="class-gtktogglebutton"><classname>gtk.ToggleButton</classname></link> 
and <link
linkend="class-gtkcheckbutton"><classname>gtk.CheckButton</classname></link>
widgets, since those classes derive from <link
linkend="class-gtkbutton"><classname>gtk.Button</classname></link>.</para>

    <title>Toplevel declarations</title>

<para>An RC file is a text file which is composed of a sequence of
declarations. '#' characters delimit comments and the portion of a line
after a '#' is ignored when parsing an RC file. The possible toplevel
declarations are:</para>

      <variablelist>
      <varlistentry>
	<term>binding&nbsp;<parameter>name</parameter>&nbsp;{&nbsp;...&nbsp;}</term>
	<listitem>
	  <simpara>Declares a binding set.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>class&nbsp;<parameter>pattern</parameter>&nbsp;[&nbsp;style&nbsp;|&nbsp;binding&nbsp;[&nbsp;:&nbsp;priority&nbsp;]]&nbsp;<parameter>name</parameter></term>
	<listitem>
	  <simpara>Specifies a style or binding set for a particular branch
of the inheritance hierarchy.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>include&nbsp;<parameter>filename</parameter></term>
	<listitem>
	  <simpara>Parses another file at this point. If
<parameter>filename</parameter> is not an absolute filename, it is searched
in the directories of the currently open RC files. <literal>GTK+</literal>
also tries to load a locale-specific variant of the included file.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>module_path&nbsp;<parameter>path</parameter></term>
	<listitem>
	  <simpara>Sets a path (a list of directories separated by colons)
that will be searched for theme engines referenced in RC files.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>pixmap_path&nbsp;<parameter>path</parameter></term>
	<listitem>
	  <simpara>Sets a path (a list of directories separated by colons)
that will be searched for pixmaps referenced in RC files.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>style&nbsp;<parameter>name</parameter>&nbsp;[&nbsp;=&nbsp;<parameter>parent</parameter>&nbsp;]&nbsp;{&nbsp;...&nbsp;}</term>
	<listitem>
	  <simpara>Declares a style.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>widget&nbsp;<parameter>pattern</parameter>&nbsp;[&nbsp;style&nbsp;|&nbsp;binding&nbsp;[&nbsp;:&nbsp;priority&nbsp;]]&nbsp;<parameter>name</parameter></term>
	<listitem>
	  <simpara>Specifies a style or binding set for a particular group
of widgets by matching on the widget pathname.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>widget_class&nbsp;<parameter>pattern</parameter>&nbsp;[&nbsp;style&nbsp;|&nbsp;binding&nbsp;[&nbsp;:&nbsp;priority&nbsp;]]&nbsp;<parameter>name</parameter></term>
	<listitem>
	  <simpara>Specifies a style or binding set for a particular group
of widgets by matching on the class pathname.</simpara>
	</listitem>
      </varlistentry>
      </variablelist>

    <title>Styles</title>

    <para>A RC style is specified by a style 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
widget 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. Within a
style declaration, the possible elements are:</para>
  
      <variablelist role="old">
      <varlistentry>
	<term>bg[<parameter>state</parameter>]&nbsp;=&nbsp;<parameter>color</parameter></term>
	<listitem>
	  <simpara>Sets the color used for the background of most
widgets.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>fg[<parameter>state</parameter>]&nbsp;=&nbsp;<parameter>color</parameter></term>
	<listitem>
	  <simpara>Sets the color used for the foreground of most
widgets.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>base[<parameter>state</parameter>]&nbsp;=&nbsp;<parameter>color</parameter></term>
	<listitem>
	  <simpara>Sets the color used for the background of widgets
displaying editable text. This color is used for the background of, among
others, <link
linkend="class-gtktextview"><classname>gtk.TextView</classname></link> and
<link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link>.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>text[<parameter>state</parameter>]&nbsp;=&nbsp;<parameter>color</parameter></term>
	<listitem>
	  <simpara>Sets the color used for foreground of widgets using
<parameter>base</parameter> for the background color.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>bg_pixmap[<parameter>state</parameter>]&nbsp;=&nbsp;<parameter>pixmap</parameter></term>
	<listitem>
	  <simpara> Sets a background pixmap to be used in place of the
<literal>bg</literal> color (or for <link
linkend="class-gtktextview"><classname>gtk.TextView</classname></link>, in
place of the <literal>base</literal> color). The special value
"&lt;parent&gt;" may be used to indicate that the widget should use the same
background pixmap as its parent. The special value "&lt;none&gt;" may be
used to indicate no background pixmap.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>font&nbsp;=&nbsp;<parameter>font</parameter></term>
	<listitem>
	  <simpara>Sets the font for a widget. font must be a XLFD font
description, e.g.
"-*-helvetica-medium-r-normal--10-*-*-*-*-*-*-*".</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>fontset&nbsp;=&nbsp;<parameter>font</parameter></term>
	<listitem>
	  <simpara>Sets the fontset for a widget. Overrides any font
declarations. font must be a comma-separated list of XLFD font descriptions,
e.g. "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150".</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>font_name&nbsp;=&nbsp;<parameter>font</parameter></term>
	<listitem>
	  <simpara>Sets the font for a widget. Overrides any
<literal>font</literal> or <literal>fontset</literal> declarations.
<parameter>font</parameter> must be a Pango font name, e.g. "Sans Italic
10".</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>stock["<parameter>stock-id</parameter>"]&nbsp;=&nbsp;{&nbsp;<parameter>icon&nbsp;source&nbsp;specifications</parameter>&nbsp;}</term>
	<listitem>
	  <simpara>Defines the icon for a stock item.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>engine&nbsp;"<parameter>engine</parameter>"&nbsp;{&nbsp;<parameter>engine-specific&nbsp;settings</parameter>&nbsp;}</term>
	<listitem>
	  <simpara>Defines the engine to be used when drawing with this
style.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>class</parameter>::<parameter>property</parameter>&nbsp;=&nbsp;<parameter>value</parameter></term>
	<listitem>
	  <simpara>Sets a <link
linkend="widget-style-properties">style property</link> for a widget
class.</simpara>
	</listitem>
      </varlistentry>
      </variablelist>

    <para>The colors and background pixmaps are specified as a function of
the state of the widget. The states are:</para>

      <variablelist>
      <varlistentry>
	<term><literal>NORMAL</literal></term>
	<listitem>
	  <simpara>A color used for a widget in its normal state.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>ACTIVE</literal></term>
	<listitem>
	  <simpara>A variant of the <literal>NORMAL</literal> color used
when the widget is in the <literal>gtk.STATE_ACTIVE</literal> state, and
also for the trough of a <link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>,
tabs of a <link
linkend="class-gtknotebook"><classname>gtk.Notebook</classname></link> other
than the current tab and similar areas. Frequently, this should be a darker
variant of the <literal>NORMAL</literal> color.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>PRELIGHT</literal></term>
	<listitem>
	  <simpara>A color used for widgets in the
<literal>gtk.STATE_PRELIGHT</literal> state. This state is the used for
<link linkend="class-gtkbutton"><classname>gtk.Button</classname></link> and
<link linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
widgets that have the mouse cursor over them, and for their
children.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>SELECTED</literal></term>
	<listitem>
	  <simpara>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.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>INSENSITIVE</literal></term>
	<listitem>
	  <simpara>A color used for the background of widgets that have been
set insensitive with the <link
linkend="method-gtkwidget--set-sensitive"><methodname>set_sensitive</methodname>()</link> 
method.</simpara>
	</listitem>
      </varlistentry>
      </variablelist>

    <para>Colors can be specified as a string containing a color name (from
the X color database <filename>/usr/lib/X11/rgb.txt</filename>), in one of
the hexadecimal forms <literal>#rrrrggggbbbb</literal>,
<literal>#rrrgggbbb</literal>, <literal>#rrggbb</literal>, or
<literal>#rgb</literal>, where <literal>r</literal>, <literal>g</literal>
and <literal>b</literal> are hex digits, or they can be specified as a
triplet <literal>{ r, g, b}</literal>, where <literal>r</literal>,
<literal>g</literal> and <literal>b</literal> are either integers in the
range 0-65635 or floats in the range 0.0-1.0.</para>

<para>In a stock definition, icon sources are specified as a 4-tuple of
image filename, text direction, widget state, and size, in that order. Each
icon source specifies an image filename to use with a given direction,
state, and size. The * character can be used as a wildcard, and if
direction-state-size are omitted they default to *. So for example, the
following specifies different icons to use for left-to-right and
right-to-left languages:</para>

    <programlisting>
  stock["my-stock-item"] = 
  {
    { "itemltr.png", LTR, *, * },
    { "itemrtl.png", RTL, *, * }
  }
</programlisting>

    <para>This could be abbreviated as follows:</para>

    <programlisting>
  stock["my-stock-item"] = 
  {
    { "itemltr.png", LTR },
    { "itemrtl.png", RTL }
  }
</programlisting>

    <para>You can specify custom icons for specific sizes, as
follows:</para>

    <programlisting>
  stock["my-stock-item"] = 
  {
    { "itemmenusize.png", *, *, "gtk-menu" },
    { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
    { "itemgeneric.png" } /* implicit *, *, * as a fallback */
  }
</programlisting>

    <para>The sizes that come with <literal>GTK+</literal> itself are
"gtk-menu", "gtk-small-toolbar", "gtk-large-toolbar", "gtk-button",
"gtk-dialog". Applications can define other sizes. It's also possible to use
custom icons for a given state, for example:</para>

    <programlisting>
  stock["my-stock-item"] = 
  {
    { "itemprelight.png", *, PRELIGHT },
    { "iteminsensitive.png", *, INSENSITIVE }, 
    { "itemgeneric.png" } /* implicit *, *, * as a fallback */
  }
</programlisting>

    <para>When selecting an icon source to use, <literal>GTK+</literal> 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), <literal>GTK+</literal> won't modify the image; if the attribute
matches with a wildcard, <literal>GTK+</literal> will scale or modify the
image to match the state and size the user requested.</para>

    <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>

    <programlisting>
  binding name {
    bind key { 
      signalname (param, ...)
      ...
    }
    ...
  }
</programlisting>

    <para><parameter>key</parameter> is a string consisting of a series of
modifiers followed by the name of a key. The modifiers can be:</para>

    <itemizedlist>
      <listitem>
	<simpara>&lt;alt&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;control&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;mod1&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;mod2&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;mod3&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;mod4&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;mod5&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;release&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;shft&gt;</simpara>
      </listitem>
      <listitem>
	<simpara>&lt;shift&gt;</simpara>
      </listitem>
   </itemizedlist>

    <para>&lt;shft&gt; is an alias for &lt;shift&gt; and &lt;alt&gt; is an
alias for &lt;mod1&gt;.</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. 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. Binding sets are
connected to widgets in the same manner as styles, with one addition. A
priority can be specified for each pattern, and within each type of pattern,
binding sets override other binding sets first by priority, and only then by
order of specification. (Later overrides earlier). The priorities that can
be specified are (highest to lowest):</para>

    <itemizedlist>
      <listitem>
	<simpara>highest</simpara>
      </listitem>
      <listitem>
	<simpara>rc</simpara>
      </listitem>
      <listitem>
	<simpara>theme</simpara>
      </listitem>
      <listitem>
	<simpara>application</simpara>
      </listitem>
      <listitem>
	<simpara>gtk</simpara>
      </listitem>
      <listitem>
	<simpara>lowest</simpara>
      </listitem>
   </itemizedlist>

    <para><literal>rc</literal> is the default for bindings read from an RC
file, <literal>theme</literal> is the default for bindings read from theme
RC files, <literal>application</literal> should be used for bindings an
application sets up, and <literal>gtk</literal> is used for bindings that
<literal>GTK+</literal> creates internally.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

  <refsect2 id="method-gtkrcstyle--copy">
      <title>gtk.RcStyle.copy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkrcstyle"><classname>gtk.RcStyle</classname></link> that is
a copy of the rcstyle</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The copy() method returns a new <link
linkend="class-gtkrcstyle"><classname>gtk.RcStyle</classname></link> that is
a copy of the RC style. This method will correctly copy an RC style that is
a member of a class derived from <link
linkend="class-gtkrcstyle"><classname>gtk.RcStyle</classname></link>.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--rc-add-default-file">
      <title>gtk.rc_add_default_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_add_default_file</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of a file containing resource
data</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_add_default_file</function>() function adds
the file specified by <parameter>filename</parameter> to the list of files
to be parsed for resource data.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-set-default-files">
      <title>gtk.rc_set_default_files</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_set_default_files</methodname>
	  <methodparam><parameter
			 role="keyword">filenames</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">filenames</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of filenames</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_set_default_files</function>() function
sets the list of files (specified by <parameter>filenames</parameter>) that
will be parsed for resource information.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-default-files">
      <title>gtk.rc_get_default_files</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_default_files</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current list of resource
files</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_default_files</function>() function
returns a list of filenames (as set by the <link
linkend="function-gtk--rc-set-default-files"><function>gtk.rc_set_default_files</function>()</link> 
function) that will be parsed for resource data.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-style-by-paths">
      <title>gtk.rc_get_style_by_paths</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_style_by_paths</methodname>
	  <methodparam><parameter
			 role="keyword">settings</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">widget_path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">class_path</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">type</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">settings</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">widget_path</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget path to use when looking up the
style</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">class_path</parameter>&nbsp;:</term>
	  <listitem><simpara>the class path to use when looking up the
style</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>a type that will be used along with parent
types of this type when matching against class styles, or
<literal>gobject.TYPE_NONE</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> created by
matching with the supplied paths, or <literal>None</literal> if nothing
matching was specified and the default style should be
used.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_style_by_paths</function>() function
returns a <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> created
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
<literal>PyGTK</literal> widgets. An example of this would be items inside a
<literal>GNOME</literal> canvas widget.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-reparse-all-for-settings">
      <title>gtk.rc_reparse_all_for_settings</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_reparse_all_for_settings</methodname>
	  <methodparam><parameter
			 role="keyword">settings</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">force_load</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">settings</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">force_load</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> reparse the RC files
even if they haven't changed</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the files were
reparsed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_reparse_all_for_settings</function>()
function reparses the files associated with the <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object specified by <parameter>settings</parameter> if any of the files have
changed and <parameter>force_load</parameter> is <literal>False</literal>
and . If <parameter>force_load</parameter> is <literal>True</literal> the
files are always reparsed.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-reset-styles">
      <title>gtk.rc_reset_styles</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_reset_styles</methodname>
    <methodparam><parameter role="keyword">settings</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">settings</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.rc_reset_styles</function>() function returns
a <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link>. This
function computes the styles for all widgets that use the <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object specified by <parameter>settings</parameter>. (There is one <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
object per <link
linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>, see
the <link
linkend="function-gtk--settings-get-for-screen"><function>gtk.settings_get_for_screen</function>()</link>
function). 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 explicitly on them with the <link
linkend="method-gtkwidget--set-style"><methodname>gtk.Widget.set_style</methodname>()</link>
method.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-parse">
      <title>gtk.rc_parse</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_parse</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of a file to parse for resource
data</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_parse</function>() function parses the file
specified by <parameter>filename</parameter> for resource data.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-parse-string">
      <title>gtk.rc_parse_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_parse_string</methodname>
	  <methodparam><parameter
			 role="keyword">rc_string</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">rc_string</parameter>&nbsp;:</term>
	  <listitem><simpara>a string to parse for resource
data</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_parse_string</function>() function parses
the string specified by <parameter>rc_string</parameter> for resource
data.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-reparse-all">
      <title>gtk.rc_reparse_all</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_reparse_all</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the files were
reparsed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_reparse_all</function>() function discards
all style data and reparses all the RC files for resource data if any of
them have changed.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-find-module-in-path">
      <title>gtk.rc_find_module_in_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_find_module_in_path</methodname>
	  <methodparam><parameter
			 role="keyword">module_file</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">module_file</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of a theme engine</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the filename of the theme engine or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_find_module_in_path</function>() function
searches for a theme engine named by <parameter>module_file</parameter>.
This function is not useful for applications and should not be used.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-theme-dir">
      <title>gtk.rc_get_theme_dir</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_theme_dir</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of the themes
directory</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_theme_dir</function>() function returns
the name of the directory where themes should be installed.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-module-dir">
      <title>gtk.rc_get_module_dir</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_module_dir</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the theme engines directory
name</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_module_dir</function>() function
returns the name of the directory where <literal>PyGTK</literal> searches
for theme engines.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-im-module-path">
      <title>gtk.rc_get_im_module_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_im_module_path</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the IM modules path</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_im_module_path</function>() function
returns the path where <literal>PyGTK</literal> searches for IM
modules.</para>

    </refsect2>

    <refsect2 id="function-gtk--rc-get-im-module-file">
      <title>gtk.rc_get_im_module_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.rc_get_im_module_file</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of the IM modules
file</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.rc_get_im_module_file</function>() function
returns the name of the <literal>PyGTK</literal> IM modules file.</para>

    </refsect2>

  </refsect1>

</refentry>