<?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-gtkicontheme">
  <refnamediv>
    <refname>gtk.IconTheme</refname>
    <refpurpose>look up icons by name and size (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IconTheme</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkicontheme">gtk.IconTheme</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--set-screen">set_screen</link></methodname>
	<methodparam><parameter role="keyword">screen</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--set-search-path">set_search_path</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--get-search-path">get_search_path</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--append-search-path">append_search_path</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--prepend-search-path">prepend_search_path</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--set-custom-theme">set_custom_theme</link></methodname>
	<methodparam><parameter role="keyword">theme_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--has-icon">has_icon</link></methodname>
	<methodparam><parameter role="keyword">icon_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--lookup-icon">lookup_icon</link></methodname>
	<methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	<methodparam><parameter role="keyword">size</parameter></methodparam>
	<methodparam><parameter role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--load-icon">load_icon</link></methodname>
	<methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	<methodparam><parameter role="keyword">size</parameter></methodparam>
	<methodparam><parameter role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--choose-icon">choose_icon</link></methodname>
	<methodparam><parameter role="keyword">icon_names</parameter></methodparam>
	<methodparam><parameter role="keyword">size</parameter></methodparam>
	<methodparam><parameter role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--list-contexts">list_contexts</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--list-icons">list_icons</link></methodname>
	<methodparam><parameter role="keyword">context</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--get-example-icon-name">get_example_icon_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--rescan-if-needed">rescan_if_needed</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--get-icon-sizes">get_icon_sizes</link></methodname>
	<methodparam><parameter role="keyword">icon_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkicontheme--lookup-by-gicon">lookup_by_gicon</link></methodname>
	<methodparam><parameter role="keyword">icon</parameter></methodparam>
	<methodparam><parameter role="keyword">size</parameter></methodparam>
	<methodparam><parameter role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--icon-theme-get-default">gtk.icon_theme_get_default</link></methodname>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--icon-theme-get-for-screen">gtk.icon_theme_get_for_screen</link></methodname>
    <methodparam><parameter role="keyword">screen</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--icon-theme-add-builtin-icon">gtk.icon_theme_add_builtin_icon</link></methodname>
    <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
    <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
  </methodsynopsis>
</programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkicontheme">gtk.IconTheme</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkicontheme">
    <title>gtk.IconTheme Signal Prototypes</title>

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

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkicontheme--changed">changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>icontheme</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

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

    <para><link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
provides a facility for looking up icons by name and size. The main reason
for using a name rather than simply providing a filename is to allow
different icons to be used depending on what icon theme is selected by the
user. The operation of icon themes on Linux and Unix follows the <ulink
url="http://www.freedesktop.org/Standards/icon-theme-spec">Icon Theme
Specification</ulink>). There is a default icon theme, named "hicolor" where
applications should install their icons, but more additional application
themes can be installed as operating system vendors and users choose.</para>

    <para>Named icons are similar to the Themeable Stock Images facility
(see <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>,
<link linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>
and <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>
for more detail), and the distinction between the two may be a bit
confusing. A few things to keep in mind:</para>

    <itemizedlist>
      <listitem>
	<para>Stock images usually are used in conjunction with <link
linkend="gtk-stock-items">Stock Items</link>, such as
<literal>gtk.STOCK_OK</literal> or <literal>gtk.STOCK_OPEN</literal>. Named
icons are easier to set up and therefore are more useful for new icons that
an application wants to add, such as application icons or window
icons.</para>
      </listitem>
      <listitem>
	<para>Stock images can only be loaded at the symbolic sizes defined
by the standard icon sizes (see the <link
linkend="function-gtk--icon-size-lookup"><function>gtk.icon_size_lookup</function>()</link>
function), or by custom sizes defined by the <link
linkend="function-gtk--icon-size-register"><function>gtk.icon_size_register</function>()</link>
function, while named icons are more flexible and any pixel size can be
specified.</para>
      </listitem>
      <listitem>
	<para>Because stock images are closely tied to stock items, and thus
to actions in the user interface, stock images may come in multiple variants
for different widget states or writing directions.</para>
      </listitem>
    </itemizedlist>

    <para>A good rule of thumb is that if there is a stock image for what
you want to use, use it, otherwise use a named icon. It turns out that
internally stock images are generally defined in terms of one or more named
icons. (An example is icons that depend on writing direction;
<literal>gtk.STOCK_GO_FORWARD</literal> uses the two themed icons
"gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".)</para>

    <para>In many cases, named themes are used indirectly, via <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> or stock
items, rather than directly, but looking up icons directly is also
simple. The <link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
object acts as a database of all the icons in the current theme. You can
create new <link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
objects, but its much more efficient to use the standard icon theme for the
<link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
so that the icon information is shared with other people looking up
icons. In the case where the default screen is being used, looking up an
icon can be as simple as:</para>

    <programlisting>
  icon_theme = gtk.icon_theme_get_default()
  try:
      pixbuf = icon_theme.load_icon("my-icon-name", 48, 0)
  except gobject.GError, exc:
      print "can't load icon", exc
</programlisting>

    <para></para>

  </refsect1>

  <refsect1 id="constructor-gtkicontheme">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.IconTheme</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>the newly created <link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
object.</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new icon theme object. Icon theme objects are used to
lookup up an icon by name in a particular icon theme.  Usually, you'll want
to use the <link
linkend="function-gtk--icon-theme-get-default"><function>gtk.icon_theme_get_default</function>()</link>
or <link
linkend="function-gtk--icon-theme-get-for-screen"><function>gtk.icon_theme_get_for_screen</function>()</link>
functions rather than creating a new icon theme object from scratch.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkicontheme--set-screen">
      <title>gtk.IconTheme.set_screen</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_screen</methodname>
	  <methodparam><parameter role="keyword">screen</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_screen</methodname>() method sets the <link
linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link> for
an icon theme to <parameter>screen</parameter>. The screen is used to track
the user's currently configured icon theme, which might be different for
different screens.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--set-search-path">
      <title>gtk.IconTheme.set_search_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_search_path</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a list or tuple of directories that are
	  searched for icon themes</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_search_path</methodname>() method sets the
search path for the icon theme object to the list of directory names
contained in <parameter>path</parameter>. When looking for an icon theme,
<literal>GTK+</literal> will search for a subdirectory of one or more of the
directories in <parameter>path</parameter> with the same name as the icon
theme. (Themes from multiple of the path elements are combined to allow
themes to be extended by adding icons in the user's home directory.)</para>

      <para>In addition if an icon found isn't found either in the current
icon theme or the default icon theme, and an image file with the right name
is found directly in one of the elements of <parameter>path</parameter>,
then that image will be used for the icon name. (This is a legacy feature,
and new icons should be put into the default icon theme, which is called
"hicolor", rather than directly on the icon path.)</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--get-search-path">
      <title>gtk.IconTheme.get_search_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_search_path</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the list of directory names
	  that are searched for icon themes</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_search_path</methodname>() method returns a
tuple containing the current search path. See the <link
linkend="method-gtkicontheme--set-search-path"><methodname>set_search_path()</methodname></link>
method for more details.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--append-search-path">
      <title>gtk.IconTheme.append_search_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>append_search_path</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a directory name to append to the icon
path</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>append_search_path</methodname>() method appends
the directory name specified by <parameter>path</parameter> to the search
path. See the <link
linkend="method-gtkicontheme--set-search-path"><methodname>set_search_path()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--prepend-search-path">
      <title>gtk.IconTheme.prepend_search_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>prepend_search_path</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a directory name to prepend to the icon
path</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>prepend_search_path</methodname>() method
prepends the directory name specified by <parameter>path</parameter> to the
search path. See the <link
linkend="method-gtkicontheme--set-search-path"><methodname>set_search_path()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--set-custom-theme">
      <title>gtk.IconTheme.set_custom_theme</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_custom_theme</methodname>
	  <methodparam><parameter role="keyword">theme_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">theme_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of icon theme to use instead of
the configured theme</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_custom_theme</methodname>() method sets the
theme used by the icon theme object to the theme named by
<parameter>theme_name</parameter> usually replacing system configured
theme. This method cannot be called on the icon theme objects returned from
the <link
linkend="function-gtk--icon-theme-get-default"><function>gtk.icon_theme_get_default</function>()</link>
and <link
linkend="function-gtk--icon-theme-get-default"><function>gtk.icon_theme_get_default</function>()</link>
functions.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--has-icon">
      <title>gtk.IconTheme.has_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>has_icon</methodname>
	  <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of an icon</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the icon theme
	  includes an icon for
	  <parameter>icon_name</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>has_icon</methodname>() method checks whether
the icon theme includes an icon for the icon name specified by
<parameter>icon_name</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--lookup-icon">
      <title>gtk.IconTheme.lookup_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>lookup_icon</methodname>
	  <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	  <methodparam><parameter role="keyword">size</parameter></methodparam>
	  <methodparam><parameter role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the icon to lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the desired icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the flags modifying the behavior of the icon
	  lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>
	  object containing information about the icon, or
	  <literal>None</literal> if the icon wasn't found. Free with the
	  <link
	  linkend="method-gtkiconinfo--free"><methodname>gtk.IconInfo.free()</methodname></link>
	  method</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>lookup_icon</methodname>() method looks up the
icon specified by <parameter>icon_name</parameter>,
<parameter>size</parameter> and <parameter>flags</parameter> and returns a
<link linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>
object containing information such as the filename of the icon. The icon can
then be rendered into a pixbuf using the <link
linkend="method-gtkiconinfo--load-icon"><methodname>gtk.IconInfo.load_icon()</methodname></link>
method. (the <link
linkend="method-gtkicontheme--load-icon"><methodname>load_icon()</methodname></link>
method combines these two steps if all you need is the pixbuf.)</para>

      <para>The value of flags must be a combination of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.ICON_LOOKUP_NO_SVG</literal></term>
	  <listitem>
	    <simpara>Never return Scalable Vector Graphics (SVG) icons, even
	    if gdk-pixbuf supports them. Cannot be used together with
	    <literal>gtk.ICON_LOOKUP_FORCE_SVG</literal>.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.ICON_LOOKUP_FORCE_SVG</literal></term>
	  <listitem>
	    <simpara> Return SVG icons, even if gdk-pixbuf doesn't support
	    them. Cannot be used together with
	    <literal>gtk.ICON_LOOKUP_NO_SVG</literal>.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.ICON_LOOKUP_USE_BUILTIN</literal></term>
	  <listitem>
	    <simpara>When passed to the <link
	    linkend="method-gtkicontheme--lookup-icon"><methodname>lookup_icon</methodname>()</link>
	    method includes builtin icons as well as files. For a builtin
	    icon, the <link
	    linkend="method-gtkiconinfo--get-filename"><methodname>gtk.IconInfo.get_filename</methodname>()</link>
	    method returns <literal>None</literal> and you need to call the
	    <link
	    linkend="method-gtkiconinfo--get-builtin-pixbuf"><methodname>get_builtin_pixbuf</methodname>()</link>
	    method.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--load-icon">
      <title>gtk.IconTheme.load_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>load_icon</methodname>
	  <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	  <methodparam><parameter role="keyword">size</parameter></methodparam>
	  <methodparam><parameter role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the icon to lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the desired icon size. The resulting icon may
	  not be exactly this size; see the <link
	  linkend="method-gtkiconinfo--load-icon"><methodname>gtk.IconInfo.load_icon()</methodname></link>
	  method.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the flags modifying the behavior of the icon
	  lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
	  containing the rendered icon; this may be a newly created icon or
	  a new reference to an internal icon, so you must not modify the
	  icon.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>load_icon</methodname>() method looks up the
icon specified by <parameter>icon_name</parameter> in an icon theme, scales
it to the size specified by <parameter>size</parameter> and renders it into
a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>. flags
is a combination of: <literal>gtk.ICON_LOOKUP_FORCE_SVG</literal>,
<literal>gtk.ICON_LOOKUP_NO_SVG</literal> and
<literal>gtk.ICON_LOOKUP_USE_BUILTIN</literal> (see the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>lookup_icon</methodname>()</link>
method for more details). Since this is a convenience function, if more
details about the icon are needed, use the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>lookup_icon()</methodname></link>
method followed by the <link
linkend="method-gtkiconinfo--load-icon"><methodname>GtkIconInfo.load_icon()</methodname></link>
method.</para>

      <para>This method raise the GError exception if an error occurs during
rendering of the icon.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--choose-icon">
      <title>gtk.IconTheme.choose_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>choose_icon</methodname>
	  <methodparam><parameter role="keyword">icon_names</parameter></methodparam>
	  <methodparam><parameter role="keyword">size</parameter></methodparam>
	  <methodparam><parameter role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_names</parameter>&nbsp;:</term>
	  <listitem><simpara>A list or tuple of icon names to lookup.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>The desired icon size.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the flags modifying the behavior of the icon
	  lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>.
      structure containing information about the icon, or <literal>None</literal>
      if the icon wasn't found.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.12 and above.</para>
      </note>

      <para>
        The <methodname>choose_icon</methodname>() method looks up a named icon and
        returns a structure containing information such as the filename of the icon.
        The icon can then be rendered into a pixbuf using
        <methodname><link linkend="method-gtkiconinfo--load-icon">gtk.IconInfo.load_icon</link></methodname>.
        <methodname><link linkend="method-gtkicontheme--load-icon">load_icon</link></methodname>
        combines these two steps if all you need is the pixbuf.)
      </para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--list-contexts">
      <title>gtk.IconTheme.list_contexts</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>list_contexts</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A list holding the names of all the
      contexts in the theme. </simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.12 and above.</para>
      </note>

      <para>The <methodname>list_contexts</methodname>() method gets the list of contexts
      available within the current hierarchy of icon themes</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--list-icons">
      <title>gtk.IconTheme.list_icons</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>list_icons</methodname>
	  <methodparam><parameter role="keyword">context</parameter><initializer>None</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">context</parameter>&nbsp;:</term>
	  <listitem><simpara>a string identifying a particular type of icon,
	  or <literal>None</literal> to list all icons.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the names of all the
icons in the theme.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>list_icons</methodname>() method lists the icons
in the current icon theme. Only a subset of the icons can be listed by
providing a string specified by <parameter>context</parameter>.  The set of
values for the context string is system dependent, but will typically
include such values as 'apps' and 'mimetypes'.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--get-example-icon-name">
      <title>gtk.IconTheme.get_example_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_example_icon_name</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of an example icon or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_example_icon_name</methodname>() method
returns the name of an icon that is representative of the current theme (for
instance, to use when presenting a list of themes to the user.)</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--rescan-if-needed">
      <title>gtk.IconTheme.rescan_if_needed</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>rescan_if_needed</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the icon theme has
	  changed and needed to be reloaded.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>rescan_if_needed</methodname>() method checks to
see if the icon theme has changed; if it has, any currently cached
information is discarded and will be reloaded next time the icon theme is
accessed.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--get-icon-sizes">
      <title>gtk.IconTheme.get_icon_sizes</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_sizes</methodname>
	  <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of an icon</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the sizes that the icon is
available in.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_icon_sizes</methodname>() method returns a
tuple containing the sizes available for the icon named by
<parameter>icon_name</parameter>. A size of -1 means the icon is
scalable. If the icon is not found an empty tuple is returned.</para>

    </refsect2>

    <refsect2 id="method-gtkicontheme--lookup-by-gicon">
      <title>gtk.IconTheme.lookup_by_gicon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>lookup_by_gicon</methodname>
	  <methodparam><parameter role="keyword">icon</parameter></methodparam>
	  <methodparam><parameter role="keyword">size</parameter></methodparam>
	  <methodparam><parameter role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link linkend="class-gioicon"><classname>gio.Icon</classname></link>
	  to lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>The desired icon size.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the flags modifying the behavior of the icon
	  lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>.
      structure containing information about the icon, or <literal>None</literal>
      if the icon wasn't found.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
        The <methodname>lookup_by_gicon</methodname>() method Looks up an icon
	and returns a structure containing information such as the filename of
	the icon. The icon can then be rendered into a pixbuf using
	<methodname><link linkend="method-gtkiconinfo--load-icon">gtk.IconInfo.load_icon</link></methodname>().
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--icon-theme-get-default">
      <title>gtk.icon_theme_get_default</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_theme_get_default</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A unique <link
	  linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
	  associated with the default <link
	  linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>. This
	  icon theme is associated with the screen and can be used as long
	  as the screen is open.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.icon_them_get_default</function>() function
returns the icon theme for the default screen. See the <link
linkend="function-gtk--icon-theme-get-for-screen"><function>gtk.icon_theme_get_for_screen</function>()</link>
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-theme-get-for-screen">
      <title>gtk.icon_theme_get_for_screen</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_theme_get_for_screen</methodname>
	  <methodparam><parameter
			 role="keyword">screen</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
	  object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A unique <link
	  linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>
	  associated with the default <link
	  linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>. This
	  icon theme is associated with the screen and can be used as long
	  as the screen is open.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.icon_theme_get_for_screen</function>()
function returns the icon theme object associated with the <link
linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
specified by <parameter>screen</parameter>. If this function has not
previously been called for the given screen, a new icon theme object will be
created and associated with the screen. Icon theme objects are fairly
expensive to create, so using this function is usually a better choice than
calling the <link linkend="constructor-gtkicontheme">gtk.IconTheme</link>()
constructor and setting the screen yourself; by using this function a single
icon theme object will be shared between users.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-theme-add-builtin-icon">
      <title>gtk.icon_theme_add_builtin_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_theme_add_builtin_icon</methodname>
	  <methodparam><parameter
			 role="keyword">icon_name</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara> the name of the icon to
	  register</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara> the size at which to register the icon
	  (different images can be registered for the same icon name at
	  different sizes.)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
	  that contains the image to use for
	  <parameter>icon_name</parameter>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.icon_theme_add_builtin_icon</function>()
function registers a built-in icon for icon theme lookups using
<parameter>icon_name</parameter> as the icon name,
<parameter>size</parameter> as the icon size and
<parameter>pixbuf</parameter> as the icon image. The idea of built-in icons
is to allow an application or library that uses themed icons to function
without requiring specific icon files to be present in the file system. For
instance, the default images for all of <literal>GTK+</literal>'s stock
icons are registered as built-icons.</para>

      <para>In general, if you use
<function>gtk.icon_theme_add_builtin_icon</function>() you should also
install the icon in the icon theme, so that the icon is generally
available. This function will generally be used with pixbufs loaded via the
<link
linkend="function-gdk--pixbuf-new-from-inline"><function>gtk.gdk.pixbuf_new_from_inline</function>()</link>
function.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkicontheme--changed">
      <title>The "changed" gtk.IconTheme Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>icontheme</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>icontheme</parameter>&nbsp;:</term>
	  <listitem><simpara>the icontheme that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The "changed" signal is emitted when the current icon theme is
switched or <literal>GTK+</literal> detects that a change has occurred in
the contents of the current icon theme.</para>

    </refsect2>

  </refsect1>

</refentry>