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 [EMAIL PROTECTED] www.murrayc.com www.openismus.com _______________________________________________ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
