Callback based tooltips (Re: New tooltips API, continued)

[Tim Janik <timj imendio com>]

On Tue, 14 Mar 2006, Kristian Rietveld wrote:

> Hey,
[...]


hi kris.

reading your proposal for the first time (both versions of it), i can't help the
feeling that it seems a bit complicated (with nesting tip areas etc.) at least
from a widget user perspective.
i'm wondering if a callback based approach wouldn't ease the whole setup a lot,
so to brainstorm for a second:

typedef struct {
  GObject parent_instance;
  /*< opaque >*/
} GtkTooltip;

void	gtk_tooltip_set_markup (GtkTooltip	*tooltip,
                                const gchar     *markup);
void	gtk_tooltip_set_icon   (GtkTooltip	*tooltip,
                                GdkPixbuf       *pixbuf);
void	gtk_tooltip_set_custom (GtkTooltip	*tooltip,
                                GtkWidget       *custom_widget);

struct GtkWidgetClass {
  [...]
  gboolean	(*query_tooltip)	(GtkWidget	*widget,
                                         gint            x,
                                         gint            y,
                                         GtkTooltip     *tooltip);
};

void		gtk_widget_set_tooltip_window	(GtkWidget	*widget,
                	                         GtkWindow      *custom_window);
GtkWindow*	gtk_widget_get_tooltip_window	(GtkWidget	*widget);

/* and properties: */
gboolean     GtkWidget::has-tooltip; default=FALSE;
const gchar* GtkWidget::tooltip-markup; /* auto sets has-tooltip=TRUE */


in the above, 90% of all tooltips are covered by GtkWidget::tooltip-markup,
the text of which can be used as:
static gboolean
gtk_widget_real_query_tooltip (GtkWidget      *widget,
                               gint            x,
                               gint            y,
                               GtkTooltip     *tooltip)
{
  if (widget->::tooltip-markup)
    {
      gtk_tooltip_set_markup (tooltip, widget->::tooltip-markup);
      return TRUE; /* there is a tooltip to be displayed at x/y for widget */
    }
  return FALSE; /* there is no tooltip to be displayed */
}

it also coveres moderately advanced cases with gtk_tooltip_set_icon() and
gtk_tooltip_set_custom(). for real adventurous tooltipping, people can use
gtk_widget_set_tooltip_window() and mess up their custom window instead
of GtkTooltip inside of a ::query_tooltip() handler. the common case
however would be to not make use of gtk_widget_set_tooltip_window().

compared to your proposal, i think this would not only be simpler to use,
but also:
- allow "nesting" of tooltips by emitting ::query_tooltip() on widget
  while (result == FALSE && widget->parent) widget = widget->parent;
  i.e. walk a widget's ancestry until a tip is found.
- Gtk+ can decide to "cache" tooltip windows for widgets that don't use
  gtk_widget_set_tooltip_window(), e.g. by having a global list that just
  contains 1 GtkWindow per display.
- for area specific tooltipping, widgets don't need to track the mouse
  pointer themselves. once gtk is in tooltip mode, ::query_tooltip() is
  simply emitted as the pointer moves.
- in constrast to your proposal, the decision of *when* to popup tooltips,
  and how long they are left up is completely up to gtk. this is actually
  meant to improve user experience, since gtk can honour per-display
  tooltip behaviour settings, and tooltip popup behaviour will be consistent
  across widgets on the same display.
- there's no "grouping" of tooltips provided. for one, that's because i
  don't really understand the use case for that. once in tooltip mode, all
  widget tooltips can simply be popped up/changed seemlessly, until some
  significant user action forces leave of tooltip mode again (button press,
  key press).
  and for another, if grouping really is required, that can still be
  implemented after the fact with API similar to what you suggested.
- because GtkTooltip is opaque and basically just implements a limited
  set of tip setters, future versions could allow gtk-wide or per-display
  plugging of tooltip objects. this could be interesting for embedded
  devices, respectively touchscreens, which may want to display tooltips
  in a non-standard way. e.g. an "info popup" in the upper right corner
  like the N770 has it. it also would cover themes that want to implement
  specialized tooltip display.
- querying tooltips via ::query_tooltip() will also be easily customizable
  via connecting signal handlers to widgets, and it will work for insensitive
  widgets even with area sensitive tooltips. especially the latter isn't really
  covered by your proposal afaiu but an often requested feature.

> That's all for today, thanks for your attention.

well, sorry for coming back so late. hope i could provide some usefull
input anyway ;)

> -kris.
>
>
> [1] http://mail.gnome.org/archives/gtk-devel-list/2006-January/msg00251.html

---
ciaoTJ