gimphelpui

Name

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

Synopsis



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_set_help_data         (GtkWidget *widget,
                                             const gchar *tooltip,
                                             const gchar *help_data);
void        gimp_context_help               (void);

Description

Details

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.


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.


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).