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.
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list
