gnome-help

Name

gnome-help -- Routines for displaying help

Synopsis


#include <gnome.h>


struct      GnomeHelpMenuEntry;
gchar*      gnome_help_file_find_file       (gchar *app,
                                             gchar *path);
gchar*      gnome_help_file_path            (gchar *app,
                                             gchar *path);
void        gnome_help_display              (void *ignore,
                                             GnomeHelpMenuEntry *ref);
void        gnome_help_goto                 (void *ignore,
                                             gchar *file);
void        gnome_help_pbox_display         (void *ignore,
                                             gint page_num,
                                             GnomeHelpMenuEntry *ref);
void        gnome_help_pbox_goto            (void *ignore,
                                             int ignore2,
                                             GnomeHelpMenuEntry *ref);

Description

These routines provide simple wrappers for invoking the help system in GNOME. They will take care of invoking the help browser with the help file you provide.

Details

struct GnomeHelpMenuEntry

typedef struct {
    gchar *name;
    gchar *path;
} GnomeHelpMenuEntry;

This structure describes where to get the help from. The name field is used to specify the name of the application (this is used to pull the help files from the help directory where the files were installed). The path parameter is the name relative to the package's help directory.

For example, the Gnumeric spreadsheet uses the structure like this:

static GnomeHelpMenuEntry help_ref = { "gnumeric", "formatting.html" };

This identifies the application and the filename that is displayed


gnome_help_file_find_file ()

gchar*      gnome_help_file_find_file       (gchar *app,
                                             gchar *path);

app : Name of this application
path : File that contains the help document
Returns :a fully resolved file name for path. Use needs to g_free the path when done. It looks in LANG, then unser C if LANG is not set I added this because I didnt want to break all apps using gnome_help_file_path() currently. We need a good solution (if this isnt it) to handle case where locale file didnt exist


gnome_help_file_path ()

gchar*      gnome_help_file_path            (gchar *app,
                                             gchar *path);

app : Name of this application
path : File that contains the help document
Returns :a fully resolved file name for path. Use needs to g_free the path when done. It looks in LANG, then unser C if LANG is not set


gnome_help_display ()

void        gnome_help_display              (void *ignore,
                                             GnomeHelpMenuEntry *ref);

Cause a help viewer to display help entry defined in ref.

ignore : value of this is ignored. To simplify hooking into clicked signals
ref : A GnomeHelpMenuEntry.


gnome_help_goto ()

void        gnome_help_goto                 (void *ignore,
                                             gchar *file);

Cause a help viewer to display file.

ignore : ignored.
file : file to display in the help browser.


gnome_help_pbox_display ()

void        gnome_help_pbox_display         (void *ignore,
                                             gint page_num,
                                             GnomeHelpMenuEntry *ref);

Cause a help viewer to display the help entry defined in ref. This function is meant to be connected to the "help" signal of a GnomePropertyBox. If ref is { "my-app", "properties-blah" }, and the current page number is 3, then the help viewer will display my-app/lang/properties-blah-3.html, which can be symlinked to the appropriate file.

ignore : ignored.
page_num : The number of the current notebook page in the properties box.
ref : A GnomeHelpMenuEntry


gnome_help_pbox_goto ()

void        gnome_help_pbox_goto            (void *ignore,
                                             int ignore2,
                                             GnomeHelpMenuEntry *ref);

Cause a help viewer to display the help entry defined in ref. This function is meant to be connected to the help button of a GnomePropertyBox, when you don't want any munging of the help path done. Most of the time, you can use gnome_help_pbox_display, though.

ignore : ignored.
ignore2 : also ignored.
ref : A GnomeHelpMenuEntry