<?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-gtkiconset">
  <refnamediv>
    <refname>gtk.IconSet</refname>
    <refpurpose>contains a set of variants for an icon</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IconSet</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkiconset">gtk.IconSet</link></methodname>
	<methodparam><parameter
		       role="keyword">pixbuf</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconset--copy">copy</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconset--render-icon">render_icon</link></methodname>
	<methodparam><parameter
		       role="keyword">style</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">direction</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">state</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">widget</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">detail</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconset--add-source">add_source</link></methodname>
	<methodparam><parameter
		       role="keyword">source</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconset--get-sizes">get_sizes</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>
contains a set of variants for a single icon. The variants provide icons of
different sizes and for different widget states. The variants can be added
with the <link
linkend="method-gtkiconset--add-source"><methodname>add_source</methodname>()</link> 
method.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.IconSet</methodname>
	<methodparam><parameter
		       role="keyword">pixbuf</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	<listitem><simpara>a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> with
<parameter>pixbuf</parameter> as the default fallback source image. If
<parameter>pixbuf</parameter> is <literal>None</literal> there is no default
fallback source image. If you don't add any additional <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>s
to the icon set, all variants of the icon will be created from
<parameter>pixbuf</parameter>, using scaling, pixelation, etc. as required
to adjust the icon size or make the icon look insensitive/prelighted.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkiconset--copy">
      <title>gtk.IconSet.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-gtkiconset"><classname>gtk.IconSet</classname></link>
identical to the first.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>copy</methodname>() method returns a copy of the
icon set.</para>

    </refsect2>

    <refsect2 id="method-gtkiconset--render-icon">
      <title>gtk.IconSet.render_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>render_icon</methodname>
	  <methodparam><parameter
			 role="keyword">style</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">direction</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">state</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">widget</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">detail</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">style</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> associated
with <parameter>widget</parameter>, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">direction</parameter>&nbsp;:</term>
	  <listitem><simpara>the text direction; one of:
<literal>gtk.TEXT_DIR_NONE</literal>, <literal>gtk.TEXT_DIR_LTR</literal>,
<literal>gtk.TEXT_DIR_RTL</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">state</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget state; one of:
<literal>gtk.STATE_NORMAL</literal>, <literal>gtk.STATE_ACTIVE</literal>,
<literal>gtk.STATE_PRELIGHT</literal>,
<literal>gtk.STATE_SELECTED</literal>,
<literal>gtk.STATE_INSENSITIVE</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the icon size; one of:
<literal>gtk.ICON_SIZE_INVALID</literal>,
<literal>gtk.ICON_SIZE_MENU</literal>,
<literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal>,
<literal>gtk.ICON_SIZE_LARGE_TOOLBAR</literal>,
<literal>gtk.ICON_SIZE_BUTTON</literal>,
<literal>gtk.ICON_SIZE_DND</literal>,
<literal>gtk.ICON_SIZE_DIALOG</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget that will display the icon, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">detail</parameter>&nbsp;:</term>
	  <listitem><simpara>the detail to pass to the theme engine, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> to be
displayed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>render_icon</methodname>() method renders an
icon using <link
linkend="method-gtkstyle--render-icon"><function>gtk.Style.render_icon()</function></link>. 
In most cases, <link
linkend="method-gtkwidget--render-icon"><function>gtk.Widget.render_icon()</function></link> 
is better, since it automatically provides most of the arguments from the
current widget settings.  This method never returns <literal>None</literal>;
if the icon can't be rendered (perhaps because an image file fails to load),
a default "missing image" icon will be returned instead.</para>

    </refsect2>

    <refsect2 id="method-gtkiconset--add-source">
      <title>gtk.IconSet.add_source</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add_source</methodname>
	  <methodparam><parameter
			 role="keyword">source</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">source</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>add_source</methodname>() method adds the <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>
specified by <parameter>source</parameter> to the icon set.  Icon sets have
a list of <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>,
which they use as base icons for rendering icons in different states and
sizes. Icons are scaled, made to look insensitive, etc. in the <link
linkend="method-gtkiconset--render-icon"><methodname>render_icon</methodname>()</link>
method, but <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> needs
base images to work with. The base images and when to use them are described
by a <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>.</para>

      <para>An example of when you'd use this method: a web browser's
"<guibutton>Back to Previous Page</guibutton>" icon might point in a
different direction in Hebrew and in English; it might look different when
insensitive; and it might change size depending on toolbar mode (small
or large icons). So a single icon set would contain all those variants of the
icon, and you might add a separate source for each one.</para>

      <para>You should nearly always add a "default" icon source with all
fields wildcarded, which will be used as a fallback if no more specific
source matches. <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> always
prefers more specific icon sources to more generic icon sources. The order
in which you add the sources to the icon set does not matter.</para>

      <para>The <link
linkend="constructor-gtkiconset"><methodname>gtk.IconSet</methodname>()</link> 
constructor creates a new icon set with a default icon source based on the
given pixbuf.</para>

    </refsect2>

    <refsect2 id="method-gtkiconset--get-sizes">
      <title>gtk.IconSet.get_sizes</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_sizes</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing all the icon sizes supported
by the icon set</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_sizes</methodname>() method returns a tuple
containing all the icon sizes this icon set can render.</para>

    </refsect2>

  </refsect1>

</refentry>
