Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions

  




 

 

Gtk+/Gnome Application Development
Prev Home Next

Online Help

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:

  • By writing documentation, and providing buttons and menu items that jump to relevant sections. For example, the "Help" button in a properties dialog should bring up a help window describing the dialog.

  • By adding "tooltips," explanatory text that appears if the mouse remains motionless over a widget for a short time. For menu items, explanatory text appears in the window's status bar as the user moves over the item.

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>

gchar* gnome_help_file_find_file(const gchar* app, const gchar* filename);

void gnome_help_goto(void* ignore, const gchar* url);

Figure 10. Help Files

Gtk+/Gnome Application Development
Prev Home Next

 
 
  Published under free license. Design by Interspire