diff --git a/ChangeLog b/ChangeLog index 043b1dcb77..ffe53c3475 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2000-02-27 Michael Natterer + + * libgimp/gimphelpui.c: added documentation. + Sun Feb 27 13:07:31 CET 2000 Sven Neumann * app/gimpimage.c diff --git a/devel-docs/ChangeLog b/devel-docs/ChangeLog index 83cf8d8f44..ca4f580577 100644 --- a/devel-docs/ChangeLog +++ b/devel-docs/ChangeLog @@ -1,3 +1,7 @@ +2000-02-27 Michael Natterer + + * libgimp/tmpl/gimphelpui.sgml: updated. + 2000-02-26 Michael Natterer * libgimp/libgimp-decl.txt diff --git a/devel-docs/libgimp/tmpl/gimphelpui.sgml b/devel-docs/libgimp/tmpl/gimphelpui.sgml index 98c65a8484..51a4b102b5 100644 --- a/devel-docs/libgimp/tmpl/gimphelpui.sgml +++ b/devel-docs/libgimp/tmpl/gimphelpui.sgml @@ -17,10 +17,32 @@ system. - +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. -@help_data: + +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. @@ -53,10 +75,22 @@ system. - +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. -@help_data: + +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. @@ -77,8 +111,6 @@ system. @widget: @tooltip: @help_data: - -@tool_tip: diff --git a/libgimp/gimphelpui.c b/libgimp/gimphelpui.c index 8400553ecc..88886691e0 100644 --- a/libgimp/gimphelpui.c +++ b/libgimp/gimphelpui.c @@ -68,7 +68,7 @@ gimp_help_init (void) /** * gimp_help_free: * - * This function frees the menory used by the #GtkTooltips created by + * This function frees the memory used by the #GtkTooltips created by * gimp_help_init(). * */ @@ -110,6 +110,14 @@ gimp_help_disable_tooltips (void) * @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. * + * 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. + * */ void gimp_help_connect_help_accel (GtkWidget *widget, @@ -204,6 +212,25 @@ gimp_help_connect_help_accel (GtkWidget *widget, * @tooltip: The text for this widget's tooltip. * @help_data: The @help_data for the #GtkTipsQuery tooltips inspector. * + * 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. + * */ void gimp_help_set_help_data (GtkWidget *widget, @@ -223,6 +250,15 @@ gimp_help_set_help_data (GtkWidget *widget, * gimp_context_help: * * 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). * */ void diff --git a/libgimpwidgets/gimphelpui.c b/libgimpwidgets/gimphelpui.c index 8400553ecc..88886691e0 100644 --- a/libgimpwidgets/gimphelpui.c +++ b/libgimpwidgets/gimphelpui.c @@ -68,7 +68,7 @@ gimp_help_init (void) /** * gimp_help_free: * - * This function frees the menory used by the #GtkTooltips created by + * This function frees the memory used by the #GtkTooltips created by * gimp_help_init(). * */ @@ -110,6 +110,14 @@ gimp_help_disable_tooltips (void) * @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. * + * 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. + * */ void gimp_help_connect_help_accel (GtkWidget *widget, @@ -204,6 +212,25 @@ gimp_help_connect_help_accel (GtkWidget *widget, * @tooltip: The text for this widget's tooltip. * @help_data: The @help_data for the #GtkTipsQuery tooltips inspector. * + * 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. + * */ void gimp_help_set_help_data (GtkWidget *widget, @@ -223,6 +250,15 @@ gimp_help_set_help_data (GtkWidget *widget, * gimp_context_help: * * 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). * */ void