path: root/docs/reference/pygtk-gtkimage.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-gtkimage">
  <refnamediv>
    <refname>gtk.Image</refname>
    <refpurpose>A widget displaying an image
</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Image</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkmisc">gtk.Misc</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkimage">gtk.Image</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-pixmap">set_from_pixmap</link></methodname>
	<methodparam><parameter
		       role="keyword">pixmap</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">mask</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-image">set_from_image</link></methodname>
	<methodparam><parameter
		       role="keyword">gdk_image</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">mask</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-file">set_from_file</link></methodname>
	<methodparam><parameter
		       role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-pixbuf">set_from_pixbuf</link></methodname>
	<methodparam><parameter
		       role="keyword">pixbuf</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-stock">set_from_stock</link></methodname>
	<methodparam><parameter
		       role="keyword">stock_id</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-icon-set">set_from_icon_set</link></methodname>
	<methodparam><parameter
		       role="keyword">icon_set</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-animation">set_from_animation</link></methodname>
	<methodparam><parameter
		       role="keyword">animation</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-storage-type">get_storage_type</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-pixmap">get_pixmap</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-image">get_image</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-pixbuf">get_pixbuf</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-stock">get_stock</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-icon-set">get_icon_set</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-animation">get_animation</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-icon-name">get_icon_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-from-icon-name">set_from_icon_name</link></methodname>
	<methodparam><parameter
		       role="keyword">icon_name</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--set-pixel-size">set_pixel_size</link></methodname>
	<methodparam><parameter
		       role="keyword">pixel_size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--get-pixel-size">get_pixel_size</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkimage--clear">clear</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkimage--set-from-gicon">set_from_gicon</link></methodname>
	<methodparam><parameter role="keyword">gicon</parameter></methodparam>
	<methodparam><parameter role="keyword">size</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-stock">gtk.image_new_from_stock</link></methodname>
    <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-icon-set">gtk.image_new_from_icon_set</link></methodname>
    <methodparam><parameter role="keyword">icon_set</parameter></methodparam>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-animation">gtk.image_new_from_animation</link></methodname>
    <methodparam><parameter role="keyword">animation</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-animation">gtk.image_new_from_icon_name</link></methodname>
    <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-pixmap">gtk.image_new_from_pixmap</link></methodname>
    <methodparam><parameter role="keyword">pixmap</parameter></methodparam>
    <methodparam><parameter role="keyword">mask</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-image">gtk.image_new_from_image</link></methodname>
    <methodparam><parameter role="keyword">image</parameter></methodparam>
    <methodparam><parameter role="keyword">mask</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-file">gtk.image_new_from_file</link></methodname>
    <methodparam><parameter role="keyword">filename</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-pixbuf">gtk.image_new_from_pixbuf</link></methodname>
    <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--image-new-from-gicon">gtk.image_new_from_gicon</link></methodname>
    <methodparam><parameter role="keyword">gicon</parameter></methodparam>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
  </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkmisc">gtk.Misc</link>
        +-- <link linkend="class-gtkimage">gtk.Image</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkimage"><classname>gtk.Image</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>

  <refsect1 id="properties-gtkimage">
    <title>gtk.Image Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkmisc">gtk.Misc Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"file"</entry>
	      <entry>Write</entry>

	      <entry>A filename containing the image data. Default value:
<literal>None</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"gicon"</entry>
	      <entry>Read-Write</entry>

	      <entry>The GIcon displayed in the GtkImage. For themed icons,
	      If the icon theme is changed, the image will be updated automatically.
	      Available in GTK 2.14 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"icon-name"</entry>
	      <entry>Read-Write</entry>

	      <entry>The name of the icon in the icon theme. If the icon
theme is changed, the image will be updated automatically. Default value:
<literal>None</literal>. Available in GTK 2.6 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"icon-set"</entry>
	      <entry>Read-Write</entry>
	      <entry>the <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> to
display</entry>
	    </row>

	    <row valign="top">
	      <entry>"icon-size"</entry>
	      <entry>Read-Write</entry>

	      <entry>the size to use for a stock icon, named icon or icon
set. Allowed values: >= 0. Default value: 4</entry>
	    </row>

	    <row valign="top">
	      <entry>"image"</entry>
	      <entry>Read-Write</entry>
	      <entry>a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> to
display</entry>
	    </row>

	    <row valign="top">
	      <entry>"mask"</entry>
	      <entry>Read-Write</entry>
	      <entry>a bitmap <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> to
use with a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> or a
<link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link></entry>
	    </row>

	    <row valign="top">
	      <entry>"pixbuf"</entry>
	      <entry>Read-Write</entry>
	      <entry>the <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> 
to display</entry>
	    </row>

	    <row valign="top">
	      <entry>"pixbuf-animation"</entry>
	      <entry>Read-Write</entry>
	      <entry>the <link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link> 
to display</entry>
	    </row>

	    <row valign="top">
	      <entry>"pixel-size"</entry>
	      <entry>Read-Write</entry>

	      <entry>a fixed size overriding the "icon-size" property for
images of type <literal>gtk.IMAGE_ICON_NAME</literal>. Allowed values: >=
-1. Default value: -1. Available in GTK+ 2.6 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"pixmap"</entry>
	      <entry>Read-Write</entry>
	      <entry>a <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> to
display</entry>
	    </row>

	    <row valign="top">
	      <entry>"stock"</entry>
	      <entry>Read-Write</entry>
	      <entry>the stock ID for a stock image to display. Default
value: <literal>None</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"storage-type"</entry>
	      <entry>Read</entry>

	      <entry>the type of the image data; one of the <xref
linkend="gtk-image-type-constants"
endterm="gtk-image-type-constants-title"></xref>:
<literal>gtk.IMAGE_EMPTY</literal>, <literal>gtk.IMAGE_PIXMAP</literal>,
<literal>gtk.IMAGE_IMAGE</literal>, <literal>gtk.IMAGE_PIXBUF</literal>,
<literal>gtk.IMAGE_STOCK</literal>, <literal>gtk.IMAGE_ICON_SET</literal> or
<literal>gtk.IMAGE_ANIMATION</literal></entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkimage">
    <title>gtk.Image Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkimage">
    <title>gtk.Image Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> widget
displays an image. Various kinds of objects can be displayed as an image;
usually, you would load a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
("pixel buffer") from a file, and then display it. The convenience method
<link
linkend="method-gtkimage--set-from-file"><methodname>set_from_file</methodname>()</link> 
will read the file and automatically create a pixbuf that is added to the
<link linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget. If the file isn't loaded successfully, the image will contain a
"broken image" icon similar to that used in many web browsers. If you want
to handle errors in loading the file yourself, for example by displaying an
error message, then load the image with <link
linkend="function-gdk--pixbuf-new-from-file"><methodname>gtk.gdk.pixbuf_new_from_file</methodname>()</link>, 
then add it to the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> with the
<link
linkend="method-gtkimage--set-from-pixbuf"><methodname>set_from_pixbuf</methodname>()</link> 
method. The image file may contain an animation; if so, the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> will
display an animation (<link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link>) 
instead of a static image.</para>

    <para><link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> is a
subclass of <link
linkend="class-gtkmisc"><classname>gtk.Misc</classname></link>, which
implies that you can align it (center, left, right) and add padding to it,
using the <link
linkend="class-gtkmisc"><classname>gtk.Misc</classname></link> methods.
<link linkend="class-gtkimage"><classname>gtk.Image</classname></link> is a
"no window" widget (has no <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> of
its own), so by default does not receive events. If you want to receive
events on the image, such as button clicks, place the image inside a <link
linkend="class-gtkeventbox"><classname>gtk.EventBox</classname></link>, then
connect to the event signals on the event box.</para>

    <para>When handling events on the event box, keep in mind that
coordinates in the image may be different from event box coordinates due to
the alignment and padding settings on the image (see <link
linkend="class-gtkmisc"><classname>gtk.Misc</classname></link>). The
simplest way to solve this is to set the alignment to 0.0 (left/top), and
set the padding to zero. Then the origin of the image will be the same as
the origin of the event box.</para>

    <para>Sometimes an application will want to avoid depending on external
data files, such as image files. GTK+ comes with a program to avoid this,
called <command>gdk-pixbuf-csource</command>. This program allows you to
convert an image into a C variable declaration, which can then be loaded
into a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> using
the <link
linkend="function-gdk--pixbuf-new-from-inline"><function>gtk.gdk.pixbuf_new_from_inline</function>()</link>
function. This can also be used in <literal>PyGTK</literal> by modifying the
output using an editor or the <command>sed</command> command as
follows:</para>

    <programlisting>
  gdk-pixbuf-csource imagefile | \
          sed -n -e 's/{/[/' -e 's/};/]/' -e '/".*"/p' >outfile
</programlisting>

    <para>You can edit <filename>outfile</filename> into a Python file where
it will be evaluated to a list containing a string. The string can be used
directly with the <link
linkend="function-gdk--pixbuf-new-from-inline"><function>gtk.gdk.pixbuf_new_from_inline</function>()</link>
function to create a pixbuf that can be used in a <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Image</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a newly created <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new empty <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkimage--set-from-pixmap">
      <title>gtk.Image.set_from_pixmap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_pixmap</methodname>
	  <methodparam><parameter
			 role="keyword">pixmap</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">mask</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixmap</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">mask</parameter>&nbsp;:</term>
	  <listitem><simpara>a bitmap <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_pixmap</methodname>() method sets the
image data from <parameter>pixmap</parameter> using
<parameter>mask</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-image">
      <title>gtk.Image.set_from_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_image</methodname>
	  <methodparam><parameter
			 role="keyword">gdk_image</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">mask</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">gdk_image</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">mask</parameter>&nbsp;:</term>
	  <listitem><simpara>a bitmap <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_image</methodname>() method sets the
image data from <parameter>image</parameter> using
<parameter>mask</parameter>. A <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> is a
client-side image buffer in the pixel format of the current display. If
<parameter>image</parameter> is <literal>None</literal> the current image
data will be removed.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-file">
      <title>gtk.Image.set_from_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_file</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>a filename or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_file</methodname>() method sets the
image data from the contents of the file named
<parameter>filename</parameter>. If the file isn't found or can't be loaded,
the resulting <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> will
display a "broken image" icon. This function never returns None, it always
returns a valid <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> widget. If
the file contains an animation, the image will contain an animation. If
<parameter>filename</parameter> is <literal>None</literal> the current image
data will be removed.</para>

      <para>If you need to detect failures to load the file, use <link
linkend="function-gdk--pixbuf-new-from-file"><methodname>gtk.gdk.pixbuf_new_from_file</methodname>()</link> 
to load the file yourself, then create the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> from the
pixbuf. (Or for animations, use the <link
linkend="constructor-gdkpixbufanimation">gtk.gdk.PixbufAnimation</link>()
constructor.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-pixbuf">
      <title>gtk.Image.set_from_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_pixbuf</methodname>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_pixbuf</methodname>() method sets the
image data using <parameter>pixbuf</parameter>. Note that this function just
creates an <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> from
<parameter>pixbuf</parameter>. The <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> created
will not react to state changes. Should you want that, you should use the
<link
linkend="method-gtkimage--set-from-icon-set"><methodname>set_from_icon_set</methodname>()</link> 
method If <parameter>pixbuf</parameter> is <literal>None</literal> the
current image data will be removed.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-stock">
      <title>gtk.Image.set_from_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_stock</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon size</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_stock</methodname>() method sets the
image data from the stock item identified by
<parameter>stock_id</parameter>. Sample stock icon names are
<literal>gtk.STOCK_OPEN</literal> and <literal>gtk.STOCK_OK</literal>.
Stock icon sizes are <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> and
<literal>gtk.ICON_SIZE_DIALOG</literal>. If the stock icon name isn't known,
a "broken image" icon will be displayed instead. You can register your own
stock icon names, see the <link
linkend="method-gtkiconfactory--add-default"><methodname>gtk.IconFactory.add_default</methodname>()</link> 
and <link
linkend="method-gtkiconfactory--add"><methodname>gtk.IconFactory.add</methodname>()</link> 
methods.</para>

      <para>The stock icons are described in the <link
linkend="gtk-stock-items">Stock Items</link> reference.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-icon-set">
      <title>gtk.Image.set_from_icon_set</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_icon_set</methodname>
	  <methodparam><parameter
			 role="keyword">icon_set</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_set</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon size</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_icon_set</methodname>() method sets the
image data from icon_set with the size specified by
<parameter>size</parameter>. Stock icon sizes are
<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> and
<literal>gtk.ICON_SIZE_DIALOG</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-animation">
      <title>gtk.Image.set_from_animation</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_from_animation</methodname>
	  <methodparam><parameter
			 role="keyword">animation</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">animation</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_from_animation</methodname>() method sets
the image data from <parameter>animation</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-storage-type">
      <title>gtk.Image.get_storage_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_storage_type</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the type of the image representation being
used</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_storage_type</methodname>() method gets the
type of representation being used by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> to store
image data. If the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> has no
image data, the return value will be <literal>gtk.IMAGE_EMPTY</literal>. The
image type is one of: <literal>gtk.IMAGE_EMPTY</literal>,
<literal>gtk.IMAGE_PIXMAP</literal>, <literal>gtk.IMAGE_IMAGE</literal>,
<literal>gtk.IMAGE_PIXBUF</literal>, <literal>gtk.IMAGE_STOCK</literal>,
<literal>gtk.IMAGE_ICON_SET</literal> or
<literal>gtk.IMAGE_ANIMATION</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-pixmap">
      <title>gtk.Image.get_pixmap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_pixmap</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the pixmap (or
<literal>None</literal>) and the mask (or
<literal>None</literal>)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_pixmap</methodname>() method returns a tuple
containing the pixmap and mask being displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. Either or
both the pixmap and mask may be <literal>None</literal>. If the storage type
of the image is not either <literal>gtk.IMAGE_EMPTY</literal> or
<literal>gtk.IMAGE_PIXMAP</literal> the ValueError exception will be
raised.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-image">
      <title>gtk.Image.get_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_image</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> and a
mask bitmap</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_image</methodname>() method returns a tuple
containing the <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> and
mask being displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. One or
both of the <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> and
mask may be <literal>None</literal>. If the storage type of the image is not
either of <literal>gtk.IMAGE_EMPTY</literal> or
<literal>gtk.IMAGE_IMAGE</literal> the ValueError exception will be
raised.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-pixbuf">
      <title>gtk.Image.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 displayed pixbuf, or
<literal>None</literal> if the image is empty</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_pixbuf</methodname>() method gets the <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> being
displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. The return
value may be None if no image data is set. If the storage type of the image
is not either <literal>gtk.IMAGE_EMPTY</literal> or
<literal>gtk.IMAGE_PIXBUF</literal> the ValueError exception will be
raised.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-stock">
      <title>gtk.Image.get_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_stock</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the stock icon name and the
stock icon size of the image data</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_stock</methodname>() method returns a tuple
containing the stock icon identifier (may be <literal>None</literal>) and
size being displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. The size
will be one of: <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> or
<literal>gtk.ICON_SIZE_DIALOG</literal>. If the storage type of the image is
not either <literal>gtk.IMAGE_EMPTY</literal> or
<literal>gtk.IMAGE_STOCK</literal> the ValueError exception will be
raised.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-icon-set">
      <title>gtk.Image.get_icon_set</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_set</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> and a
stock icon size</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_icon_set</methodname>() method returns a
tuple containing the icon set (may be <literal>None</literal>) and size
being displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. The size
will be one of: <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> or
<literal>gtk.ICON_SIZE_DIALOG</literal>. If the storage type of the image is
not either <literal>gtk.IMAGE_EMPTY</literal> or
<literal>gtk.IMAGE_ICON_SET</literal> the ValueError exception will be
raised.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-animation">
      <title>gtk.Image.get_animation</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_animation</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the displayed animation, or
<literal>None</literal> if the image is empty</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_animation</methodname>() method gets the
<link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link> 
(may be None if there is no image data) being displayed by the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>. If the
storage type of the image is not either <literal>gtk.IMAGE_EMPTY</literal>
or <literal>gtk.IMAGE_ANIMATION</literal> the ValueError exception will be
raised.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_name</methodname>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the name and size of the
displayed icon.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_icon_name</methodname>() method returns a
2-tuple containing the values of the "icon-name" and "icon-size" properties
respectively if the "icon-name" property is not <literal>None</literal>. If
the "icon-name" property is <literal>None</literal> the 2-tuple returned
will be:</para>

      <programlisting>
  (None, &lt;enum GTK_ICON_SIZE_INVALID of type GtkIconSize&gt;)
</programlisting>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-icon-name">
      <title>gtk.Image.set_from_icon_name</title>

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

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

      <para>The <methodname>set_from_icon_name</methodname>() method sets
the "icon-name" and "icon-size" properties to the values of
<parameter>icon_name</parameter> and <parameter>size</parameter>
respectively. <parameter>icon_name</parameter> should be the name of an icon
in the current icon theme. If <parameter>icon_name</parameter> isn't known,
a "broken image" icon will be displayed instead. If the current icon theme
is changed, the icon will be updated appropriately.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-pixel-size">
      <title>gtk.Image.set_pixel_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_pixel_size</methodname>
          <methodparam><parameter
                         role="keyword">pixel_size</parameter></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">pixel_size</parameter>&nbsp;:</term>
	  <listitem><simpara>the new pixel size to be used for named
icons</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_pixel_size</methodname>() method sets the
"pixel-size" property to the value specified by
<parameter>pixel_size</parameter>. If the pixel size is set to a value != -1
the "pixel-size" property is used instead of the icon size set by the <link
linkend="method-gtkimage--set-from-icon-name"><methodname>set_from_icon_name</methodname>()</link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--get-pixel-size">
      <title>gtk.Image.get_pixel_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_pixel_size</methodname>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the pixel size used for named
icons.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_pixel_size</methodname>() method returns the
value of the "pixel-size" property which specifies the pixel size to be used
for named icons.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--clear">
      <title>gtk.Image.clear</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>clear</methodname>
        </methodsynopsis></programlisting>

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

      <para>The <methodname>clear</methodname>() method removes the current
image, if any, and resets the "storage-type", "mask" and "icon-size"
properties. One of the "file", "icon-name", "icon-set", "image", "pixbuf",
"pixbuf-animation", "pixmap" or "stock" will be reset if there was an
existing image.</para>

    </refsect2>

    <refsect2 id="method-gtkimage--set-from-gicon">
      <title>gtk.Image.set_from_gicon</title>

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

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

      <para>
	For the <methodname>set_from_gicon</methodname>() method see
	<methodname><link linkend="function-gtk--image-new-from-gicon">gtk.image_new_from_gicon</link></methodname>()
	for details.
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--image-new-from-stock">
      <title>gtk.image_new_from_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_stock</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer representing an icon
size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkimage"><classname>gtk.Image</classname></link>
	  displaying the stock icon</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.image_new_from_stock</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> displaying
the stock icon specified by <parameter>stock_id</parameter> with the
specified <parameter>size</parameter>. Sample stock icon names are
<literal>gtk.STOCK_OPEN</literal>, <literal>gtk.STOCK_OK</literal> - see the
<link
linkend="method-gtkimage--set-from-stock"><methodname>set_from_stock</methodname>()</link> 
method for detailed information on the <literal>PyGTK</literal> stock icons.
. Sample stock sizes are <literal>gtk.ICON_SIZE_MENU</literal>,
<literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal> - see the <link linkend="function-gtk--icon-size-lookup"><function>gtk.icon_size_lookup</function>()</link> function for more detail. If the stock icon name isn't
known, a "broken image" icon will be displayed instead. You can register
your own stock icon names, see the <link
linkend="method-gtkiconfactory--add-default"><methodname>gtk.IconFactory.add_default</methodname>()</link> 
and <link
linkend="method-gtkiconfactory--add"><methodname>gtk.IconFactory.add</methodname>()</link> 
methods.</para>

    </refsect2>

    <refsect2 id="function-gtk--image-new-from-icon-set">
      <title>gtk.image_new_from_icon_set</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_icon_set</methodname>
	  <methodparam><parameter
			 role="keyword">icon_set</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_set</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer representing an icon
size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.image_new_from_icon_set</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> created
from the <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>
specified by <parameter>icon_set</parameter> with the specified
<parameter>size</parameter>. Sample stock sizes are
<literal>gtk.ICON_SIZE_MENU</literal>,
<literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal> - see the <link
linkend="function-gtk--icon-size-lookup"><function>gtk.icon_size_lookup</function>()</link> 
function for more detail. Instead of using this function, usually it's
better to create a <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>, 
put your icon sets in the icon factory, add the icon factory to the list of
default factories with the <link
linkend="method-gtkiconfactory--add-default"><methodname>add_default</methodname>()</link> 
method, and then use the <link
linkend="function-gtk--image-new-from-stock"><function>gtk.image_new_from_stock</function>()</link> 
function. This will allow themes to override the icon you ship with your
application.</para>

    </refsect2>

    <refsect2 id="function-gtk--image-new-from-animation">
      <title>gtk.image_new_from_animation</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_animation</methodname>
	  <methodparam><parameter
			 role="keyword">animation</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">animation</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link> 
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <function>gtk.image_new_from_animation</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
containing the <link
linkend="class-gdkpixbufanimation"><classname>gtk.gdk.PixbufAnimation</classname></link> 
specified by <parameter>animation</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--image-new-from-icon_name">
      <title>gtk.image_new_from_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_icon_name</methodname>
	  <methodparam><parameter
			 role="keyword">icon_name</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>an icon name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon size</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_icon_name</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
displaying the named theme icon specified by
<parameter>icon_name</parameter> with the icon size specified by
<parameter>size</parameter>. If the icon name isn't known, a "broken image"
icon will be displayed instead. If the current icon theme is changed, the
icon will be updated appropriately. The "icon-name" and "icon-size"
properties are also set by this function.</para>

    </refsect2>
    
    <refsect2 id="function-gtk--image-new-from-pixmap">
      <title>gtk.image_new_from_pixmap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_pixmap</methodname>
	  <methodparam><parameter
			 role="keyword">pixmap</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">mask</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixmap</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">mask</parameter>&nbsp;:</term>
	  <listitem><simpara>the bitmap that is the transparency mask.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_pixmap</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
displaying pixmap with a mask. A <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> 
is a server-side image buffer in the pixel format of the current display.</para>

    </refsect2>
    
    <refsect2 id="function-gtk--image-new-from-image">
      <title>gtk.image_new_from_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_image</methodname>
	  <methodparam><parameter
			 role="keyword">image</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">mask</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">image</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">mask</parameter>&nbsp;:</term>
	  <listitem><simpara>the bitmap that is the transparency mask.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_image</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
displaying an image with a mask. A <link
linkend="class-gdkimage"><classname>gtk.gdk.Image</classname></link> 
is a client-side image buffer in the pixel format of the current display.</para>

    </refsect2>
    
    <refsect2 id="function-gtk--image-new-from-file">
      <title>gtk.image_new_from_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_file</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>a filename</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_file</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
displaying the file filename. If the file isn't found or can't be loaded, 
the resulting <link linkend="class-gtkimage"><classname>gtk.Image</classname></link> 
will display a "broken image" icon. This function never returns None, 
it always returns a valid <link linkend="class-gtkimage"><classname>gtk.Image</classname>
</link> widget.</para>
      <para>If the file contains an animation, the image will contain an animation.</para>
      <para>If you need to detect failures to load the file, use <link
linkend="function-gdk--pixbuf-new-from-file">gtk.gdk.pixbuf_new_from_file</link> 
to load the file yourself, then create the <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> 
from the pixbuf. (Or for animations, use <link
linkend="constructor-gdkpixbufanimation">gtk.gdk.PixbufAnimation</link>.
The storage type (<link
linkend="method-gtkimage--get-storage-type">get_storage_type</link>) 
of the returned image is not defined, it will be whatever is appropriate 
for displaying the file.</para>

    </refsect2><refsect2 id="function-gtk--image-new-from-pixbuf">
      <title>gtk.image_new_from_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_pixbuf</methodname>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></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-gtkimage"><classname>gtk.Image</classname></link>
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_pixbuf</function>() function
returns a new <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> object
displaying pixbuf</para>
      <para>Note that this function just creates a <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> from the pixbuf. The 
<link linkend="class-gtkimage"><classname>gtk.Image</classname></link> 
created will not react to state changes. Should you want that, you should use 
<link linkend="function-gtk--image-new-from-icon-set">gtk.image_new_from_icon_set</link>
      </para>
     </refsect2>
    
    <refsect2 id="function-gtk--image-new-from-gicon">
      <title>gtk.image_new_from_gicon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.image_new_from_gicon</methodname>
	  <methodparam><parameter role="keyword">gicon</parameter></methodparam>
	  <methodparam><parameter role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">gicon</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link linkend="class-gioicon"><classname>gio.Icon</classname></link>
	  </simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon size.
	  </simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link linkend="class-gtkimage"><classname>gtk.Image</classname></link>
	  displaying the themed icon.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.image_new_from_pixbuf</function>() function returns
      a new <link linkend="class-gtkimage"><classname>gtk.Image</classname></link>
      displaying an icon from the current icon theme. If the icon name isn't known,
      a "broken image" icon will be displayed instead. If the current icon theme is
      changed, the icon will be updated appropriately.
      </para>
     </refsect2>
 

  </refsect1>

</refentry>