Re: Proposal for new tooltips API

[Alex Graveley <alex beatniksoftware com>]

Hi Kristian,

Really glad to see someone taking the initiative on this!

I haven't followed any of the previous discussions, but what about the 
following alterations?

1) Add this GtkWidget signal:

	gboolean (*populate_tooltip) (GtkTooltipWindow *win,
                                      GtkRectangle *widget_area);

widget_area would be passed with zero values, which would cause the 
placement logic to substitute the widget's allocation, giving the same 
placement as today.  This could be clamped or extended for complex 
widgets like  GtkTreeView.

GtkWidget would track mouse motion pauses itself, and fire this signal.

Toolbars and other containers which have custom tooltip-showing 
requirements could fire this on their children.

2) Make GtkToolTipWindow an actual GtkWindow that users can pack widgets 
into (please!).  This in addition to the 
gtk_tooltips_window_set_text/markup utilities you've described.

3) Add this call to GtkTooltipWindow:

	void gtk_tooltip_window_show_for_widget (GtkTooltipWindow *win,
						 GtkWidget *widget);

This would handle calling populate_tooltip on the widget and moving the 
tooltip window to the proper location before showing it (without delay).

4) Substitute a similar populate_tooltip call instead of get_tooltip for 
 GtkCellRenderers.

It seems like these changes would cover most of the reasons I have had 
to re-implement tooltips in my code.  Namely:
- Need to show/hide a tooltip on-demand
- Need to use complex widgets inside the tooltip window
- Need to place tooltips manually

-Alex

Kristian Rietveld wrote:
> Hello,
>
>
> We've had a bug opened on reworking the tooltips API since 2001 (#50619) and
> GtkTreeView needs this in order to be able to support tooltips on rows, cells,
> etc.  So it's about time to do something about it.  In this proposal I am
> basically building forth on the work of Owen Taylor and Christof Petig, the
> e-mail thread is archived at [1].
>
> Basically, we see two kinds of tooltips:
>   a) A simple widget which just has a single tip (eg. GtkButton),
>   b) A complex widget which can have multiple tips, which tip is shown is
>      usually determined by the position of the mouse cursor or keyboard focus
>      (eg. GtkTreeView).
>
> As a main encompassing object we would introduce GtkTooltipsWindow.  This
> widget would take care of displaying the yellow rectangle and logic for
> showing/hiding the tooltip based on keyboard and mouse actions.  Its API
> will be described later on.  The plan is to have a single GtkTooltipsWindow
> per widget, created on demand.
>
> Now, tooltip kind a) is easily solved by introducing "tooltip" and
> "tooltip-uses-markup" properties in the GtkWidget object.  GtkWidget would
> create a GtkTooltipsWindow on demand and showing the tooltip will be handled
> automatically.
>
> For the more complex tooltips handling, the widget would manipulate the
> GtkTooltipsWindow itself.  The tooltips window can be acquired using:
>
>   gtk_widget_get_tooltips_window()
>
> the tooltips window will be created on demand if required.  The object can be
> manipulated with the following functions:
>
>   typedef enum { GTK_TOOLTIPS_MOUSE, GTK_TOOLTIPS_KEYBOARD } GtkTooltipsContext;
>
>   void gtk_tooltips_window_begin (GtkTooltipsWindow *window,
> 				  GtkTooltipsContext context,
> 				  GObject           *owner);
>   void gtk_tooltips_window_end   (GtkTooltipsWindow *window,
> 				  GtkTooltipsContext context,
> 				  GObject           *owner);
>
> For widget global tooltips (the properties), these functions are called by
> gtkwidget.c. But for widgets with multiple tooltips within them, it would be
> called by the widget implementation as it receives enter/leave
> focus-in/focus-out events.  These functions would update internal state
> variables, set up timeouts, etc.
>
>   void gtk_tooltips_window_set_text (GtkTooltipsWindow  *window,
> 				     GtkTooltipsContext  context,
> 				     GObject            *owner,
> 				     const char         *text);
>   void gtk_tooltips_window_set_markup (GtkTooltipsWindow  *window,
> 				       GtkTooltipsContext  context,
> 				       GObject            *owner,
> 				       const char         *markup);
>
> The widget can use these functions to update the contents on the tooltip.
> For example when the mouse pointer changes position.  These functions would
> only be used for the complex tooltips case (b).
>
>   void gtk_tooltips_window_set_area   (GtkTooltipsWindow  *window,
> 				       GtkTooltipsContext  context,
> 				       GObject            *owner,
> 				       GdkWindow          *relative_to,
> 				       int                 x,
> 				       int                 y,
> 				       int                 width,
> 				       int                 height);
>
> The window, x, y, width, height arguments indicate the area of the object to
> which the tooltip refers. The tooltip would be placed completely 
> clear of this area. (As it is placed to avoid widgets today).
>
> For supporting sticky delay (imagine a toolbar, where each button has a
> tooltip; there you do not want to wait for each tooltip to pop up.  Once
> a tooltip on the toolbar has popped up and the mouse is moved to another
> toolbar button that tooltip will popup instantly) we will introduce
> GtkTooltipsGroup along the lines of GtkSizeGroup. Tooltips windows can then
> be added using
>
>   void gtk_tooltips_window_set_group  (GtkTooltipsWindow  *window,
> 				       GtkTooltipsContext  context,
> 				       GObject            *owner,
> 				       GtkTooltipsGroup   *group);
>
>
> This API should be sufficient for supporting all kinds of tooltips and thus
> the plan is to deprecate GtkTooltips.
>
>
> GtkTreeView needs support for tooltips on a per cell basis.  I am thinking
> of extending the GtkCellRenderer interface with:
>
>   gchar * (* get_tooltip) (GtkCellRenderer  *cell,
>                            gboolean         *uses_markup);
>
>
>
> -kris.
>
>
> [1] http://mail.gnome.org/archives/gtk-devel-list/2004-October/msg00120.html
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list