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

[Murray Cumming <murrayc murrayc com>]

On Tue, 2007-06-12 at 13:59 +0200, Kristian Rietveld wrote:
> 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.

So could we deprecate GtkTooltips with #ifdefs and gtk-doc comments?

Thanks for the great overview.

>   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.
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com