<?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-gtktooltip">
    <refnamediv>
        <refname>gtk.Tooltip</refname>
        <refpurpose>Add tips to your widgets (new in PyGTK 2.12)</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gtk.Tooltip</classname></ooclass>
        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
    
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtktooltip--set-custom">set_custom</link></methodname>
        <methodparam><parameter role="keyword">widget</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtktooltip--set-icon">set_icon</link></methodname>
        <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtktooltip--set-icon-from-stock">set_icon_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-gtktooltip--set-icon-from-stock">set_icon_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-gtktooltip--set-icon-from-gicon">set_icon_from_gicon</link></methodname>
      <methodparam><parameter role="keyword">gicon</parameter></methodparam>
      <methodparam><parameter role="keyword">size</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtktooltip--set-markup">set_markup</link></methodname>
        <methodparam><parameter role="keyword">markup</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtktooltip--set-text">set_text</link></methodname>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
    </methodsynopsis>

    </classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>
 
<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--tooltip-trigger-tooltip-query">gtk.tooltip_trigger_tooltip_query</link></methodname>
    <methodparam><parameter role="keyword">display</parameter></methodparam>
  </methodsynopsis></programlisting>

    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtktooltip">gtk.Tooltip</link>
</synopsis>

    </refsect1>

    <refsect1>
        <title>Description</title>
            <para>
                <link linkend="class-gtktooltip"><classname>gtk.Tooltip</classname></link>
                belongs to the new tooltips API that was introduced in GTK+ 2.12 and which
                deprecates the old <link linkend="class-gtktooltips"><classname>gtk.Tooltips</classname></link> API.
            </para>
            <para>
                Basic tooltips can be realized simply by using
                <methodname><link linkend="method-gtkwidget--set-tooltip-text">gtk.Widget.set_tooltip_text</link></methodname>() or
                <methodname><link linkend="method-gtkwidget--set-tooltip-markup">gtk.Widget.set_tooltip_markup</link></methodname>()
                without any explicit tooltip object.
            </para>
            <para>
                When you need a tooltip with a little more fancy contents, like adding an image,
                or you want the tooltip to have different contents per
                <link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link> row or cell,
                you will have to do a little more work:
            </para>
            <itemizedlist>
                <listitem>
                    <simpara>
                        Set the GtkWidget:has-tooltip property to <literal>True</literal>,
                        this will make GTK+ monitor the widget for motion and related events
                        which are needed to determine when and where to show a tooltip.
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        Connect to the <link linkend="signal-gtkwidget--query-tooltip">GtkWidget::query-tooltip</link>
                        signal. This signal will be emitted
                        when a tooltip is supposed to be shown. One of the arguments passed to the
                        signal handler is a
                        <link linkend="class-gtktooltip"><classname>gtk.Tooltip</classname></link>
                        object. This is the object that we are about
                        to display as a tooltip, and can be manipulated in your callback using functions
                        like <methodname><link linkend="method-gtktooltip--set-icon">set_icon</link></methodname>.
                        There are functions for setting the tooltip's markup,
                        setting an image from a stock icon, or even putting in a custom widget.
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        Return <literal>True</literal> from your query-tooltip handler. This causes the
                        tooltip to be show. If you return <literal>False</literal>, it will not be shown.
                    </simpara>
                </listitem>
            </itemizedlist>
            <para>
                In the probably rare case where you want to have even more control over the tooltip that
                is about to be shown, you can set your own
                <link linkend="class-gtkwindow"><classname>gtk.Window</classname></link> which will be used as tooltip window.
                This works as follows:
            </para>
            <itemizedlist>
                <listitem>
                    <simpara>
                        Set GtkWidget:has-tooltip and connect to
                        <link linkend="signal-gtkwidget--query-tooltip">GtkWidget::query-tooltip</link>
                        as before.
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        Use <methodname><link linkend="method-gtkwidget--set-tooltip-window">gtk.Widget.set_tooltip_window</link></methodname>()
                        to set a <link linkend="class-gtkwindow"><classname>gtk.Window</classname></link> created by you as tooltip window.
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        In the ::query-tooltip callback you can access your window using
                        <methodname><link linkend="method-gtkwidget--get-tooltip-window">gtk.Widget.get_tooltip_window</link></methodname>()
                        and manipulate as you wish. The semantics of the return value are exactly as before,
                        return <literal>True</literal> to show the window, <literal>False</literal> to not show it.
                    </simpara>
                </listitem>
            </itemizedlist>
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-gtktooltip--set-custom">
            <title>gtk.Tooltip.set_custom</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_custom</methodname>
                <methodparam><parameter>widget</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
                        <listitem><simpara>A
                        <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>set_custom</methodname>() method replaces the widget packed into
                the tooltip with custom_widget. By default a box with a
                <link linkend="class-gtkimage"><classname>gtk.Image</classname></link> and
                <link linkend="class-gtklabel"><classname>gtk.Label</classname></link> is
                embedded in the tooltip, which can be configured using
                <methodname><link linkend="method-gtktooltip--set-markup">set_markup</link></methodname> and
                <methodname><link linkend="method-gtktooltip--set-icon">set_icon</link></methodname>.
            </para>
        </refsect2>

        <refsect2 id="method-gtktooltip--set-icon">
            <title>gtk.Tooltip.set_icon</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_value</methodname>
                <methodparam><parameter>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.12 and above.</para>
            </note>

            <para>
                The <methodname>set_icon</methodname>() method sets the icon of the tooltip
                (which is in front of the text) to be pixbuf.
                If <parameter>pixbuf</parameter> is <literal>None</literal>, the image will be hidden.
            </para>
        </refsect2>

        <refsect2 id="method-gtktooltip--set-icon-from-icon-name">
            <title>gtk.Tooltip.set_icon_from_icon_name</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_icon_from_icon_name</methodname>
                <methodparam><parameter>icon_name</parameter></methodparam>
                <methodparam><parameter>size</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
                        <listitem><simpara>an icon name, or <literal>None</literal>.</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.14 and above.</para>
            </note>

            <para>
                The <methodname>set_icon_from_icon_name</methodname>() method sets the icon of the tooltip
                (which is in front of the text) to be the icon indicated by <parameter>icon_name</parameter>
                with the size indicated by <parameter>size</parameter>. If icon_name is <literal>None</literal>,
                the image will be hidden.
            </para>
        </refsect2>

        <refsect2 id="method-gtktooltip--set-icon-from-stock">
            <title>gtk.Tooltip.set_icon_from_stock</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_icon_from_stock</methodname>
                <methodparam><parameter>stock_id</parameter></methodparam>
                <methodparam><parameter>size</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
                        <listitem><simpara>A stock icon name, or <literal>None</literal>.</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.12 and above.</para>
            </note>

            <para>
                The <methodname>set_icon_from_stock</methodname>() method sets the icon of the tooltip
                (which is in front of the text) to be the stock item indicated by <parameter>stock_id</parameter>
                with the size indicated by <parameter>size</parameter>. If stock_id is <literal>None</literal>,
                the image will be hidden.
            </para>
        </refsect2>

        <refsect2 id="method-gtktooltip--set-icon-from-gicon">
          <title>gtk.Tooltip.set_icon_from_gicon</title>

          <programlisting><methodsynopsis language="python">
            <methodname>set_icon_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>the icon to set, or <literal>None</literal>..</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.22 and above.</para>
          </note>

          <para>The <methodname>set_icon_from_gicon</methodname>() method sets the icon of the
          tooltip (which is in front of the text) to be the icon indicated by <parameter>gicon</parameter>
          with the size indicated by <parameter>size</parameter>. If gicon is <literal>None</literal>,
          the image will be hidden.</para>

        </refsect2>

        <refsect2 id="method-gtktooltip--set-markup">
            <title>gtk.Tooltip.set_markup</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_markup</methodname>
                <methodparam><parameter>markup</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">markup</parameter>&nbsp;:</term>
                        <listitem><simpara>A markup string (see Pango markup format)
                        or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>set_markup</methodname>() method sets the text of the tooltip to be
                <parameter>markup</parameter>, which is marked up with the Pango text markup language.
                If <parameter>markup</parameter> is <literal>None</literal>, the label will be hidden.
            </para>
        </refsect2>

        <refsect2 id="method-gtktooltip--set-text">
            <title>gtk.Tooltip.set_text</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_text</methodname>
                <methodparam><parameter>text</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">text</parameter>&nbsp;:</term>
                        <listitem><simpara>A text string or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>set_text</methodname>() method sets the text of the tooltip to be text.
                If text is <literal>None</literal>, the label will be hidden. See also
                <methodname><link linkend="method-gtktooltip--set-markup">set_markup</link></methodname>.
            </para>
        </refsect2>
    </refsect1>
    
    <refsect1>
        <title>Functions</title>

        <refsect2 id="function-gtk--tooltip-trigger-tooltip-query">
            <title>gtk.tooltip_trigger_tooltip_query</title>

            <programlisting><methodsynopsis language="python">
                <methodname>tooltip_trigger_tooltip_query</methodname>
                <methodparam><parameter>display</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">display</parameter>&nbsp;:</term>
                        <listitem><simpara>A
                            <link linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>tooltip_trigger_tooltip_query</methodname>() function triggers a
                new tooltip query on display, in order to update the current visible tooltip,
                or to show/hide the current tooltip. This function is useful to call when, for example,
                the state of the widget changed by a key press.
            </para>
        </refsect2>
    </refsect1>
</refentry>
