<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-tooltips">

  <title>Migrating from GtkTooltips to GtkTooltip</title>

  <para>
    GTK+ 2.12 brings a completely new tooltip implementation which
    allows many things that were not possible with the old 
    #GtkTooltips interface. The new possibilities are explained
    in more detail in the section about #GtkTooltip. 
  </para>

  <para>
    A number of complications of the old API have been removed:
    <itemizedlist>

      <listitem><para>
        Tooltips can not be grouped anymore. The old tooltips
        API allowed this by using multiple #GtkTooltips objects.
        We believe that the timeout behaviour of the new tooltips 
        implementation is better and makes it unnecessary to use 
        grouping as a way to overcome shortcomings of the 
        fast-tooltips mode.
      </para></listitem>

      <listitem><para>
        Timeouts can not be set individually anymore. Instead
        there are settings #GtkSettings:gtk-tooltip-timeout, 
        #GtkSettings:gtk-tooltip-browse-timeout and
        #GtkSettings:gtk-tooltip-browse-mode-timeout to influence
        the behaviour of tooltips globally.
      </para></listitem>

    </itemizedlist>
  </para>

  <para>
    Here is an example of setting a tooltip on a widget with the old API:
    <informalexample><programlisting>
GtkTooltips *tooltips = gtk_tooltips_new ();     
gtk_tooltips_set_tip (tooltips, widget, "Some tips", NULL);
    </programlisting></informalexample>
  </para>
  <para>
    Using the new tooltips API, it is no longer necessary to create 
    an object:
    <informalexample><programlisting>
gtk_widget_set_tooltip_text (widget, "Some tips");
    </programlisting></informalexample>
  </para>
  <para>
    Similarly, setting a tooltip on a #GtkToolItem gets
    simplified from
    <informalexample><programlisting>
gtk_tool_item_set_tooltip (toolitem, toolbar->tooltips, "tool tip", NULL);
    </programlisting></informalexample>
    to
    <informalexample><programlisting>
gtk_tool_item_set_tooltip_text (toolitem, text);
    </programlisting></informalexample>
  </para>

</chapter>