help (HEAD)

help — User guide access

Functions

void	gwy_help_add_to_proc_dialog ()
void	gwy_help_add_to_graph_dialog ()
void	gwy_help_add_to_volume_dialog ()
void	gwy_help_add_to_xyz_dialog ()
void	gwy_help_add_to_cmap_dialog ()
void	gwy_help_add_to_file_dialog ()
void	gwy_help_add_to_tool_dialog ()
void	gwy_help_add_to_window ()
void	gwy_help_add_to_window_uri ()
void	gwy_help_show ()
gboolean	gwy_help_is_available ()

Types and Values

enum	GwyHelpFlags

Includes

#include <app/gwyapp.h>

Description

Help functions add a Help button to dialogs and install a key press handler responding to Help and F1 keys to all windows. For built-in modules, invoking the help opens a web browser (using some generic and system-specific means) pointing to the corresponding location in the user guide. Third-party modules can use gwy_help_add_to_window_uri() to open a web browser at an arbitrary URI.

Functions

gwy_help_add_to_proc_dialog ()

void
gwy_help_add_to_proc_dialog (GtkDialog *dialog,
                             GwyHelpFlags flags);

Adds help to a data processing function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a data processing function.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_graph_dialog ()

void
gwy_help_add_to_graph_dialog (GtkDialog *dialog,
                              GwyHelpFlags flags);

Adds help to a graph function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a graph function.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_volume_dialog ()

void
gwy_help_add_to_volume_dialog (GtkDialog *dialog,
                               GwyHelpFlags flags);

Adds help to a volume data processing function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a volume data processing function.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_xyz_dialog ()

void
gwy_help_add_to_xyz_dialog (GtkDialog *dialog,
                            GwyHelpFlags flags);

Adds help to a XYZ data processing function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a XYZ data processing function.
flags	Flags allowing to modify the help setup.

Since: 2.45

gwy_help_add_to_cmap_dialog ()

void
gwy_help_add_to_cmap_dialog (GtkDialog *dialog,
                             GwyHelpFlags flags);

Adds help to a curve map data processing function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a curve map data processing function.
flags	Flags allowing to modify the help setup.

Since: 2.60

gwy_help_add_to_file_dialog ()

void
gwy_help_add_to_file_dialog (GtkDialog *dialog,
                             GwyHelpFlags flags);

Adds help to a file function dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a file function.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_tool_dialog ()

void
gwy_help_add_to_tool_dialog (GtkDialog *dialog,
                             GwyTool *tool,
                             GwyHelpFlags flags);

Adds help to a tool dialog.

Note the help button will not be added if no help URI is found for the currently running function or help is not available.

Parameters

dialog	Main dialog for a tool function.
tool	The tool.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_window ()

void
gwy_help_add_to_window (GtkWindow *window,
                        const gchar *filename,
                        const gchar *fragment,
                        GwyHelpFlags flags);

Adds help to a window pointing to the user guide.

If the window is a GtkDialog a help button will be added by default (this can be modified with flags ). Normal windows do not get help buttons. No help may be added if help is not available.

This is a relatively low-level function and should not be necessary in modules. An exception may be modules with multiple user interfaces described in different parts of the guide – but this should be rare.

It is a suitable functions for adding help to base application windows, such as channel or volume windows.

Parameters

window	A window.
filename	Base file name in the user guide without any path or extensions, for instance "statistical-analysis".
fragment	Fragment identifier (without "#"), or possibly NULL.
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_add_to_window_uri ()

void
gwy_help_add_to_window_uri (GtkWindow *window,
                            const gchar *uri,
                            GwyHelpFlags flags);

Adds help to a window pointing to an arbitrary URI.

If the window is a GtkDialog a help button will be added by default (this can be modified with flags ). Normal windows do not get help buttons. No help may be added if help is not available.

This function should not be necessary anywhere within Gwyddion itself. Use the functions pointing to the user guide instead as they can handle language versions or changing the user guide base location.

It may be useful for third-party modules if they wish to add a help facility behaving similarly to built-in modules.

Parameters

window	A window.
uri	Full URI pointing to the help for window .
flags	Flags allowing to modify the help setup.

Since: 2.38

gwy_help_show ()

void
gwy_help_show (const gchar *filename,
               const gchar *fragment);

Immediately shows a specific help location.

This function should be rarely needed. It may fail if help is not available.

Parameters

filename	Base file name in the user guide without any path or extensions, for instance "statistical-analysis".
fragment	Fragment identifier (without "#"), or possibly NULL.

Since: 2.38

gwy_help_is_available ()

gboolean
gwy_help_is_available (void);

Check whether help is available.

This is a weak check that finds if we have any help-showing backend that might work at all, have the user guide module map, and if the user guide locations is a local directory it checks whether it exists. If it returns TRUE it does not guarantee help will work. If it returns FALSE, however, it means help will not work.

Returns

TRUE if help seems available, FALSE if it is not.

Since: 2.38

Types and Values

enum GwyHelpFlags

Flags controlling help setup and behaviour.

Members

GWY_HELP_DEFAULT	No flags, the default behaviour.
GWY_HELP_NO_BUTTON	Do not add a Help button, even to windows that are dialogs.

Since: 2.38