GIMP Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gimphelpui

## Name

gimphelpui -- Functions for setting GtkTooltips and HTML links into the GIMP help system.

## Synopsis

    void        (*GimpHelpFunc)                 (const gchar *help_data);
    void        gimp_help_init                  (void);
    void        gimp_help_free                  (void);
    void        gimp_help_enable_tooltips       (void);
    void        gimp_help_disable_tooltips      (void);
    void        gimp_standard_help_func         (const gchar *help_data);
    void        gimp_help_connect_help_accel    (GtkWidget *widget,
                                                 GimpHelpFunc help_func,
                                                 const gchar *help_data);
    void        gimp_help_set_help_data         (GtkWidget *widget,
                                                 const gchar *tooltip,
                                                 const gchar *help_data);
    void        gimp_context_help               (void);

## Description

## Details

### GimpHelpFunc ()

    void        (*GimpHelpFunc)                 (const gchar *help_data);

This is the prototype for all functions you pass as `help_func` to the various GIMP dialog constructors like gimp_dialog_new(), gimp_query_int_box() etc.

Note that all help paths are relative to the root of the help system in the current language. So if your language is "C", a help path of "filters/foo_bar.html" will expand to "${gimp_data_dir}/help/C/filters/foo_bar.html".

All these functions finally call gimp_help_connect_help_accel() which does the work of installing the "F1" accelerator.

In most cases it will be ok to use gimp_plugin_help_func() which does nothing but passing the `help_data` string to gimp_help(). If your plug-in needs some more sophisticated help handling you can provide your own `help_func` which has to call gimp_help() to actually display the help.

`help_data` : | A string containing the path to a HTML page.

### gimp_help_init ()

    void        gimp_help_init                  (void);

This function initializes GIMP's help system.

Currently it only creates a GtkTooltips object with gtk_tooltips_new() which will be used by gimp_help_set_help_data().

### gimp_help_free ()

    void        gimp_help_free                  (void);

This function frees the memory used by the GtkTooltips created by gimp_help_init().

### gimp_help_enable_tooltips ()

    void        gimp_help_enable_tooltips       (void);

This function calls gtk_tooltips_enable().

### gimp_help_disable_tooltips ()

    void        gimp_help_disable_tooltips      (void);

This function calls gtk_tooltips_disable().

### gimp_standard_help_func ()

    void        gimp_standard_help_func         (const gchar *help_data);

This is the standard GIMP help function which does nothing but calling gimp_help(). Please use gimp_plugin_help_func() for your plug-in's help links.

Currently, gimp_standard_help_func() and gimp_plugin_help_func() do exactly the same. The latter one was introduced to ensure future flexibility.

See GimpHelpFunc for the naming conventions of HTML help files.

`help_data` : | A string containing the path to a HTML page.

### gimp_help_connect_help_accel ()

    void        gimp_help_connect_help_accel    (GtkWidget *widget,
                                                 GimpHelpFunc help_func,
                                                 const gchar *help_data);

Note that this function is automatically called by all libgimp dialog constructors. You only have to call it for windows/dialogs you created "manually".

For convenience, gimp_help_connect_help_accel() calls gimp_dialog_set_icon() if the passed widget is a GtkWindow, so you don't have to worry about this.

`widget` : | The widget you want to connect the help accelerator for. Will be a GtkWindow in most cases.
`help_func` : | The function which will be called if the user presses "F1".
`help_data` : | The data pointer which will be passed to `help_func`.

### gimp_help_set_help_data ()

    void        gimp_help_set_help_data         (GtkWidget *widget,
                                                 const gchar *tooltip,
                                                 const gchar *help_data);

The reason why we don't use gtk_tooltips_set_tip() is that it's impossible to set a `private_tip` (aka `help_data`) without a visible `tooltip`.

This function can be called with `tooltip` == NULL. Use this feature if you want to set a HTML help link for a widget which shouldn't have a visible tooltip.

You can e.g. set a `help_data` string to a complete HTML page for a container widget (e.g. a GtkBox). For the widgets inside the box you can set HTML anchors which point inside the container widget's help page by setting `help_data` strings starting with "#".

If the tooltips inspector (Shift + "F1") is invoked and the user clicks on one of the widgets which only contain a "#" link, the help system will automatically ascend the widget hierarchy until it finds another widget with `help_data` attached and concatenates both to a complete help path.

`widget` : | The GtkWidget you want to set a `tooltip` and/or `help_data` for.
`tooltip` : | The text for this widget's tooltip.
`help_data` : | The `help_data` for the GtkTipsQuery tooltips inspector.

### gimp_context_help ()

    void        gimp_context_help               (void);

This function invokes the GtkTipsQuery tooltips inspector.

The mouse cursor will turn turn into a question mark and the user can click on any widget of the application which started the inspector.

If the widget the user clicked on has a `help_data` string attached (see gimp_help_set_help_data()), the corresponding HTML page will be displayed. Otherwise the help system will ascend the widget hierarchy until it finds an attached `help_data` string (which should be the case at least for every window/dialog).

<<< Previous Page | Home | Up | Next Page >>>
gimpexport | gimpmenu