<?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-gtkiconfactory">
  <refnamediv>
    <refname>gtk.IconFactory</refname>
    <refpurpose>an object that manages a group of icon sets.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IconFactory</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkiconfactory">gtk.IconFactory</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconfactory--add">add</link></methodname>
	<methodparam><parameter
		       role="keyword">stock_id</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">icon_set</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconfactory--lookup">lookup</link></methodname>
	<methodparam><parameter
		       role="keyword">stock_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconfactory--add-default">add_default</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconfactory--remove-default">remove_default</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-factory-lookup-default">gtk.icon_factory_lookup_default</link></methodname>
	<methodparam><parameter role="keyword">stock_id</parameter>
	</methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkiconfactory">gtk.IconFactory</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkiconfactory">
    <title>gtk.IconFactory Signal Prototypes</title>

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

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>
manages a group of <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>s that
manage a set of variants (for different sizes and states) of a specific
icon. Icons in an icon factory are named by a stock ID, which is a simple
string identifying the icon e.g "gtk-ok". Each <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> has a list
of <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>s 
derived from the current theme; those icon factories are consulted first
when searching for an icon. If the theme doesn't set a particular icon, the
search continues for the icon in a list of default icon factories,
maintained by the <link
linkend="method-gtkiconfactory--add-default"><methodname>add_default</methodname>()</link>() 
and <link
linkend="method-gtkiconfactory--remove-default"><methodname>remove_default</methodname>()</link>() 
methods. Applications with icons should add a default icon factory with
their icons, which will allow themes to override the icons for the
application.</para>

    <para>To display an icon, always use <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link> 
on the widget that will display the icon, or the convenience function <link
linkend="method-gtkwidget--render-icon"><methodname>gtk.Widget.render_icon</methodname>()</link>. 
These functions take the theme into account when looking up the icon to use
for a given stock ID. </para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.IconFactory</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkiconfactory--add">
      <title>gtk.IconFactory.add</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">icon_set</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an icon name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">icon_set</parameter>&nbsp;:</term>
	  <listitem><simpara>an icon set</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>add</methodname>() method adds the specified
<parameter>icon_set</parameter> to the icon factory, under the name
<parameter>stock_id</parameter>.  the <parameter>stock_id</parameter> string
should include the name of your application, e.g. "myapp-whatever-icon".
Normally applications create a <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>, 
then add it to the list of default factories with the <link
linkend="method-gtkiconfactory--add-default"><methodname>add_default</methodname>()</link>. 
Then they pass the <parameter>stock_id</parameter> to widgets such as <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> to display
the icon. Themes can provide an icon with the same name (such as
"myapp-whatever-icon") to override your application's default icons. If an
icon already existed in the icon factory for
<parameter>stock_id</parameter>, it is unreferenced and replaced with the
new <parameter>icon_set</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkiconfactory--lookup">
      <title>gtk.IconFactory.lookup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>lookup</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an icon name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon set named
<parameter>stock_id</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>lookup</methodname>() method looks up
<parameter>stock_id</parameter> in the icon factory, returning an icon set
if found, otherwise <literal>None</literal>. For display to the user, you
should use <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link> 
on the <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> for the
widget that will display the icon, instead of using this function directly,
so that themes are taken into account.</para>

    </refsect2>

    <refsect2 id="method-gtkiconfactory--add-default">
      <title>gtk.IconFactory.add_default</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add_default</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>add_default</methodname>() method adds the icon
factory to the list of icon factories searched by <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link>. 
This means that, for example, <link
linkend="method-gtkimage--set-from-stock"><methodname>gtk.Image.set_from_stock</methodname>()</link> 
will be able to find icons in the icon factory. There will normally be an
icon factory added for each library or application that comes with icons.
The default icon factories can be overridden by themes.</para>

    </refsect2>

    <refsect2 id="method-gtkiconfactory--remove-default">
      <title>gtk.IconFactory.remove_default</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>remove_default</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>remove_default</methodname>() method removes an
icon factory from the list of default icon factories. Not normally used
though you might use it for a library that can be unloaded or shut
down.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--icon-factory-lookup-default">
      <title>gtk.icon_factory_lookup_default</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_factory_lookup_default</methodname>
	  <methodparam><parameter role="keyword">stock_id</parameter>
	  </methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>the stock ID to lookup</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon set matching
<parameter>stock_id</parameter> or <literal>None</literal> if no icon set
matches</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_factory_lookup_default</function>()
function returns the <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> that
has the name specified by <parameter>stock_id</parameter>. If the icon set
cannot be found the function returns <literal>None</literal>.</para>

    </refsect2>

  </refsect1>

</refentry>
