path: root/docs/reference/pygtk-gtkiconsource.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-gtkiconsource">
  <refnamediv>
    <refname>gtk.IconSource</refname>
    <refpurpose>a source for icon variants</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IconSource</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkiconsource">gtk.IconSource</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--copy">copy</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--free">free</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-filename">set_filename</link></methodname>
	<methodparam><parameter
		       role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-pixbuf">set_pixbuf</link></methodname>
	<methodparam><parameter
		       role="keyword">pixbuf</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-filename">get_filename</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-pixbuf">get_pixbuf</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-direction-wildcarded">set_direction_wildcarded</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-state-wildcarded">set_state_wildcarded</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-size-wildcarded">set_size_wildcarded</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-size-wildcarded">get_size_wildcarded</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-state-wildcarded">get_state_wildcarded</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-direction-wildcarded">get_direction_wildcarded</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-direction">set_direction</link></methodname>
	<methodparam><parameter
		       role="keyword">direction</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-state">set_state</link></methodname>
	<methodparam><parameter
		       role="keyword">state</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-size">set_size</link></methodname>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-direction">get_direction</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-state">get_state</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-size">get_size</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--set-state">set_icon_name</link></methodname>
	<methodparam><parameter
		       role="keyword">icon_name</parameter></methodparam>
      </methodsynopsis>
     <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkiconsource--get-size">get_icon_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-lookup">gtk.icon_size_lookup</link></methodname>
	<methodparam><parameter
		       role="keyword">icon_size</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-lookup-for-settings">gtk.icon_size_lookup_for_settings</link></methodname>
	<methodparam><parameter
		       role="keyword">settings</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">icon_size</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-register">gtk.icon_size_register</link></methodname>
	<methodparam><parameter
		       role="keyword">name</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">width</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">height</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-register-alias">gtk.icon_size_register_alias</link></methodname>
	<methodparam><parameter
		       role="keyword">alias</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">target</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-from-name">gtk.icon_size_from_name</link></methodname>
	<methodparam><parameter
		       role="keyword">name</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--icon-size-get-name">gtk.icon_size_get_name</link></methodname>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>
contains a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> (or
an image filename) that serves as the base image for one or more of the
icons in a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>, along
with a specification for which icons in the icon set will be based on that
pixbuf or image file. By default, the icon source has all parameters
wildcarded. That is, the icon source can be used as the base icon for any
desired text direction, widget state, or icon size.</para>

  </refsect1>

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

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

    <para>Creates a new <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>.
A <link
linkend="class-gtkiconsource"><classname>gtk.IconSource</classname></link>
contains a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> (or
image filename) that serves as the base image for one or more of the icons
in a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>, along
with a specification for which icons in the icon set will be based on that
pixbuf or image file. By default, the icon source has all parameters
wildcarded. That is, the icon source will be used as the base icon for any
desired text direction, widget state, or icon size.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkiconsource--copy">
      <title>gtk.IconSource.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-gtkiconsource"><classname>gtk.IconSource</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>copy</methodname>() method creates a copy of the
icon source.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--free">
      <title>gtk.IconSource.free</title>

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

      <warning>
        <para>This method is deprecated and should not be used. Use of this
method may cause your application to crash.</para>
      </warning>

      <para>The <methodname>free</methodname>() method frees a
dynamically-allocated icon source, along with its filename, size, and pixbuf
fields if those are not <literal>None</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-filename">
      <title>gtk.IconSource.set_filename</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_filename</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>the image file to use</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_filename</methodname>() method sets the name
of the image file (specified by <parameter>filename</parameter>) to use as
the base image when creating icon variants for a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>. The
filename must be absolute.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-pixbuf">
      <title>gtk.IconSource.set_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_pixbuf</methodname>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>the pixbuf to use as a
source</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_pixbuf</methodname>() method sets a pixbuf
(specified by <parameter>pixbuf</parameter>) to use as a base image when
creating icon variants for a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>. If an
icon source has both a filename and a pixbuf set, the pixbuf will take
priority.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-filename">
      <title>gtk.IconSource.get_filename</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_filename</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the image filename</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_filename</methodname>() method retrieves the
source filename, or <literal>None</literal> if none is set.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-pixbuf">
      <title>gtk.IconSource.get_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_pixbuf</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the source pixbuf</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_pixbuf</methodname>() method retrieves the
source pixbuf, or <literal>None</literal> if none is set.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-direction-wildcarded">
      <title>gtk.IconSource.set_direction_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_direction_wildcarded</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> wildcard the text
direction</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_direction_wildcarded</methodname>() method
determines whether the icon source direction is wildcarded according to the
value specified by <parameter>setting</parameter>. If
<parameter>setting</parameter> is <literal>True</literal> the text direction
is wildcarded and the icon source can be used as the base image for an icon
in any text direction (<literal>gtk.TEXT_DIR_NONE</literal>,
<literal>gtk.TEXT_DIR_LTR</literal> or <literal>gtk.TEXT_DIR_RTL</literal>).
If the text direction is not wildcarded, then the text direction the icon
source applies to should be set with the <link
linkend="method-gtkiconsource--set-direction"><methodname>set_direction</methodname>()</link> 
method and the icon source will only be used with that text direction.
Non-wildcarded icon sources (exact matches) are preferred over wildcarded
icon sources. An exact match will be used when possible.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-state-wildcarded">
      <title>gtk.IconSource.set_state_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_state_wildcarded</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> wildcard the widget
state</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_state_wildcarded</methodname>() method
determines whether the icon source state is wildcarded according to the
value of <parameter>setting</parameter>. If <parameter>setting</parameter>
is <literal>True</literal> the widget state is wildcarded and the icon
source can be used as the base image for an icon in any widget state
(<literal>gtk.STATE_NORMAL</literal>, <literal>gtk.STATE_ACTIVE</literal>,
<literal>gtk.STATE_PRELIGHT</literal>, <literal>gtk.STATE_SELECTED</literal>
or <literal>gtk.STATE_INSENSITIVE</literal>). If the widget state is not
wildcarded, then the widget state the icon source applies to should be set
with the <link
linkend="method-gtkiconsource--set-state"><methodname>set_state</methodname>()</link> 
method and the icon source will only be used with that specific state.
Non-wildcarded icon sources (exact matches) are preferred over wildcarded
icon sources. An exact match will be used when possible.</para>

      <para>A <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> will
normally transform wildcarded icon source images to produce an appropriate
icon for a given state, for example lightening an image on prelight, but
will not modify source images that match exactly.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-size-wildcarded">
      <title>gtk.IconSource.set_size_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_size_wildcarded</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> wildcard the widget
state</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_size_wildcarded</methodname>() determines
whether the icon source can be used as the basis for an icon of any size
according to the value of <parameter>setting</parameter>. If
<parameter>setting</parameter> is <literal>True</literal> the icon size is
wildcarded and the icon source can be used as the base image for an icon of
any size.  If the size is not wildcarded, then the size the icon source
applies to should be set with <link
linkend="method-gtkiconsource--set-size"><function>gtk.IconSource.set_size()</function></link> 
and the icon source will only be used with that specific size.
Non-wildcarded icon sources (exact matches) are preferred over wildcarded
icon sources. An exact match will be used when possible.</para>

      <para><link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> will
normally scale wildcarded source images to produce an appropriate icon at a
given size, but will not change the size of source images that match
exactly.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-size-wildcarded">
      <title>gtk.IconSource.get_size_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size_wildcarded</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if this icon source is
a base for any icon size variant</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_size_wildcarded</methodname>() method gets
the value set by the <link
linkend="method-gtkiconsource--set-size-wildcarded"><methodname>set_size_wildcarded</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-state-wildcarded">
      <title>gtk.IconSource.get_state_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_state_wildcarded</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if this icon source is
a base for any widget state variant</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_state_wildcarded</methodname>() method gets
the value set by the <link
linkend="method-gtkiconsource--set-state-wildcarded"><methodname>set_state_wildcarded</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-direction-wildcarded">
      <title>gtk.IconSource.get_direction_wildcarded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_direction_wildcarded</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if this icon source is
a base for any text direction variant</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_direction_wildcarded</methodname>() method
gets the value set by the <link
linkend="method-gtkiconsource--set-direction-wildcarded"><methodname>set_direction_wildcarded</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-direction">
      <title>gtk.IconSource.set_direction</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_direction</methodname>
	  <methodparam><parameter
			 role="keyword">direction</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">direction</parameter>&nbsp;:</term>
	  <listitem><simpara>the text direction this icon source applies
to</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_direction</methodname>() method sets the
text direction according to the value of <parameter>direction</parameter>
that the icon source is intended to be used with. The value of direction
must be one of: <literal>gtk.TEXT_DIR_NONE</literal>,
<literal>gtk.TEXT_DIR_LTR</literal> or
<literal>gtk.TEXT_DIR_RTL</literal>.</para>

      <para>Setting the text direction on an icon source makes no difference
if the text direction is wildcarded. Therefore, you should usually call the
<link
linkend="method-gtkiconsource--set-direction-wildcarded"><methodname>set_direction_wildcarded</methodname>()</link> 
method with a setting of <literal>False</literal> to un-wildcard it in
addition to calling this function.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-state">
      <title>gtk.IconSource.set_state</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_state</methodname>
	  <methodparam><parameter
			 role="keyword">state</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">state</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget state this source applies
to</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_state</methodname>() method sets the widget
state specified by <parameter>state</parameter> that the icon source is
intended to be used with. The value of <parameter>state</parameter> must be
one of: <literal>gtk.STATE_NORMAL</literal>,
<literal>gtk.STATE_ACTIVE</literal>, <literal>gtk.STATE_PRELIGHT</literal>,
<literal>gtk.STATE_SELECTED</literal> or
<literal>gtk.STATE_INSENSITIVE</literal>. Setting the widget state on an
icon source makes no difference if the state is wildcarded. Therefore, you
should usually call the <link
linkend="method-gtkiconsource--set-state-wildcarded"><methodname>set_state_wildcarded</methodname>()</link> 
method with a setting of <literal>False</literal> to un-wildcard it in
addition to calling this function.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-size">
      <title>gtk.IconSource.set_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_size</methodname>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the icon size this source applies
to</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_size</methodname>() method sets the icon
size specified by <parameter>size</parameter> that the icon source is
intended to be used with. Setting the icon size for an icon source makes no
difference if the size is wildcarded. Therefore, you should usually call the
<link
linkend="method-gtkiconsource--set-size-wildcarded"><function>gtk.IconSource.set_size_wildcarded()</function></link> 
method with a setting of <literal>False</literal> to un-wildcard it in
addition to calling this function.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-direction">
      <title>gtk.IconSource.get_direction</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_direction</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the text direction the icon source
matches</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_direction</methodname>() method obtains the
text direction this icon source applies to. The return value is only useful
and meaningful if the text direction is <emphasis>not</emphasis>
wildcarded.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-state">
      <title>gtk.IconSource.get_state</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_state</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the widget state the icon source
matches</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_state</methodname>() method obtains the
widget state this icon source applies to. The return value is only useful
and meaningful if the widget state is <emphasis>not</emphasis>
wildcarded.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-size">
      <title>gtk.IconSource.get_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon size this source
matches.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_size</methodname>() method obtains the icon
size this source applies to. The return value is only useful and meaningful
if the icon size is <emphasis>not</emphasis> wildcarded.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--set-icon-name">
      <title>gtk.IconSource.set_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_name</methodname>
	  <methodparam><parameter
			 role="keyword">icon_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>an icon name
to</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_icon_name</methodname>() method uses the
name specified by <parameter>icon_name</parameter> to look up an icon in the
current icon theme to use as a base image when creating icon variants for
<link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>.</para>

      <para>In PyGTK 2.10 and above, <parameter>icon_name</parameter> may be
<literal>None</literal> to unset the icon name.</para>

    </refsect2>

    <refsect2 id="method-gtkiconsource--get-icon-name">
      <title>gtk.IconSource.get_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_name</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon name or <literal>None</literal> if no
name is set.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_icon</methodname>() method returns the
 source icon name, or <literal>None</literal> if no name is set.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--icon-size-lookup">
      <title>gtk.icon_size_lookup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_lookup</methodname>
	  <methodparam><parameter
			 role="keyword">icon_size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">icon_size</parameter>&nbsp;:</term>
	  <listitem><simpara> an icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the width and height of
the specified <parameter>icon_size</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_size_lookup</function>() function returns
a 2-tuple containing the width and height of the icon size specified by
<parameter>icon_size</parameter>. The value of
<parameter>icon_size</parameter> must be one of:</para>

      <itemizedlist>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_MENU</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_LARGE_TOOLBAR</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_BUTTON</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_DND</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_DIALOG</literal></simpara>
	</listitem>
      </itemizedlist>

      <para>or an integer value returned from the <link
linkend="function-gtk--icon-size-register"><function>gtk.icon_size_register</function>()</link> 
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-size-lookup-for-settings">
      <title>gtk.icon_size_lookup_for_settings</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_lookup_for_settings</methodname>
	  <methodparam><parameter
			 role="keyword">settings</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">icon_size</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 used to determine which user preferences to use.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">icon_size</parameter>&nbsp;:</term>
	  <listitem><simpara> an icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the width and height of
the specified <parameter>icon_size</parameter> or <literal>None</literal>
if <parameter>icon_size</parameter> was invalid.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.icon_size_lookup_for_settings</function>()
function returns a 2-tuple containing the width and height of the icon size
specified by <parameter>icon_size</parameter> of <literal>None</literal> if
<parameter>icon_size</parameter> was not valid. The value of
<parameter>icon_size</parameter> must be one of:</para>

      <itemizedlist>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_MENU</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_LARGE_TOOLBAR</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_BUTTON</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_DND</literal></simpara>
	</listitem>
	<listitem>
	  <simpara><literal>gtk.ICON_SIZE_DIALOG</literal></simpara>
	</listitem>
      </itemizedlist>

      <para>or an integer value returned from the <link
linkend="function-gtk--icon-size-register"><function>gtk.icon_size_register</function>()</link> 
function.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-size-register">
      <title>gtk.icon_size_register</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_register</methodname>
	  <methodparam><parameter
			 role="keyword">name</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">width</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">height</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">width</parameter>&nbsp;:</term>
	  <listitem><simpara>the width of the icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">height</parameter>&nbsp;:</term>
	  <listitem><simpara>the height of the icon
size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer representing the icon
size</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_size_register</function>() function
registers a new icon size for the specified <parameter>width</parameter> and
<parameter>height</parameter> with the specified <parameter>name</parameter>
and returns the integer used to represent the icon size.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-size-register-alias">
      <title>gtk.icon_size_register_alias</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_register_alias</methodname>
	  <methodparam><parameter
			 role="keyword">alias</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">target</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">alias</parameter>&nbsp;:</term>
	  <listitem><simpara>an alias for
<parameter>target</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">target</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer representing an existing icon
size</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_size_register_alias</function>() function
registers the specified <parameter>alias</parameter> as another name for the
icon size specified by <parameter>target</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-size-from-name">
      <title>gtk.icon_size_from_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_from_name</methodname>
	  <methodparam><parameter
			 role="keyword">name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">name</parameter>&nbsp;:</term>
	  <listitem><simpara>a name of an existing icon
size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon size associated with
<parameter>name</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_size_from_name</function>() function
returns the integer representing the icon size associated with the specified
<parameter>name</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--icon-size-get-name">
      <title>gtk.icon_size_get_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.icon_size_get_name</methodname>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer representing an existing icon
size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name associated with the icon size
represented by <parameter>size</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.icon_size_get_name</function>() function
returns the name of the icon size represented by
<parameter>size</parameter>.</para>

    </refsect2>

  </refsect1>

</refentry>