help: Gwyddion Application Library Reference Manual

## help 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