Finished applications should provide online help and
documentation. Of course, the first "line of defense" is to
have an intuitive interface in the first place. But you
should give users a way to get more information if they
need it.
This section describes the two major ways you can explain
your interface to users:
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.
