Re: Tooltips progress

[Tim Janik <timj imendio com>]

On Wed, 31 May 2006, Kristian Rietveld wrote:

> Last week I've been working on the tooltips implementation, using the
> callback-based approach/interface discussed earlier on this mailing list.
> The basics are working already including keyboard support and custom
> windows.  Before I can finalize a patch for reviewal, I have some comments
> and questions.
>
>
> In a follow up to his original mail, Tim is talking about adding the
> following function:
>
>  gdk_display_force_query_display (GdkDisplay *);
>
> I am not sure if this really belongs in GdkDisplay.  Currently I have a:
>
>  gtk_widget_force_query_tooltip (GtkWidget *widget);
>
> which works just fine for forcably updating a tooltip, in both keyboard
> and mouse mode.  I guess most people will usually know which widget's
> tooltip to update.  Opinions?

yes, in most cases the widget will be known, but not in all.
the trivial example is changing per-display settings like
::display-tooltips = off or the timeout.
also, since we support nesting/overlaying of widgets.
even the display might not be clear, which is why i actually proposed:

void gtk_display_force_tooltip_query (GdkDisplay*); /* display may be NULL */
/* because of nesting/overlapping tooltips, widget is not always known
 * http://mail.gnome.org/archives/gtk-devel-list/2006-April/msg00030.html
 */

but you have a point here, since in most cases the widget will indeed
be known, it'll be most convenient to also provide:
void
gtk_widget_force_query_tooltip (GtkWidget *widget)
{
  gtk_display_force_tooltip_query (gtk_widget_get_display (widget));
}

> Currently, we are using the following query-tooltips signal:
>
>  gboolean (*query_tooltip)     (GtkWidget           *widget,
>                                 gint                 x,
>                                 gint                 y,
>                                 GtkTooltip          *tooltip);
>
> But if a user sets a custom using gtk_widget_set_custom_window(), we don't
> have to pass a GtkTooltip around.  So currently I just set the tooltip
> field to NULL, so the user knows he has to use his own custom tooltip
> window (and we assume he has a reference to that).

my original proposal
  http://mail.gnome.org/archives/gtk-devel-list/2006-April/msg00010.html
included:
  GtkWindow*      gtk_widget_get_tooltip_window   (GtkWidget      *widget);
so the user doesn't need to duplicate tracking of this window.

>  Is this okay or do
> we want to change this?  We could also move the _set_custom_window()
> functions into GtkTooltip for example.

no, i intentionally didn't put it there. the reasoning for this was:
- the setter should go along with a getter
- the user should get at the custom window but *not* the tooltips window
  used by gtk. the latter is violated with a getter on GtkTooltip.

> Implementing GtkTreeView tooltips in your application is now pretty easy,
> just set up a query_tooltip callback and call gtk_tree_view_get_path_at_pos()
> with the coordinates which are provided to you (but if x == -1, the keyboard
> mode is enabled and then you should really call gtk_tree_view_get_cursor()).

using x==-1&&y==-1 for keyboard mode was a bit of an aftermath patchup to
my original proposal.

Matthias Clasen now pointed out:
> Using x == -1 to indicate a keyboard-triggered tooltip looks a bit
> odd to me; how about adding a boolean parameter for this ?

and i thnk he is right. another indication that we'd not want (-1,-1) is that
you already talk about querying the cursor yourself. so it's probably better
to adapt the signal to:
  gboolean      (*query_tooltip)        (GtkWidget      *widget,
                                         gint            x,
                                         gint            y,
                                         gboolean        keyboard_tip,
                                         GtkTooltip     *tooltip);
and preserve the x,y position.

> Would this be sufficient, or do we want to add some special API for supporting
> tooltips in the tree view, like having GtkTreeView implement the query
> tooltip callback and have tooltip-markup properties on cell renderers.
> Personally I think implementing the query-tooltip yourself is easy enough
> for people to do and also really flexible, so there's no need for more API.

i'd say let's first nail the basic tooltip API. GtkWidget already comes with
a default handler. we can still add treeview convenience API later on if that
is required. (and for that, i think it'd be easiest to forward the query_tooltip()
signal to signals on the columns and cell renderers).

> Since we re-query for a tooltip on mouse motion, I was wondering what we
> should do in keyboard mode if a key is pressed in, for example, GtkTreeView.
> A key press there might change the cursor and we might want to update the
> tooltip contents.  Do we want stock GTK+ to take care of this, or should the
> user do this himself?  (For example by calling gtk_widget_force_tooltip_query
> from the GtkTreeSelection::changed callback).

i think i'd handle key press events like mouse motion and scroll events, i.e.
re-query. that eases things on the user side and is consistent with movement.
(the basic idea behind my proposal was that gtk+ takes care of the required
granularity whenever possible, so gtk_display_force_tooltip_query() needs to
allmost never be used).

> thanks,
>
> -kris.

---
ciaoTJ