path: root/docs/reference/pygtk-gtkstatusicon.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-gtkstatusicon">

  <refnamediv>
    <refname>gtk.StatusIcon</refname>
      <refpurpose>display an icon in the system tray (new in PyGTK
      2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.StatusIcon</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkstatusicon">gtk.StatusIcon</link></methodname>
        <methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-storage-type">get_storage_type</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-gicon">get_gicon</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-pixbuf">get_pixbuf</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-stock">get_stock</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-icon-name">get_icon_name</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-size">get_size</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-x11-window-id">get_x11_window_id</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-tooltip">set_tooltip</link></methodname>
        <methodparam><parameter role="keyword">tooltip_text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-visible">set_visible</link></methodname>
        <methodparam><parameter role="keyword">visible</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-visible">get_visible</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-blinking">set_blinking</link></methodname>
        <methodparam><parameter role="keyword">blinking</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-blinking">get_blinking</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--is-embedded">is_embedded</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-geometry">get_geometry</link></methodname>
        <methodparam><parameter role="keyword">screen</parameter></methodparam>
        <methodparam><parameter role="keyword">area</parameter></methodparam>
        <methodparam><parameter role="keyword">orientation</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--get-screen">get_screen</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-screen">set_screen</link></methodname>
        <methodparam><parameter role="keyword">screen</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-from-pixbuf">set_from_pixbuf</link></methodname>
        <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-from-file">set_from_file</link></methodname>
        <methodparam><parameter role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-from-stock">set_from_stock</link></methodname>
        <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-from-icon-name">set_from_icon_name</link></methodname>
        <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkstatusicon--set-from-gicon">set_from_gicon</link></methodname>
        <methodparam><parameter role="keyword">gicon</parameter></methodparam>
      </methodsynopsis>
</classsynopsis>

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

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-new-from-pixbuf">gtk.status_icon_new_from_pixbuf</link></methodname>
    <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-new-from-file">gtk.status_icon_new_from_file</link></methodname>
    <methodparam><parameter role="keyword">filename</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-new-from-gicon">gtk.status_icon_new_from_gicon</link></methodname>
    <methodparam><parameter role="keyword">filename</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-new-from-stock">gtk.status_icon_new_from_stock</link></methodname>
    <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-new-from-icon-name">gtk.status_icon_new_from_icon_name</link></methodname>
    <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--status-icon-position-menu">gtk.status_icon_position_menu</link></methodname>
    <methodparam><parameter>menu</parameter></methodparam>
    <methodparam><parameter>statusicon</parameter></methodparam>
  </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkstatusicon">gtk.StatusIcon</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkstatusicon">
    <title>gtk.StatusIcon Properties</title>

    <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="3.5in"/>
        <tbody>

        <row valign="top">
          <entry>"blinking"</entry>
          <entry>Read-Write</entry>
          <entry>if <literal>True</literal> the status icon is
          blinking. Default value: <literal>False</literal>.</entry>
        </row>
        
        <row valign="top">
          <entry>"embedded"</entry>
          <entry>Read-Write</entry>
          <entry><literal>True</literal> if the status icon is
          embedded in a notification area.
          Default value: <literal>False</literal>.
          This property is available in GTK+ 2.12 and above.</entry>
        </row>

        <row valign="top">
          <entry>"file"</entry>
          <entry>Write</entry>
          <entry>Filename to load and display. Default value:
          <literal>None</literal>.</entry>
        </row>

        <row valign="top">
          <entry>"gicon"</entry>
          <entry>Read-Write</entry>
          <entry>The GIcon displayed in the GtkStatusIcon. For themed icons,
          the image will be updated automatically if the theme changes.</entry>
          Available from GTK+ 2.14.
        </row>

        <row valign="top">
          <entry>"icon-name"</entry>
          <entry>Read-Write</entry>
          <entry>The name of the icon from the icon theme. Default value:
          <literal>None</literal>.</entry>
        </row>
        
        <row valign="top">
          <entry>"orientation"</entry>
          <entry>Read-Write</entry>
          <entry>The orientation of the tray in which the statusicon is embedded.
          Default value: gtk.ORIENTATION_HORIZONTAL.
          This property is available in GTK+ 2.12 and above.</entry>
        </row>

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

        <row valign="top">
          <entry>"size"</entry>
          <entry>Read</entry>
          <entry>The size of the icon. Default value: 0.</entry>
        </row>

        <row valign="top">
          <entry>"stock"</entry>
          <entry>Read-Write</entry>
          <entry>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 representation being used for image data. Default
          value: <literal>gtk.IMAGE_EMPTY</literal>.</entry>
        </row>

        <row valign="top">
          <entry>"visible"</entry>
          <entry>Read-Write</entry>
          <entry>If <literal>True</literal> the status icon is
          visible. Default value: <literal>True</literal>.</entry>
        </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkstatusicon">
    <title>gtk.StatusIcon Signal Prototypes</title>

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

      <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkstatusicon--activate">activate</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkstatusicon--popup-menu">popup-menu</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>button</parameter></methodparam>
            <methodparam><parameter>activate_time</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkstatusicon--size-changed">size-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>size</parameter></methodparam>
           <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The "system tray" or notification area is normally used for
    transient icons that indicate some special state. For example, a system
    tray icon might appear to tell the user that they have new mail, or have
    an incoming instant message, or something along those lines. The basic
    idea is that creating an icon in the notification area is less annoying
    than popping up a dialog.</para>

    <para>A <link
    linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>
    object can be used to display an icon in a "system tray".  The icon can
    have a tooltip, and the user can interact with it by activating it or
    popping up a context menu. Critical information should not solely be
    displayed in a <link
    linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>,
    since it may not be visible (e.g. when the user doesn't have a
    notification area on his panel).  This can be checked with the <link
    linkend="method-gtkstatusicon--is-embedded"><methodname>gtk.StatusIcon.is_embedded()</methodname></link>
    method.</para>

    <para>On X11, the implementation follows the freedesktop.org "System
    Tray" <ulink
    url="http://www.freedesktop.org/wiki/Standards/systemtray-spec">specification</ulink>.
    Implementations of the "tray" side of this specification can be found
    e.g. in the GNOME and KDE panel applications.</para>

    <para>Note that a <link
    linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>
    is <emphasis>not</emphasis> a widget, but just a <link
    linkend="class-gobject"><classname>gobject.GObject</classname></link>.
    Making it a widget would be impractical, since the system tray on Win32
    doesn't allow to embed arbitrary widgets.</para>

  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-gtkstatusicon">
      <title>gtk.StatusIcon</title>

      <programlisting><constructorsynopsis language="python">
        <methodname>gtk.StatusIcon</methodname>
        <methodparam></methodparam>
      </constructorsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
          linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This constructor is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Creates an empty status icon object.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkstatusicon--set-from-pixbuf">
      <title>gtk.StatusIcon.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>

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

      <para>Makes <parameter>status_icon</parameter> display
      <parameter>pixbuf</parameter>.  See the <link
      linkend="function-gtk--status-icon-new-from-pixbuf"><function>gtk.status_icon_new_from_pixbuf</function>()</link>
      function for details.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--set-from-file">
      <title>gtk.StatusIcon.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</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Makes <parameter>status_icon</parameter> display the file
      <parameter>filename</parameter>.  See the <link
      linkend="function-gtk--status-icon-new-from-file"><function>gtk.status_icon_new_from_file</function>()</link>
      function for details.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
        <methodname>set_from_stock</methodname>
        <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
          <listitem><simpara>a stock icon id</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Makes <parameter>status_icon</parameter> display the stock icon
      with the id <parameter>stock_id</parameter>.  See the <link
      linkend="function-gtk--status-icon-new-from-stock"><function>gtk.status_icon_new_from_stock</function>()</link>
      function for details.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
        <methodname>set_from_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</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Makes <parameter>status_icon</parameter> display the icon named
      <parameter>icon_name</parameter> from the current icon theme.  See the
      <link
      linkend="function-gtk--status-icon-new-from-icon-name"><function>gtk.status_icon_new_from_icon_name</function>()</link>
      function for details.</para>

    </refsect2>

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

      <programlisting><methodsynopsis language="python">
        <methodname>set_from_gicon</methodname>
        <methodparam><parameter role="keyword">gicon</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">gicon</parameter>&nbsp;:</term>
          <listitem><simpara>a gio.Icon()</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Makes <parameter>status_icon</parameter> display the <parameter>gio.Icon()</parameter>
      See <methodname><link linkend="function-gtk--status-icon-new-from-gicon">gtk.status_icon_new_from_gicon</link></methodname>()
      for details</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-storage-type">
      <title>gtk.StatusIcon.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 image representation being used - one of
          the <xref linkend="gtk-image-type-constants"
          endterm="gtk-image-type-constants-title"></xref>.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Gets the type of representation being used by the <link
      linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>
      to store image data. If the <link
      linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>
      has no image data, the return value will be
      <literal>gtk.IMAGE_EMPTY</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-gicon">
      <title>gtk.StatusIcon.get_gicon</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the displayed icon, or <literal>None</literal>
          if the image is empty.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>
        Retrieves the gio.Icon() being displayed by the
        <link linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>.
        The storage type of the status icon must be gtk.IMAGE_EMPTY or gtk.IMAGE_GICON.
        If this method fails, icon is left unchanged;
      </para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-x11-window-id">
      <title>gtk.StatusIcon.get_x11_window_id</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>An 32 bit unsigned integer identifier for the
          underlying X11 Window.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>
        This function is only useful on the X11/freedesktop.org platform. It
        returns a window ID for the widget in the underlying status icon
        implementation. This is useful for the Galago notification service,
        which can send a window ID in the protocol in order for the server
        to position notification windows pointing to a status icon reliably.
      </para>
      <para>
        This function is not intended for other use cases which are more likely
        to be met by one of the non-X11 specific methods,
        such as
        <methodname><link linkend="function-gtk--status-icon-position-menu">gtk.status_icon_position_menu</link></methodname>().
      </para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-pixbuf">
      <title>gtk.StatusIcon.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>

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

      <para>Gets the <link
      linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
      being displayed by the <link
      linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>.
      The storage type of the status icon must be
      <literal>gtk.IMAGE_EMPTY</literal> or
      <literal>gtk.IMAGE_PIXBUF</literal> (see the <link
      linkend="method-gtkstatusicon--get-storage-type"><methodname>gtk.StatusIcon.get_storage_type()</methodname></link>
      method).</para>

    </refsect2>

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

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

      <para>Gets the id of the stock icon being displayed by the <link
      linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>.
      The storage type of the status icon must be
      <literal>gtk.IMAGE_EMPTY</literal> or
      <literal>gtk.IMAGE_STOCK</literal> (see the <link
      linkend="method-gtkstatusicon--get-storage-type"><methodname>gtk.StatusIcon.get_storage_type()</methodname></link>
      method).</para>

    </refsect2>

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

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

      <para>Gets the name of the icon being displayed by the <link
      linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link>.
      The storage type of the status icon must be
      <literal>gtk.IMAGE_EMPTY</literal> or
      <literal>gtk.IMAGE_ICON_NAME</literal> (see the <link
      linkend="method-gtkstatusicon--get-storage-type"><methodname>gtk.StatusIcon.get_storage_type()</methodname></link>
      method).</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-size">
      <title>gtk.StatusIcon.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 size that is available for the
          image</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Gets the size in pixels that is available for the image.  Stock
      icons and named icons adapt their size automatically if the size of
      the notification area changes. For other storage types, the
      "size-changed" signal can be used to react to size changes.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--set-tooltip">
      <title>gtk.StatusIcon.set_tooltip</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_tooltip</methodname>
        <methodparam><parameter role="keyword">tooltip_text</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">tooltip_text</parameter>&nbsp;:</term>
          <listitem><simpara>the tooltip text, or
          <literal>None</literal></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Sets the tooltip of the status icon.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--set-visible">
      <title>gtk.StatusIcon.set_visible</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_visible</methodname>
        <methodparam><parameter role="keyword">visible</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">visible</parameter>&nbsp;:</term>
          <listitem><simpara>if <literal>True</literal> show the status
          icon, if <literal>False</literal> hide it</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Shows or hides a status icon.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-visible">
      <title>gtk.StatusIcon.get_visible</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the status icon is
          visible</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns <literal>True</literal> if the status icon is visible.
      Note that being visible does not guarantee that the user can actually
      see the icon, see also the <link
      linkend="method-gtkstatusicon--is-embedded"><methodname>gtk.StatusIcon.is_embedded()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--set-blinking">
      <title>gtk.StatusIcon.set_blinking</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_blinking</methodname>
        <methodparam><parameter role="keyword">blinking</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">blinking</parameter>&nbsp;:</term>
          <listitem><simpara>if <literal>True</literal> turn blinking on, if
          <literal>False</literal> turn it off</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Makes the status icon start or stop blinking.  Note that
      blinking user interface elements may be problematic for some users,
      and thus may be turned off, in which case this setting has no
      effect.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-blinking">
      <title>gtk.StatusIcon.get_blinking</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the icon is
          blinking</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns <literal>True</literal> if the icon is blinking, see the
      <link
      linkend="method-gtkstatusicon--set-blinking"><methodname>gtk.StatusIcon.set_blinking()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--is-embedded">
      <title>gtk.StatusIcon.is_embedded</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the status icon is
          embedded in a notification area.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns <literal>True</literal> if the status icon is embedded
      in a notification area.</para>

    </refsect2>

    <refsect2 id="method-gtkstatusicon--get-geometry">
      <title>gtk.StatusIcon.get_geometry</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 3-tuple (containing the screen, area occupied
          by the status icon and the panel orientation) or
          None.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns information in a 3-tuple about the location of the
      status icon on screen. The 3-tuple contains the <link
      linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>,
      the area occupied by the status icon as a <link
      linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
      and the orientation of the panel containing the statis icon - one of
      the <xref linkend="gtk-orientation-constants"
      endterm="gtk-orientation-constants-title"></xref>. This information
      can be used to e.g. position popups like notification bubbles.  See
      the <link
      linkend="function-gtk--status-icon-position-menu"><function>gtk.status_icon_position_menu</function>()</link>
      function for a more convenient alternative for positioning
      menus.</para>
      
      <para>Note that some platforms do not provide this information.</para>

    </refsect2>
    
    <refsect2 id="method-gtkstatusicon--get-screen">
      <title>gtk.StatusIcon.get_screen</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a <link linkend="class-gdkscreen">
          <classname>gtk.gdk.Screen</classname></link>.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the <link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
      associated with status_icon.</para>

    </refsect2>
    
    <refsect2 id="method-gtkstatusicon--set-screen">
      <title>gtk.StatusIcon.set_screen</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_screen</methodname>
        <methodparam><parameter role="keyword">screen</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
          <listitem><simpara>a <link linkend="class-gdkscreen">
          <classname>gtk.gdk.Screen</classname></link>.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Sets the <link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
      where status_icon is displayed; if the icon is already mapped, it will be unmapped,
      and then remapped on the new screen.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--status-icon-new-from-pixbuf">
      <title>gtk.status_icon_new_from_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_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></simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>Creates a status icon displaying <parameter>pixbuf</parameter>.
      The image will be scaled down to fit in the available space in the
      notification area, if necessary.</para>

    </refsect2>

    <refsect2 id="function-gtk--status-icon-new-from-file">
      <title>gtk.status_icon_new_from_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_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></simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>Creates a status icon displaying the image in the file specified
      by <parameter>filename</parameter>.  The image will be scaled down to
      fit in the available space in the notification area, if
      necessary.</para>

    </refsect2>

    <refsect2 id="function-gtk--status-icon-new-from-gicon">
      <title>gtk.status_icon_new_from_gicon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_new_from_gicon</methodname>
	  <methodparam><parameter
			 role="keyword">gicon</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">gicon</parameter>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>
        Creates a status icon displaying a gio.Icon(). If the icon is a
        themed icon, it will be updated when the theme changes.
      </para>

    </refsect2>

    <refsect2 id="function-gtk--status-icon-new-from-stock">
      <title>gtk.status_icon_new_from_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_new_from_stock</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a stock icon id</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>Creates a status icon displaying a stock icon. Sample stock icon
      names are <literal>gtk.STOCK_OPEN</literal>,
      <literal>gtk.STOCK_QUIT</literal>. 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--status-icon-new-from-icon-name">
      <title>gtk.status_icon_new_from_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_new_from_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</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>Creates a status icon displaying an icon from the current icon
      theme. If the current icon theme is changed, the icon will be updated
      appropriately.</para>

    </refsect2>

    <refsect2 id="function-gtk--status-icon-position-menu">
      <title>gtk.status_icon_position_menu</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.status_icon_position_menu</methodname>
	  <methodparam><parameter>menu</parameter></methodparam>
	  <methodparam><parameter>statusicon</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>menu</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
	  linkend="class-gtkmenu"><classname>gtk.Menu</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>statusicon</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
	  linkend="class-gtkstatusicon"><classname>gtk.StatusIcon</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 3-tuple containing the x and y coordinates
	  for the menu and a boolean indicating whether the menu should be
	  pushed in to be completely inside the screen instead of just
	  clamped to the size to the screen.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>Menu positioning function to use with the <link
      linkend="method-gtkmenu--popup"><methodname>popup</methodname>()</link>
      method to position <parameter>menu</parameter> aligned to
      <parameter>statusicon</parameter> .</para>

      <para>Eample use of this function is:</para>

      <programlisting>
  menu.popup(None, None, gtk.status_icon_position_menu, 
             event.button, event.time, statusicon)
      </programlisting>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkstatusicon--activate">
      <title>The "activate" gtk.StatusIcon Signal</title>

      <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>status_icon</parameter>&nbsp;:</term>
          <listitem><simpara>the object which received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This signal is available in GTK+ 2.10 and above.</para>
      </note>

      <para>Gets emitted when the user activates the status icon.  If and
      how status icons can be activated is platform-dependent.</para>

    </refsect2>

    <refsect2 id="signal-gtkstatusicon--popup-menu">
      <title>The "popup-menu" gtk.StatusIcon Signal</title>

      <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>button</parameter></methodparam>
            <methodparam><parameter>activate_time</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>status_icon</parameter>&nbsp;:</term>
          <listitem><simpara>the object which received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>button</parameter>&nbsp;:</term>
          <listitem><simpara>the button that was pressed, or 0 if the 
  signal is not emitted in response to a button press event</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>activate_time</parameter>&nbsp;:</term>
          <listitem><simpara>the timestamp of the event that
  triggered the signal emission</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This signal is available in GTK+ 2.10 and above.</para>
      </note>

      <para>Gets emitted when the user brings up the context menu of the
      status icon. Whether status icons can have context menus and how these
      are activated is platform-dependent.</para>
      
      <para>The <parameter>button</parameter> and
      <parameter>activate_timeout</parameter> parameters should be passed as
      the last two arguments to the <link
      linkend="method-gtkmenu--popup"><methodname>gtk.Menu.popup()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="signal-gtkstatusicon--size-changed">
      <title>The "size-changed" gtk.StatusIcon Signal</title>

      <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>status_icon</parameter></methodparam>
            <methodparam><parameter>size</parameter></methodparam>
            <methodparam><parameter>statusicon</parameter></methodparam>
            <methodparam><parameter>arg1</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>status_icon</parameter>&nbsp;:</term>
          <listitem><simpara>the object which received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>size</parameter>&nbsp;:</term>
          <listitem><simpara>the new size</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the icon was updated
          for the new size. Otherwise, GTK+ will scale the icon as
          necessary.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This signal is available in GTK+ 2.10 and above.</para>
      </note>

      <para>Gets emitted when the size available for the image changes,
      e.g. because the notification area got resized.</para>

    </refsect2>

</refsect1>

</refentry>