Re: New tooltips API, continued

[Martyn Russell <martyn imendio com>]

On Tue, 2006-03-14 at 14:25 +0100, Kristian Rietveld wrote:
> Hey,

Hi :)

> 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.

>From a user's point of view, it doesn't really feel right making owner a
GObject, a GtkWidget would fit better with the rest of the API IMO.

> 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.

That all sounds good to me.

> 6. Random thoughts:
>   - Maybe we want to name the tooltip window "GtkTooltipWindow" instead of
>     "GtkTooltipsWindow", since the window displays a single tooltip?

I prefer GtkTooltipWindow personally.

>   - 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?

I think this could be interesting. Tooltips with widgets on them might
look weird unless they follow controlled themes. 

I think that having shaped windows would be pretty cool, but perhaps a
themed shape otherwise you might get apps having tooltip windows in
different shapes to other apps - which would ruin the consistency on the
desktop.

--
Regards,
Martyn