New tooltips API, continued

[Kristian Rietveld <kris imendio com>]

Hey,


My apologies for being so late to reply on this topic, and thanks to all who
replied on my earlier mail.  I hope this proposal will be another step forward
to a new tooltips API for GTK+.  I am replying with one large mail, since that
is probably easier than several separate replies.  Since I am building on the
API found in the previous mail[1], it might be useful to read that one
through again before continuing here.

This proposal is of course by no means final, a lot will have to be refined
later on.  But once we agree on a general direction (and hopefully the
proposal below is exactly that ;) I can start working on an implemention and
we can refine from there.


1. GtkTooltipsWindow will either be a GtkWindow or a GtkContainer, depending
on the implementation.  This means it will always be possible to pack your
own widgets in it.  We will keep the convenience functions:

  gtk_tooltips_window_set_text ()
  gtk_tooltips_window_set_markup ()

2. We add a "populate-tooltip" signal to GtkTooltipsWindow.  This signal will
be emitted when the tooltip is about to pop up and gives you the chance to,
for example, fill the window with content related to the current position
of the mouse pointer or focus.

3. Next to the "tooltip" and "tooltip-uses-markup" properties already
introduced in GtkWidget, we introduce a "tooltips-window" property and a pair
of get/set functions:

   gtk_widget_get_tooltips_window ()
   gtk_widget_set_tooltips_window ()

Contrary to the previous proposal, getting the tooltip window will not
provide you with a tooltips window created on demand when no tooltip window
has been set yet.  We now distinguish three types of tooltips:

  - The really simple tooltips, controlled by the tooltip/tooltip-use-markup
    properties on GtkWidget.  When the tooltip property is set, GtkWidget
    will do the following:

      * Create a tooltip window and call gtk_widget_set_tooltip_window() if
        necessary,
      * call gtk_tooltip_window_set_text() or gtk_tooltip_window_set_markup()
        to set the content of the tooltip.

    GtkWidget will handle popping up and popping down the tooltip.  In this
    case the application programmer has nothing to do with the tooltip window.
    We will also provide gtk_widget_show_tooltip() (or maybe
    gtk_widget_show_tooltips_window()) to have GtkWidget popup the tooltip
    window immediately, when one is set.

  - Next case is having a single tooltip per widget, but with widgets packed.
    This would work as follows:
      * The application programmer calls gtk_tooltips_window_new () and
        gtk_widget_set_tooltips_window().  Because of the call to
        gtk_widget_set_tooltips_window(), GtkWidget will handle popping up
        and popping down the tooltip.  Also gtk_widget_show_tooltip() will
        work for this case.
      * Set the content of the tooltip window now, or connect to the 
        "populate-tooltip" signal to be able to fill it later.

  - Complex tooltips.  GtkTreeView would use this for example.
      * Create your own tooltip window using gtk_tooltip_window_new ().
      * Set the content of the tooltip window now and/or connect to the
        populate-tooltip signal.
      * In this case you get to handle tooltip pop up/down yourself.

4. For controlling popping up/down the tooltips window we already discussed
the following API:

  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);

This API would only be used by GtkWidget and by widgets implementing their
"own" complex tooltips.  The general idea is that you call the _begin()
function with the GTK_TOOLTIPS_MOUSE context if the mouse enters a tooltip
area and _end() with the mouse contenxt when it leaves that area.  Likewise
for the keyboard context.

The owner arguments are there for allowing proper handling of nested tooltips
areas.  The idea for making this a GObject was taken over from Owen's
original plan.  It can be any GObject: a widget, a GdkWindow, etc.  We might
change this during the implementation phase when needed.

5. We will replace the get_tooltip method in the GtkCellRenderer interface,
which was proposed earlier with a populate-tooltip signal.  The signal
will have a gboolean return value.  When this value is FALSE, it means
that the cell does not have a tooltip and nothing will be displayed.

6. Random thoughts:
  - Maybe we want to name the tooltip window "GtkTooltipWindow" instead of
    "GtkTooltipsWindow", since the window displays a single tooltip?
  - Maybe we want to add support to have the way the tooltips are drawn
    controlled by themes?  Currently there is a tooltip detail for the
    flat box, but this might not suffice for the new API.  We might want to
    have shaped windows?


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



-kris.


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