Online Help

Gnome Documentation and Help Menu Items

The Gnome documentation installation process was described in the section called Documentation in the chapter called Creating Your Source Tree. Recall that applications install documentation in HTML format in directories named after locales. Each locale directory contains both help files and a topic.dat file indexing the available help topics.

Gnome makes it ridiculously easy to create menu items for the nodes in topic.dat. Simply create a help menu using the GNOMEUIINFO_HELP() macro, like this:

static GnomeUIInfo help_menu [] = {
  GNOMEUIINFO_HELP ("gnome-hello"),
  
  GNOMEUIINFO_MENU_ABOUT_ITEM(about_cb, NULL),
  
  GNOMEUIINFO_END
};

The single argument to GNOMEUIINFO_HELP() is the name of the directory where you've installed your help files. The Gnome libraries will read topic.dat for the user's locale (or the C locale if there is no translation) and create a menu item for each topic. Activating these menu items will launch a help browser to display the appropriate URL. (Users can configure the exact browser Gnome will launch.) If topic.dat isn't found, Gnome creates no menu items.

In other contexts, you will have to manually set up widgets and callbacks to open your help files. Gnome provides some helper functions; the two most important ones are shown in Figure 10. gnome_help_file_find_file() returns the complete path to a help file, given the name of your help directory and the name of a help file (relative to one of the locale directories). If the help file is not found, NULL is returned. For example:

  gchar* helpfile;
  
  helpfile = gnome_help_file_find_file("gnome-hello",
                                       "gnome-hello.html");

  if (helpfile != NULL)
    {
      gchar* url;

      url = g_strconcat("file:", helpfile, NULL);

      gnome_help_goto(NULL, url);

      g_free(url);
      g_free(helpfile);
    }
  else
    {
      gnome_error_dialog(_("Couldn't find the GnomeHello manual!"));
    }

gnome_help_file_find_file() takes the user's locale into account when generating the help file's pathname.

gnome_help_goto() simply directs the help browser to a URL. You must prepend "file:" to a path to make it a valid URL before calling this function. The first argument to gnome_help_goto() is ignored; this makes it convenient to connect gnome_help_goto() as a callback function, for example to a button's "clicked" signal.

libgnome/gnome-help.h contains a few other variants of gnome_help_goto() suited for connection to signals with different signatures; in particular, there's a callback there for the GnomePropertyBox's "help" signal.

One caveat: the Gnome libraries look for files in the Gnome installation prefix, not in your application's installation prefix. For now, users should install Gnome applications and libraries in the same place. This was done for simplicity's sake when Gnome was much smaller; it's clearly the wrong behavior and will be fixed in a future version. If you use Gnome library functions such as gnome_help_file_find_file(), your application will automatically take advantage of this future Gnome enhancement.

#include <libgnome/gnome-help.h>

Menu Hints

As the user moves over your application menus, a short description of each menu item should appear in the statusbar. Gnome makes this very easy; just call the gnome_app_install_menu_hints() (Figure 11) after you create your menus and statusbar. The GnomeUIInfo struct passed to this function must have its widget fields filled in by one of the menu-creation functions, and the GnomeApp must have a GnomeAppBar or GtkStatusbar in its statusbar slot.

#include <libgnomeui/gnome-app-helper.h>

Tooltips

GTK+ provides tooltip functionality; you simply create a GtkTooltips and attach it to a widget. I like to use the following convenience function in my applications:

void
set_tooltip(GtkWidget* w, const gchar* tip)
{
  GtkTooltips* t = gtk_tooltips_new();

  gtk_tooltips_set_tip (t, w, tip, NULL);
}

The GtkTooltips will be destroyed along with the widget. Make your tooltips long rather than short; there's no reason to skimp on the amount of information you provide here. You should get in the habit of calling set_tooltip() every time you create a button or other widget that could benefit from it.

Note that toolbars created from a GnomeUIInfo template will have tooltips installed automatically.