<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="GtkTooltips">
<refmeta>
<refentrytitle role="top_of_page" id="GtkTooltips.top_of_page">GtkTooltips</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkTooltips</refname>
<refpurpose>Add tips to your widgets</refpurpose>
</refnamediv>

<refsynopsisdiv id="GtkTooltips.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gtk/gtk.h&gt;

                    <link linkend="GtkTooltips-struct">GtkTooltips</link>;
                    <link linkend="GtkTooltipsData">GtkTooltipsData</link>;
<link linkend="GtkTooltips">GtkTooltips</link>*        <link linkend="gtk-tooltips-new">gtk_tooltips_new</link>                    (void);
<link linkend="void">void</link>                <link linkend="gtk-tooltips-enable">gtk_tooltips_enable</link>                 (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);
<link linkend="void">void</link>                <link linkend="gtk-tooltips-disable">gtk_tooltips_disable</link>                (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);
<link linkend="void">void</link>                <link linkend="gtk-tooltips-set-delay">gtk_tooltips_set_delay</link>              (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips,
                                                         <link linkend="guint">guint</link> delay);
<link linkend="void">void</link>                <link linkend="gtk-tooltips-set-tip">gtk_tooltips_set_tip</link>                (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips,
                                                         <link linkend="GtkWidget">GtkWidget</link> *widget,
                                                         const <link linkend="gchar">gchar</link> *tip_text,
                                                         const <link linkend="gchar">gchar</link> *tip_private);
<link linkend="GtkTooltipsData">GtkTooltipsData</link>*    <link linkend="gtk-tooltips-data-get">gtk_tooltips_data_get</link>               (<link linkend="GtkWidget">GtkWidget</link> *widget);
<link linkend="void">void</link>                <link linkend="gtk-tooltips-force-window">gtk_tooltips_force_window</link>           (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-tooltips-get-info-from-tip-window">gtk_tooltips_get_info_from_tip_window</link>
                                                        (<link linkend="GtkWindow">GtkWindow</link> *tip_window,
                                                         <link linkend="GtkTooltips">GtkTooltips</link> **tooltips,
                                                         <link linkend="GtkWidget">GtkWidget</link> **current_widget);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkTooltips.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
         +----<link linkend="GtkObject">GtkObject</link>
               +----GtkTooltips
</synopsis>
</refsect1>








<refsect1 id="GtkTooltips.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GtkTooltips"><type>GtkTooltips</type></link> has been deprecated in GTK+ 2.12, in favor of the new
<link linkend="GtkTooltip"><type>GtkTooltip</type></link> API.
</para>
<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.
</para>
<para>
An individual tooltip belongs to a group of tooltips. A group is created with a call to <link linkend="gtk-tooltips-new"><function>gtk_tooltips_new()</function></link>. Every tooltip in the group can then be turned off with a call to <link linkend="gtk-tooltips-disable"><function>gtk_tooltips_disable()</function></link> and enabled with <link linkend="gtk-tooltips-enable"><function>gtk_tooltips_enable()</function></link>.
</para>
<para>
The length of time the user must keep the mouse over a widget before the tip is shown, can be altered with <link linkend="gtk-tooltips-set-delay"><function>gtk_tooltips_set_delay()</function></link>. This is set on a 'per group of tooltips' basis.
</para>
<para>
To assign a tip to a particular <link linkend="GtkWidget"><type>GtkWidget</type></link>, <link linkend="gtk-tooltips-set-tip"><function>gtk_tooltips_set_tip()</function></link> is used.
</para>
<note>
<para>
Tooltips can only be set on widgets which have their own X window and
receive enter and leave events.
To check if a widget has its own window use <link linkend="GTK-WIDGET-NO-WINDOW--CAPS"><function>GTK_WIDGET_NO_WINDOW()</function></link>.
To add a tooltip to a widget that doesn't have its own window, place the
widget inside a <link linkend="GtkEventBox"><type>GtkEventBox</type></link> and add a tooltip to that instead.
</para>
</note>
<para>
The default appearance of all tooltips in a program is determined by the current GTK+ theme that the user has selected.
</para>
<para>
Information about the tooltip (if any) associated with an arbitrary widget can be retrieved using <link linkend="gtk-tooltips-data-get"><function>gtk_tooltips_data_get()</function></link>.
</para>
<para>
<example>
<title>Adding tooltips to buttons.</title>
<programlisting>
   GtkWidget *load_button, *save_button, *hbox;
   GtkTooltips *button_bar_tips;
   button_bar_tips = gtk_tooltips_new (<!-- -->);
   /* Create the buttons and pack them into a GtkHBox */
   hbox = gtk_hbox_new (TRUE, 2);
   load_button = gtk_button_new_with_label ("Load a file");
   gtk_box_pack_start (GTK_BOX (hbox), load_button, TRUE, TRUE, 2);
   gtk_widget_show (load_button);
   save_button = gtk_button_new_with_label ("Save a file");
   gtk_box_pack_start (GTK_BOX (hbox), save_button, TRUE, TRUE, 2);
   gtk_widget_show (save_button);
   gtk_widget_show (hbox);
   /* Add the tips */
   gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), load_button,
				 "Load a new document into this window",
				 "Requests the filename of a document.
				  This will then be loaded into the current
				  window, replacing the contents of whatever
				  is already loaded.");
   gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), save_button,
				 "Saves the current document to a file",
				 "If you have saved the document previously,
				  then the new version will be saved over the
				  old one. Otherwise, you will be prompted for
				  a filename.");
</programlisting></example>
</para>
</refsect1>

<refsect1 id="GtkTooltips.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkTooltips-struct" role="struct">
<title>GtkTooltips</title>
<indexterm zone="GtkTooltips-struct" role="deprecated"><primary sortas="Tooltips">GtkTooltips</primary></indexterm><programlisting>typedef struct _GtkTooltips GtkTooltips;</programlisting>
<warning><para><literal>GtkTooltips</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members.
</para></refsect2>
<refsect2 id="GtkTooltipsData" role="struct" condition="deprecated:2.12:">
<title>GtkTooltipsData</title>
<indexterm zone="GtkTooltipsData" role="deprecated"><primary sortas="TooltipsData">GtkTooltipsData</primary></indexterm><programlisting>typedef struct {
  GtkTooltips *tooltips;
  GtkWidget *widget;
  gchar *tip_text;
  gchar *tip_private;
} GtkTooltipsData;
</programlisting>
<warning><para><literal>GtkTooltipsData</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
<structfield>tooltips</structfield> is the <link linkend="GtkTooltips"><type>GtkTooltips</type></link> group that this tooltip belongs to. <structfield>widget</structfield> is the <link linkend="GtkWidget"><type>GtkWidget</type></link> that this tooltip data is associated with. <structfield>tip_text</structfield> is a string containing the tooltip message itself.</para>
<para>
<structfield>tip_private</structfield> is a string that is not shown as the default tooltip. Instead, this message may be more informative and go towards forming a context-sensitive help system for your application. (FIXME: how to actually "switch on" private tips?)
</para></refsect2>
<refsect2 id="gtk-tooltips-new" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_new ()</title>
<indexterm zone="gtk-tooltips-new" role="deprecated"><primary sortas="tooltips_new">gtk_tooltips_new</primary></indexterm><programlisting><link linkend="GtkTooltips">GtkTooltips</link>*        gtk_tooltips_new                    (void);</programlisting>
<warning><para><literal>gtk_tooltips_new</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Creates an empty group of tooltips. This function initialises a <link linkend="GtkTooltips"><type>GtkTooltips</type></link> structure. Without at least one such structure, you can not add tips to your application.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GtkTooltips"><type>GtkTooltips</type></link> group for you to use.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-enable" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_enable ()</title>
<indexterm zone="gtk-tooltips-enable" role="deprecated"><primary sortas="tooltips_enable">gtk_tooltips_enable</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tooltips_enable                 (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);</programlisting>
<warning><para><literal>gtk_tooltips_enable</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Allows the user to see your tooltips as they navigate your application.
</para><variablelist role="params">
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkTooltips"><type>GtkTooltips</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-disable" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_disable ()</title>
<indexterm zone="gtk-tooltips-disable" role="deprecated"><primary sortas="tooltips_disable">gtk_tooltips_disable</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tooltips_disable                (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);</programlisting>
<warning><para><literal>gtk_tooltips_disable</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Causes all tooltips in <parameter>tooltips</parameter> to become inactive. Any widgets that have tips associated with that group will no longer display their tips until they are enabled again with <link linkend="gtk-tooltips-enable"><function>gtk_tooltips_enable()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkTooltips"><type>GtkTooltips</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-set-delay" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_set_delay ()</title>
<indexterm zone="gtk-tooltips-set-delay" role="deprecated"><primary sortas="tooltips_set_delay">gtk_tooltips_set_delay</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tooltips_set_delay              (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips,
                                                         <link linkend="guint">guint</link> delay);</programlisting>
<warning><para><literal>gtk_tooltips_set_delay</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Sets the time between the user moving the mouse over a widget and the widget's tooltip appearing.
</para><variablelist role="params">
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkTooltips"><type>GtkTooltips</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delay</parameter>&#160;:</term>
<listitem><simpara>an integer value representing milliseconds.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-set-tip" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_set_tip ()</title>
<indexterm zone="gtk-tooltips-set-tip" role="deprecated"><primary sortas="tooltips_set_tip">gtk_tooltips_set_tip</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tooltips_set_tip                (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips,
                                                         <link linkend="GtkWidget">GtkWidget</link> *widget,
                                                         const <link linkend="gchar">gchar</link> *tip_text,
                                                         const <link linkend="gchar">gchar</link> *tip_private);</programlisting>
<warning><para><literal>gtk_tooltips_set_tip</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Adds a tooltip containing the message <parameter>tip_text</parameter> to the specified <link linkend="GtkWidget"><type>GtkWidget</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkTooltips"><type>GtkTooltips</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GtkWidget"><type>GtkWidget</type></link> you wish to associate the tip with.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tip_text</parameter>&#160;:</term>
<listitem><simpara>a string containing the tip itself.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tip_private</parameter>&#160;:</term>
<listitem><simpara>a string of any further information that may be useful if the user gets stuck.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-data-get" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_data_get ()</title>
<indexterm zone="gtk-tooltips-data-get" role="deprecated"><primary sortas="tooltips_data_get">gtk_tooltips_data_get</primary></indexterm><programlisting><link linkend="GtkTooltipsData">GtkTooltipsData</link>*    gtk_tooltips_data_get               (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<warning><para><literal>gtk_tooltips_data_get</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Retrieves any <link linkend="GtkTooltipsData"><type>GtkTooltipsData</type></link> previously associated with the given widget.
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkWidget"><type>GtkWidget</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GtkTooltipsData"><type>GtkTooltipsData</type></link> struct, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the widget has no tooltip.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-force-window" role="function" condition="deprecated:2.12:">
<title>gtk_tooltips_force_window ()</title>
<indexterm zone="gtk-tooltips-force-window" role="deprecated"><primary sortas="tooltips_force_window">gtk_tooltips_force_window</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tooltips_force_window           (<link linkend="GtkTooltips">GtkTooltips</link> *tooltips);</programlisting>
<warning><para><literal>gtk_tooltips_force_window</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Ensures that the window used for displaying the given <parameter>tooltips</parameter> is created.
</para>
<para>
Applications should never have to call this function, since GTK+ takes
care of this.
</para><variablelist role="params">
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkToolTips"><type>GtkToolTips</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tooltips-get-info-from-tip-window" role="function" condition="deprecated:2.12:|since:2.4">
<title>gtk_tooltips_get_info_from_tip_window ()</title>
<indexterm zone="gtk-tooltips-get-info-from-tip-window" role="deprecated"><primary sortas="tooltips_get_info_from_tip_window">gtk_tooltips_get_info_from_tip_window</primary></indexterm><indexterm zone="gtk-tooltips-get-info-from-tip-window" role="2.4"><primary sortas="tooltips_get_info_from_tip_window">gtk_tooltips_get_info_from_tip_window</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_tooltips_get_info_from_tip_window
                                                        (<link linkend="GtkWindow">GtkWindow</link> *tip_window,
                                                         <link linkend="GtkTooltips">GtkTooltips</link> **tooltips,
                                                         <link linkend="GtkWidget">GtkWidget</link> **current_widget);</programlisting>
<warning><para><literal>gtk_tooltips_get_info_from_tip_window</literal> has been deprecated since version 2.12 and should not be used in newly-written code. </para></warning>
<para>
Determines the tooltips and the widget they belong to from the window in 
which they are displayed. 
</para>
<para>
This function is mostly intended for use by accessibility technologies;
applications should have little use for it.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tip_window</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GtkWindow"><type>GtkWindow</type></link> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tooltips</parameter>&#160;:</term>
<listitem><simpara> the return location for the tooltips which are displayed 
   in <parameter>tip_window</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>current_widget</parameter>&#160;:</term>
<listitem><simpara> the return location for the widget whose tooltips 
   are displayed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>tip_window</parameter> is displaying tooltips, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>

</refsect1>



<refsect1 id="GtkTooltips.see-also">
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<term><link linkend="GtkToolbar"><type>GtkToolbar</type></link></term>
<listitem><para>Create groups of widgets with their own tooltips.</para></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GtkTipsQuery"><type>GtkTipsQuery</type></link></term>
<listitem><para>Query tooltips to create context-sensitive help.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

</refentry>
