gnome-help

gnome-help — Display application and GNOME system help.

Synopsis


#include <libgnome/libgnome.h>

enum                GnomeHelpError;
#define             GNOME_HELP_ERROR
gboolean            gnome_help_display                  (const char *file_name,
                                                         const char *link_id,
                                                         GError **error);
gboolean            gnome_help_display_with_doc_id      (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         GError **error);
gboolean            gnome_help_display_with_doc_id_and_env
                                                        (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         char **envp,
                                                         GError **error);
gboolean            gnome_help_display_desktop          (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         GError **error);
gboolean            gnome_help_display_desktop_with_env (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         char **envp,
                                                         GError **error);
gboolean            gnome_help_display_uri              (const char *help_uri,
                                                         GError **error);
gboolean            gnome_help_display_uri_with_env     (const char *help_uri,
                                                         char **envp,
                                                         GError **error);

Description

These functions provide a way to display help files that are either installed as part of the main GNOME installation or that are specific to the current application.

Details

enum GnomeHelpError

typedef enum {
  GNOME_HELP_ERROR_INTERNAL,
  GNOME_HELP_ERROR_NOT_FOUND
} GnomeHelpError;

The different error codes which can be thrown in the GNOME_HELP_ERROR domain.

GNOME_HELP_ERROR_INTERNAL

 Something went wrong internally. This is most likely caused by a resource problem or bad installation.

GNOME_HELP_ERROR_NOT_FOUND

 Help file does not exist.

GNOME_HELP_ERROR

#define GNOME_HELP_ERROR (gnome_help_error_quark ())

The class (or domain) of errors raised directly by the gnome-help module. This is used as a value in the domain field of the GError structure.

gnome_help_display ()

gboolean            gnome_help_display                  (const char *file_name,
                                                         const char *link_id,
                                                         GError **error);

Displays the help file specified by file_name at location link_id in the preferred help browser of the user.

file_name :

 The name of the help document to display.

link_id :

 Can be NULL. If set, refers to an anchor or section id within the requested document.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

gnome_help_display_with_doc_id ()

gboolean            gnome_help_display_with_doc_id      (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         GError **error);

Displays the help file specified by file_name at location link_id within the doc_id domain in the preferred help browser of the user. Most of the time, you want to call gnome_help_display() instead.

This function will display the help through creating a "ghelp" URI, by looking for file_name in the applications installed help location (found by GNOME_FILE_DOMAIN_APP_HELP) and its app_id. The resulting URI is roughly in the form "ghelp:appid/file_name?link_id". If a matching file cannot be found, FALSE is returned and error is set.

Please note that this only displays application help. To display help files from the global GNOME domain, you will want to use gnome_help_display_desktop().

program :

 The current application object, or NULL for the default one.

doc_id :

 The document identifier, or NULL to default to the application ID (app_id) of the specified program.

file_name :

 The name of the help document to display.

link_id :

 Can be NULL. If set, refers to an anchor or section id within the requested document.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

gnome_help_display_with_doc_id_and_env ()

gboolean            gnome_help_display_with_doc_id_and_env
                                                        (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         char **envp,
                                                         GError **error);

Like gnome_display_with_doc_id(), but the the contents of envp will become the url viewer's environment rather than inheriting from the parents environment.

program :

 The current application object, or NULL for the default one.

doc_id :

 The document identifier, or NULL to default to empty string. (app_id) of the specified program.

file_name :

 The name of the help document to display.

link_id :

 Can be NULL. If set, refers to an anchor or section id within the requested document.

envp :

 child's environment, or NULL to inherit parent's.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

Since 2.2

gnome_help_display_desktop ()

gboolean            gnome_help_display_desktop          (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         GError **error);

Displays the GNOME system help file specified by file_name at location link_id in the preferred help browser of the user. This is done by creating a "ghelp" URI, by looking for file_name in the system help domain (GNOME_FILE_DOMAIN_HELP) and it's app_id. This domain is determined when the library is compiled. If a matching file cannot be found, FALSE is returned and error is set.

Please note that this only displays system help. To display help files for an application, you will want to use gnome_help_display().

program :

 The current application object, or NULL for the default one.

doc_id :

 The name of the help file relative to the system's help domain (GNOME_FILE_DOMAIN_HELP).

file_name :

 The name of the help document to display.

link_id :

 Can be NULL. If set, refers to an anchor or section id within the requested document.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

gnome_help_display_desktop_with_env ()

gboolean            gnome_help_display_desktop_with_env (GnomeProgram *program,
                                                         const char *doc_id,
                                                         const char *file_name,
                                                         const char *link_id,
                                                         char **envp,
                                                         GError **error);

Like gnome_help_display_desktop(), but the the contents of envp will become the url viewer's environment rather than inheriting from the parents environment.

program :

 The current application object, or NULL for the default one.

doc_id :

 The name of the help file relative to the system's help domain (GNOME_FILE_DOMAIN_HELP).

file_name :

 The name of the help document to display.

link_id :

 Can be NULL. If set, refers to an anchor or section id within the requested document.

envp :

 child's environment, or NULL to inherit parent's.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

Since 2.2

gnome_help_display_uri ()

gboolean            gnome_help_display_uri              (const char *help_uri,
                                                         GError **error);

Displays help_uri in the user's preferred viewer. You should never need to call this function directly in code, since it is just a wrapper for gnome_url_show() and consequently the viewer used to display the results depends upon the scheme of the URI (so it is not strictly a help-only function).

help_uri :

 The URI to display.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

gnome_help_display_uri_with_env ()

gboolean            gnome_help_display_uri_with_env     (const char *help_uri,
                                                         char **envp,
                                                         GError **error);

Like gnome_help_display_uri(), but the the contents of envp will become the help viewer's environment rather than inheriting from the parents environment.

help_uri :

 The URI to display.

envp :

 child's environment, or NULL to inherit parent's.

error :

 A GError instance that will hold the specifics of any error which occurs during processing, or NULL

Returns :

 TRUE on success, FALSE otherwise (in which case error will contain the actual error).

Since 2.2