The new tooltips API in 5 minutes [Was: Re: Whats coming in GTK+ 2.12, continued]

[Kristian Rietveld <kris imendio com>]

On Sun, Jun 10, 2007 at 10:38:44AM +0200, Murray Cumming wrote:
> There's also a new GtkTooltip object. Could we have some more information 
> about how this should be used and if it replaces any existing API, please?

Sure ;)  As Matthias pointed out in one of his other mails, GTK+ 2.12
has a brand-new API for doing tooltips, replacing the aging GtkTooltips
object.  There are several ways for showing tooltips using the new API,
increasing in complexity as the complexity of the wished tooltip
increases:

 1. If everything you need is a tooltip displaying a simple text string,
    with or without Pango markup, the only thing you have to do is
    just setting the "tooltip-markup" property.

 2. 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:

      - Set the has-tooltip property on GtkWidget 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.

      - Connect to the "query-tooltip" signal on GtkWidget.  This signal
        will be emitted when a tooltip will have to be shown.  The
	signature is:

  gboolean     (* query_tooltip)      (GtkWidget  *widget,
                                       gint        x,
                                       gint        y,
                                       gboolean    keyboard_tooltip,
                                       GtkTooltip *tooltip);

	The arguments are pretty much straightforward, and here we see
	where the new GtkTooltip object comes to play.  The GtkTooltip
	is the object that we are about to display as a tooltip, and can
	be manipulated in your query-tooltip callback using functions
	like:

               void gtk_tooltip_set_icon (GtkTooltip  *tooltip,
                                          GdkPixbuf   *pixbuf);

	there are likewise functions for setting the tooltip's markup,
	setting an image from a stock icon or even for putting in a
	custom widget.

	Important is the return value of query-tooltip: when you return
	TRUE the GtkTooltip will be shown, when you return FALSE it will
	not be shown.

 3. 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:

        - Set has-tooltip and connect to query-tooltip as under 2).
	
	- Use gtk_widget_set_tooltip_window() to set a GtkWindow created
	  by you as tooltip window.

	- In the query-tooltip callback you can access your GtkWindow
	  using gtk_widget_get_tooltip_window() and manipulate as you
	  wish.  The semantics of the return value of query-tooltip are
	  exactly the same as with 2): TRUE will show the tooltip
	  window, FALSE will not show it.


In the GTK+ source code you will find a test app testing all of the
above methods in gtk+/tests/testtooltips.c.  There are examples for
simple tooltips on buttons (also insensitive buttons!), tooltips on
GtkTreeView rows, tooltips on GtkTextView tags and a small example with
tooltips on specific areas of a GtkDrawingArea.  (Yes, I know the tree
view example is a little broken -- it will be fixed RSN).

Some small details are still left to be worked out; think of improving
tooltips positioning, probably popup-tooltip-directly-on-demand and at
some later stage greater flexibility and customizability.  Watch
gtk-devel-list for the latest news ;)


I hope this gives you enough information to get started!


regards,

-kris.