added documentation.

2000-02-27  Michael Natterer  <mitch@gimp.org>

	* libgimp/gimphelpui.c: added documentation.

2000-02-27  Michael Natterer  <mitch@gimp.org>

	* libgimp/tmpl/gimphelpui.sgml: updated.

ChangeLog

@@ -1,3 +1,7 @@
+2000-02-27  Michael Natterer  <mitch@gimp.org>
+
+	* libgimp/gimphelpui.c: added documentation.
+
 Sun Feb 27 13:07:31 CET 2000  Sven Neumann <sven@gimp.org>
 
 	* app/gimpimage.c

devel-docs/ChangeLog

@@ -1,3 +1,7 @@
+2000-02-27  Michael Natterer  <mitch@gimp.org>
+
+	* libgimp/tmpl/gimphelpui.sgml: updated.
+
 2000-02-26  Michael Natterer  <mitch@gimp.org>
 
 	* libgimp/libgimp-decl.txt

devel-docs/libgimp/tmpl/gimphelpui.sgml

@@ -17,10 +17,32 @@ system.
 
 <!-- ##### USER_FUNCTION GimpHelpFunc ##### -->
 <para>
-
+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.
 </para>
 
-@help_data: 
+<para>
+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".
+</para>
+
+<para>
+All these functions finally call gimp_help_connect_help_accel() which
+does the work of installing the "F1" accelerator.
+</para>
+
+<para>
+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.
+</para>
+
+@help_data: A string containing the path to a HTML page.
 
 
 <!-- ##### FUNCTION gimp_help_init ##### -->
@@ -53,10 +75,22 @@ system.
 
 <!-- ##### FUNCTION gimp_standard_help_func ##### -->
 <para>
-
+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.
 </para>
 
-@help_data: 
+<para>
+Currently, gimp_standard_help_func() and gimp_plugin_help_func() do
+exactly the same. The latter one was introduced to ensure future
+flexibility.
+</para>
+
+<para>
+See #GimpHelpFunc for the naming conventions of HTML help files.
+</para>
+
+@help_data: A string containing the path to a HTML page.
 
 
 <!-- ##### FUNCTION gimp_help_connect_help_accel ##### -->
@@ -77,8 +111,6 @@ system.
 @widget: 
 @tooltip: 
 @help_data: 
-<!-- # Unused Parameters # -->
-@tool_tip: 
 
 
 <!-- ##### FUNCTION gimp_context_help ##### -->

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,
@@ -224,6 +251,15 @@ gimp_help_set_help_data (GtkWidget   *widget,
  *
  * 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
 gimp_context_help (void)

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,
@@ -224,6 +251,15 @@ gimp_help_set_help_data (GtkWidget   *widget,
  *
  * 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
 gimp_context_help (void)