help sys API

[Havoc Pennington <hp redhat com>]

Hi,

I can't find Sopwith on IRC so here are some thoughts on help before I
forget.

 The Qt interface for this is here:
   http://www.troll.no/qt/qwhatsthis-h.html

 It's a good bit simpler and easier to understand than our current mess.
It also brings up a good point; support for What's This should probably be
in GTK, because you need a virtual "get what's this text" function for
complex widgets with more than one what's this "target". Alternatively
we'd have a set_whatsthis_func call or something.

I would like to see:

 - one interface to get/set three different help levels on a widget:
    tooltip, whatsthis, and long URL; these interfaces should be in GTK
    and may be virtualized. Then you can choose your own way to 
    display the stuff if you want
 - tooltip and whatsthis popup widgets (the actual windows that pop up)
   available for separate use. (I have a tooltip widget in Guppi, 
   come to think of it, that could be easily modified to support the 
   nice ivory-with-shadow look the Qt popup help has)
 - GTK should have a widget_set_tooltip function, the need to manually
   create and attach a tooltip is gratuitous
 - convenience functions to create what's this toolbar button and menu
   item in GTK
 - GNOME code to let doc authors fill in the widget<->help association 
   file 
 - GNOME code that uses some sort of hook to load the widget<->help
   file and attach the help to the widgets
 - functions to enter/leave "what's this" mode, so you can have your 
   own UI to do that ("what's this" mode is the mode where the cursor 
   is a question mark and you click to get help) - this way you can 
   create custom ways to start/stop whatsthis mode.
   (this could actually call a generic callback when a widget is chosen, 
   so you can also use the code for other "pick a widget" situations)
 - GnomeHelpView widget is a way to magically display help in a GnomeApp

Between GtkTooltip, GtkTipsQuery, gnome-popup-help, and gnome-helpsys I
think this is another case of a confusing collection of semi-solutions. We
should talk about how to create a nice, clean, single API that looks like
it's been planned. Specific points in this email aside, the overall help
picture is definitely cleaner in Qt; it feeds the "Qt benefits from
unified commercial design" claim; we should address this problem.

As a programmer I think I'd like to say this for each widget:
 gtk_widget_set_name(widget, "blah"); /* Glade should do this automatically */
 gtk_widget_set_help(widget, _("tooltip"), _("whatsthis"), "url");

In GNOME we could replace gtk_widget_set_help() with loading some kind of
resource file that keys on widget names; I don't know if that's 
good or not (for tooltip and whatsthis it seems that we may as well just
use gettext's message catalog, programmers are more likely to write the
help if they can do it "inline").

Then something like:
 button = whatsthis_make_button();
 gtk_toolbar_add(toolbar, button); 
 menuitem = whatsthis_make_menuitem();
 gtk_menu_append(help_menu, menuitem);

with gnome-app-helper doing that automatically if requested.

I don't know the best solution, I just think this is a problem that should
be addressed by GTK and Gnome together and I think we need a clean,
easy-to-use solution.

Havoc