path: root/docs/reference/pygtk-gtkiconinfo.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-gtkiconinfo">
  <refnamediv>
    <refname>gtk.IconInfo</refname> <refpurpose>object containing
    information about and icon in an icon theme (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.IconInfo</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--copy">copy</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--free">free</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-base-size">get_base_size</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-filename">get_filename</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-builtin-pixbuf">get_builtin_pixbuf</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--load-icon">load_icon</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--set-raw-coordinates">set_raw_coordinates</link></methodname>
	<methodparam><parameter role="keyword">raw_coordinates</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-embedded-rect">get_embedded_rect</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-attach-points">get_attach_points</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkiconinfo--get-display-name">get_display_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

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

    <para>A <link
linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>
object contains information about an icon in a <link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link>. A
<link linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link>
object is created using the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon</methodname>()</link>
method.</para>

    <para>A <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> can
be rendered with the icon using the <link
linkend="method-gtkiconinfo--load-icon"><methodname>load_icon</methodname>()</link>
method. If you just want to load the pixbuf of an icon you can use the <link
linkend="method-gtkicontheme--load-icon"><methodname>gtk.IconTheme.load_icon</methodname>()</link>
method that combines the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon</methodname>()</link>
method and the <link
linkend="method-gtkiconinfo--load-icon"><methodname>load_icon</methodname>()</link>
method.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkiconinfo--copy">
      <title>gtk.IconInfo.copy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the new <link
	  linkend="class-gtkiconinfo"><classname>gtk.IconInfo</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

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

    </refsect2>

    <refsect2 id="method-gtkiconinfo--free">
      <title>gtk.IconInfo.free</title>

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

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

      <warning>
        <para>This method is deprecated and should not be used since it can
 crash your application.</para>
      </warning>

      <para>The <methodname>free</methodname>() method frees the icon info
and its associated information</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-base-size">
      <title>gtk.IconInfo.get_base_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_base_size</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the base size, or 0, if no base
size is known for the icon.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_base_size</methodname>() method returns the
base size for the icon. The base size is a size for the icon that was
specified by the icon theme creator. This may be different than the actual
size of image; an example of this is small emblem icons that can be attached
to a larger icon. These icons will be given the same base size as the larger
icons to which they are attached.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-filename">
      <title>gtk.IconInfo.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 filename for the icon, or
	  <literal>None</literal> if the <link
	  linkend="method-gtkiconinfo--get-builtin-pixbuf"><methodname>get_builtin_pixbuf()</methodname></link>
	  should be used instead.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_filename</methodname>() method returns the filename for the icon. If
the <literal>gtk.ICON_LOOKUP_USE_BUILTIN</literal> flag was passed to the
<link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon()</methodname></link>
method, there may be no filename if a builtin icon is returned. In this
case, you should use the <link
linkend="method-gtkiconinfo--get-builtin-pixbuf"><methodname>get_builtin_pixbuf()</methodname></link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-builtin-pixbuf">
      <title>gtk.IconInfo.get_builtin_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_builtin_pixbuf</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the built-in image pixbuf, or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_builtin_pixbuf</methodname>() method returns
the built-in image for this icon, if any. To allow <literal>GTK+</literal>
to use built in icon images, you must pass the
<literal>gtk.ICON_LOOKUP_USE_BUILTIN</literal> to the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon()</methodname></link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--load-icon">
      <title>gtk.IconInfo.load_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>load_icon</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the icon rendered into a <link
	  linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.
	  This may be a newly created icon or a new reference to an internal
	  icon, so you must not modify the icon.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>load_icon</methodname>() method renders the icon
previously looked up in an icon theme using the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon()</methodname></link>
method. The icon size will be based on the size passed to the <link
linkend="method-gtkicontheme--lookup-icon"><methodname>gtk.IconTheme.lookup_icon()</methodname></link>
method. Note that the resulting <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> may
not be exactly this size. An icon theme may have icons that differ slightly
from their nominal sizes, and in addition <literal>GTK</literal>+ will avoid
scaling icons that it considers sufficiently close to the requested size to
maintain sharpness.</para>

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

    </refsect2>

    <refsect2 id="method-gtkiconinfo--set-raw-coordinates">
      <title>gtk.IconInfo.set_raw_coordinates</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_raw_coordinates</methodname>
	  <methodparam><parameter role="keyword">raw_coordinates</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">raw_coordinates</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal>, the coordinates of
	  embedded rectangles and attached points should be returned in
	  their original (unscaled) form.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_raw_coordinates</methodname>() method sets
the internal raw_coordinates flag to the value of
<parameter>raw_coordinates</parameter>. If
<parameter>raw_coordinates</parameter> is <literal>True</literal>, the
coordinates returned by the <link
linkend="method-gtkiconinfo--get-embedded-rect"><methodname>get_embedded_rect()</methodname></link>
and <link
linkend="method-gtkiconinfo--get-attach-points"><methodname>get_attach_points()</methodname></link>
methods will be returned in their original form as specified in the icon
theme, instead of scaled appropriately for the pixbuf returned by the <link
linkend="method-gtkiconinfo--load-icon"><methodname>load_icon()</methodname></link>
method.</para>

      <para>Raw coordinates are somewhat strange; they are specified to be
with respect to the unscaled pixmap for <literal>PNG</literal> and
<literal>XPM</literal> icons, but for <literal>SVG</literal> icons, they are
in a 1000x1000 coordinate space that is scaled to the final size of the
icon.  You can determine if the icon is an <literal>SVG</literal> icon by
using the <link
linkend="method-gtkiconinfo--get-filename"><methodname>get_filename()</methodname></link>
method, and seeing if it is not <literal>None</literal> and ends in '.svg'.</para>

      <para>This method is provided primarily to allow compatibility
wrappers for older API's, and is not expected to be useful for
applications.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-embedded-rect">
      <title>gtk.IconInfo.get_embedded_rect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_embedded_rect</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
	  or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_embedded_rect</methodname>() method returns
a <link
linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
containing the coordinates of a rectangle within the icon that can be used
for display of information such as a preview of the contents of a text file.
See the <link
linkend="method-gtkiconinfo--set-raw-coordinates"><methodname>set_raw_coordinates()</methodname></link>
method for further information about the coordinate system.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-attach-points">
      <title>gtk.IconInfo.get_attach_points</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_attach_points</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing a set of 2-tuples for the
	  attach points</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_attach_points</methodname>() method returns
a tuple containing the attach points for an icon as a set of 2-tuples. An
attach point is a location in the icon that can be used as anchor points for
attaching emblems or overlays to the icon.</para>

    </refsect2>

    <refsect2 id="method-gtkiconinfo--get-display-name">
      <title>gtk.IconInfo.get_display_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_display_name</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the display name for the icon or <literal>None</literal>, if
the icon doesn't have a specified display name.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_display_name</methodname>() method returns the display name for an icon. A display name is a
string to be used in place of the icon name in a user
visible context like a list of icons.</para>

    </refsect2>

  </refsect1>

</refentry>