More tooltips docs

svn path=/trunk/; revision=18443

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index cb66d48896f1b58899dc7a11c8e8f3664fd73dea..0b26c720ee6565fd0c59722d3c88cd03620128d2 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,16 @@
+2007-07-11  Matthias Clasen  <mclasen@redhat.com>
+
+       * gtk/migrating-GtkTooltip.sgml: Migration chapter
+       for tooltips.
+
+       * gtk/gtk-docs.sgml: Include it, and move GtkTooltips
+       chapter to "Deprecated".
+
+       * gtk/Makefile.am: Glue
+
+       * gtk/tmpl/gtktooltip.sgml: Add more content from
+       Kris' "tooltips in 5 minutes" mail.
+
 2007-07-10  Matthias Clasen  <mclasen@redhat.com>
        
        * gdk/tmpl/colors.sgml: Remov references to deprecated

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index f596d8a88ab95f4d2799d1eab2c137975819c178..f123be2f6863224221f7fffd6160397d86522499 100644 (file)
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -136,6 +136,7 @@ content_files =                                     \
        migrating-GtkRecentChooser.sgml         \
        migrating-GtkLinkButton.sgml            \
        migrating-GtkBuilder.sgml               \
+        migrating-GtkTooltip.sgml              \
        objects_grouped.sgml                    \
        osx.sgml                                \
        question_index.sgml                     \
@@ -162,6 +163,7 @@ expand_content_files =                              \
        migrating-GtkRecentChooser.sgml         \
        migrating-GtkLinkButton.sgml            \
        migrating-GtkBuilder.sgml               \
+       migrating-GtkTooltip.sgml               \
        tree_widget.sgml                        \
        text_widget.sgml                        \
        question_index.sgml

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 5f720b6c182c84f5d39683f09f7130ac76206839..c1667a3ae640ee5780e585300e8715ec6e1460c1 100644 (file)
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -226,6 +226,7 @@
 <!ENTITY gtk-migrating-GtkRecentChooser SYSTEM "xml/migrating-GtkRecentChooser.sgml">
 <!ENTITY gtk-migrating-GtkLinkButton SYSTEM "xml/migrating-GtkLinkButton.sgml">
 <!ENTITY gtk-migrating-GtkBuilder SYSTEM "xml/migrating-GtkBuilder.sgml">
+<!ENTITY gtk-migrating-GtkTooltip SYSTEM "xml/migrating-GtkTooltip.sgml">
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
 <!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
@@ -545,7 +546,6 @@ that is, GUI components such as #GtkButton or #GtkTextView.
         &GtkIMMulticontext;
         &GtkSizeGroup;
         &GtkTooltip;
-        &GtkTooltips;
         &GtkViewport;
         &GtkAccessible;
     </chapter>
@@ -614,6 +614,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
         &GtkPreview;
         &GtkProgress;
         &GtkText;
+        &GtkTooltips;
         &GtkTipsQuery;
         &GtkTree;
         &GtkTreeItem;
@@ -646,6 +647,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     &gtk-migrating-GtkRecentChooser;
     &gtk-migrating-GtkLinkButton;
     &gtk-migrating-GtkBuilder;
+    &gtk-migrating-GtkTooltip;
   </part>
 
   <part>
@@ -682,4 +684,5 @@ that is, GUI components such as #GtkButton or #GtkTextView.
   <index role="2.12">
     <title>Index of new symbols in 2.12</title>
   </index>  
+
 </book>

diff --git a/docs/reference/gtk/migrating-GtkTooltip.sgml b/docs/reference/gtk/migrating-GtkTooltip.sgml
new file mode 100644 (file)
index 0000000..f0fc971
--- /dev/null
+++ b/docs/reference/gtk/migrating-GtkTooltip.sgml
@@ -0,0 +1,62 @@
+<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>

diff --git a/docs/reference/gtk/tmpl/gtktooltip.sgml b/docs/reference/gtk/tmpl/gtktooltip.sgml
index 15a00ccc3f6f6aedffab43ce5ea947d0a85ddbca..1d18d66c7e9ca73b205619e36f11b799e538bae7 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktooltip.sgml
+++ b/docs/reference/gtk/tmpl/gtktooltip.sgml
@@ -11,14 +11,67 @@ introduced in GTK+ 2.12 and which deprecates the old
 #GtkTooltips API. 
 </para>
 <para>
-Basic tooltips can be realized simply by using
-gtk_widget_set_tooltip_text() or gtk_widget_set_tooltip_markup() without
-any explicit tooltip object. For fancy tooltips, you will likely
-connect to the #GtkWidget::query-tooltip signal, which is passed
-a #GtkTooltip object as the last parameter. You can use functions
-like gtk_tooltip_set_icon() to modify the tooltip.  
+Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
+or gtk_widget_set_tooltip_markup() 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 GtkTreeView row or cell, you will have to do a little more work:
+<itemizedlist>
+
+<listitem><para>
+Set the #GtkWidget:has-tooltip property to %TRUE, this will
+make GTK+ monitor the widget for motion and related events
+which are needed to determine when and where to show a tooltip.
+</para></listitem>
+
+<listitem><para>
+Connect to the #GtkWidget::query-tooltip 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 #GtkTooltip
+object. This is the object that we are about to display as a 
+tooltip, and can be manipulated in your callback using functions
+like gtk_tooltip_set_icon(). There are functions for setting
+the tooltip's markup, setting an image from a stock icon, or
+even putting in a custom widget.
+</para></listitem>
+
+<listitem><para>
+Return %TRUE from your query-tooltip handler. This causes
+the tooltip to be show. If you return %FALSE, it will not be shown. 
+</para></listitem>
+</itemizedlist>
+</para>
+
+<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
+#GtkWindow which will be used as tooltip window.  This works as
+follows:
+<itemizedlist>
+
+<listitem><para>
+Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as 
+before.
+</para></listitem>
+
+<listitem><para>
+Use gtk_widget_set_tooltip_window() to set a #GtkWindow created
+by you as tooltip window.
+</para></listitem>
+
+<listitem><para>
+In the ::query-tooltip callback you can access your window
+using gtk_widget_get_tooltip_window() and manipulate as you
+wish. The semantics of the return value are exactly as before,
+return %TRUE to show the window, %FALSE to not show it.
+</para></listitem>
+</itemizedlist>
+</para>
+
+
 <!-- ##### SECTION See_Also ##### -->
 <para>