path: root/docs/reference/pygtk-gtktooltips.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-gtktooltips">
  <refnamediv>
    <refname>gtk.Tooltips</refname>
    <refpurpose>add tips to your widgets.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Tooltips</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkobject">gtk.Object</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtktooltips">gtk.Tooltips</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktooltips--enable">enable</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktooltips--disable">disable</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktooltips--set-tip">set_tip</link></methodname>
	<methodparam><parameter
		       role="keyword">widget</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">tip_text</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">tip_private</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtktooltips--force-window">force_window</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
	<methodname><link
linkend="function-gtk--tooltips-data-get">gtk.tooltips_data_get</link></methodname>
	<methodparam><parameter
		       role="keyword">widget</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-gtktooltips">gtk.Tooltips</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtktooltips">
    <title>gtk.Tooltips Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

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

	    <row valign="top">
	      <entry>"tip_window"</entry>
	      <entry>Read</entry>
	      <entry>The window that the tooltip is displayed in.</entry>
	    </row>

	    <row valign="top">
	      <entry>"tip_label"</entry>
	      <entry>Read</entry>
	      <entry>The label that displays the tooltip text.</entry>
	    </row>

	    <row valign="top">
	      <entry>"active_tips_data"</entry>
	      <entry>Read</entry>
	      <entry>The data associated with the active tooltip.</entry>
	    </row>

	    <row valign="top">
	      <entry>"tips_data_list"</entry>
	      <entry>Read</entry>
	      <entry>A list containing the data associated with the tooltips in a tooltips group. For each tooltip the data is a tuple containing:
the tooltip object, the associated widget, the tooltip text and the tooltip
private text.</entry>
	    </row>

	    <row valign="top">
	      <entry>"delay"</entry>
	      <entry>Read</entry>
	      <entry>The delay between the mouse pausing over the widget and
the display of the tooltip in msec.</entry>
	    </row>

	    <row valign="top">
	      <entry>"enabled"</entry>
	      <entry>Read</entry>
	      <entry>If <literal>True</literal> the tooltips are
enabled</entry>
	    </row>

	    <row valign="top">
	      <entry>"use_sticky_delay"</entry>
	      <entry>Read</entry>
	      <entry>If <literal>True</literal> shorten the delay for
showing a tooltip on another widget is already showing a tooltip.</entry>
	    </row>

	    <row valign="top">
	      <entry>"timer_tag"</entry>
	      <entry>Read</entry>
	      <entry>The tag of the timeout handler used for the
delay.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtktooltips">
    <title>gtk.Tooltips 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>
  </refsect1>

  <refsect1>
    <title>Description</title>
      
    <warning>
      <para>This method is deprecated in PyGTK 2.12 and above</para>
    </warning>

    <para>Tooltips are the messages that appear next to a widget when the
mouse pointer is held over it for a short amount of time. They are
especially helpful for adding more verbose descriptions of things such as
buttons in a toolbar. An individual tooltip belongs to a group of tooltips.
A group is created with a call to the <link
linkend="constructor-gtktooltips">gtk.Tooltips</link>() constructor. Every
tooltip in the group can then be turned off with a call to the <link
linkend="method-gtktooltips--disable"><methodname>disable</methodname>()</link> 
method and enabled with the <link
linkend="method-gtktooltips--enable"><methodname>enable</methodname>()</link> 
method. To assign a tip to a particular <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>, use the
<link
linkend="method-gtktooltips--set-tip"><methodname>set_tip</methodname>()</link> 
method.</para>

    <note>
      <para>Tooltips can only be set on widgets which have their own X
window. To check if a widget has its own window use
<literal>widget.flags()&amp;gtk.NO_WINDOW</literal>. To add a tooltip to a
widget that doesn't have its own window, place the widget inside a <link
linkend="class-gtkeventbox"><classname>gtk.EventBox</classname></link> and
add a tooltip to the eventbox instead.</para>
    </note>

    <para>The default appearance of all tooltips in a program is determined
by the current theme that the user has selected. Information about the
tooltip (if any) associated with an arbitrary widget can be retrieved using
the <link
linkend="function-gtk--tooltips-data-get"><function>gtk.tooltips_data_get</function>()</link> 
function.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Tooltips</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtktooltips"><classname>gtk.Tooltips</classname></link>
object</simpara></listitem>
      </varlistentry>
    </variablelist>
      
    <warning>
      <para>This method is deprecated in PyGTK 2.12 and above</para>
    </warning>

    <para>Creates an empty <link
linkend="class-gtktooltips"><classname>gtk.Tooltips</classname></link>
group.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtktooltips--enable">
      <title>gtk.Tooltips.enable</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>enable</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      
      <warning>
	<para>This method is deprecated in PyGTK 2.12 and above</para>
      </warning>

      <para>The <methodname>enable</methodname>() method enables a group of
tooltips. A tooltip will be displayed over its associated widget when
the mouse pointer pauses over the widget.</para>

    </refsect2>

    <refsect2 id="method-gtktooltips--disable">
      <title>gtk.Tooltips.disable</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disable</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      
      <warning>
	<para>This method is deprecated in PyGTK 2.12 and above</para>
      </warning>

      <para>The <methodname>disable</methodname>() method disables a group
of tooltips. A tooltip will not be displayed over its associated widget when
the mouse pointer pauses over the widget.</para>

    </refsect2>

    <refsect2 id="method-gtktooltips--set-tip">
    <title>gtk.Tooltips.set_tip</title>

<programlisting><methodsynopsis language="python">
    <methodname>set_tip</methodname>
    <methodparam><parameter role="keyword">widget</parameter></methodparam>
    <methodparam><parameter role="keyword">tip_text</parameter></methodparam>
    <methodparam><parameter role="keyword">tip_private</parameter><initializer>None</initializer></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>
    <varlistentry>
      <term><parameter role="keyword">tip_text</parameter>&nbsp;:</term>
      <listitem><simpara>the tooltip text</simpara></listitem>
    </varlistentry>
    <varlistentry>
      <term><parameter role="keyword">tip_private</parameter>&nbsp;:</term>
      <listitem><simpara>the tooltip private text for context sensitive display</simpara></listitem>
    </varlistentry>
  </variablelist>
      
    <warning>
      <para>This method is deprecated in PyGTK 2.12 and above</para>
    </warning>

      <para>The <methodname>set_tips</methodname>() method creates a tooltip
for the specified <parameter>widget</parameter>. The text specified by
<parameter>tooltip_text</parameter> will be displayed when the mouse pointer
pauses over <parameter>widget</parameter> if the tooltips are
enabled..</para>

    </refsect2>

    <refsect2 id="method-gtktooltips--force-window">
      <title>gtk.Tooltips.force_window</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>force_window</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      
      <warning>
	<para>This method is deprecated in PyGTK 2.12 and above</para>
      </warning>

      <para>The <methodname>force_window</methodname>() method ensures that
the window used for displaying the given tooltips is created. Applications
should never have to call this function, since PyGTK takes care of
this.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--tooltips-data-get">
      <title>gtk.tooltips_data_get</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.tooltips_data_get</methodname>
	  <methodparam><parameter
			 role="keyword">widget</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
	  <listitem><simpara>a widget</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the tooltip data associated
with <parameter>widget</parameter> or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>
      
    <warning>
      <para>This method is deprecated in PyGTK 2.12 and above</para>
    </warning>

      <para>The <function>gtk.tooltips_data_get</function>() function
returns a tuple containing the tooltip data associated with
<parameter>widget</parameter>. The tuple contains:</para>

      <itemizedlist>
	<listitem>
	  <simpara>the <link
linkend="class-gtktooltips"><classname>gtk.Tooltips</classname></link> group
containing the tooltip</simpara>
	</listitem>
	<listitem>
	  <simpara>the widget</simpara>
	</listitem>
	<listitem>
	  <simpara>the tooltip text string</simpara>
	</listitem>
	<listitem>
	  <simpara>the tooltip private text string or
<literal>None</literal></simpara>
	</listitem>
      </itemizedlist>

      <para>If <parameter>widget</parameter> does not have an associated
tooltip this function returns <literal>None</literal>.</para>

    </refsect2>

  </refsect1>

</refentry>