Export gtk_widget_set_accel_path().

Tue Jan 29 22:31:07 2002  Owen Taylor  <otaylor@redhat.com>

        * gtk/gtkwidget.[ch] gtkmenuitem.c gtkitemfactory.c: Export
        gtk_widget_set_accel_path().

        * gtk/gtk.def: Add gtk_widget_set_accel_path.

5 files changed, 42 insertions, 17 deletions

diff --git a/gtk/gtk.def b/gtk/gtk.def
index 0989149d3a..455289b065 100755
--- a/gtk/gtk.def
+++ b/gtk/gtk.def
@@ -2047,6 +2047,7 @@ EXPORTS
 	gtk_widget_ref
 	gtk_widget_region_intersect
 	gtk_widget_remove_accelerator
+        gtk_widget_set_accel_path
 	gtk_widget_render_icon
 	gtk_widget_reparent
 	gtk_widget_reset_rc_styles
diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c
index d47715371e..732c514561 100644
--- a/gtk/gtkitemfactory.c
+++ b/gtk/gtkitemfactory.c
@@ -326,7 +326,7 @@ gtk_item_factory_add_foreign (GtkWidget      *accel_widget,
       if (accel_group)
 	{
 	  gtk_accel_map_add_entry (full_path, keyval, modifiers);
-	  _gtk_widget_set_accel_path (accel_widget, full_path, accel_group);
+	  gtk_widget_set_accel_path (accel_widget, full_path, accel_group);
 	}
     }
 }
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 85369a24fc..083358e989 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -1054,7 +1054,7 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
 
   if (!accel_group)
     {
-      _gtk_widget_set_accel_path (widget, NULL, NULL);
+      gtk_widget_set_accel_path (widget, NULL, NULL);
       return;
     }
 
@@ -1074,10 +1074,10 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
 	  path = menu_item->accel_path;
 	}
       if (path)
-	_gtk_widget_set_accel_path (widget, path, accel_group);
+	gtk_widget_set_accel_path (widget, path, accel_group);
     }
   else if (group_changed)			/* reinstall accelerators */
-    _gtk_widget_set_accel_path (widget, path, accel_group);
+    gtk_widget_set_accel_path (widget, path, accel_group);
 }
 
 /**
@@ -1092,6 +1092,10 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
  * gtk_accel_map_add_entry() with the same @accel_path.
  * See also gtk_accel_map_add_entry() on the specifics of accelerator paths,
  * and gtk_menu_set_accel_path() for a more convenient variant of this function.
+ *
+ * This function is basically a convenience wrapper that handles calling
+ * gtk_widget_set_accel_path() with the appropriate accelerator group for
+ * the menu item.
  */
 void
 gtk_menu_item_set_accel_path (GtkMenuItem *menu_item,
@@ -1109,7 +1113,7 @@ gtk_menu_item_set_accel_path (GtkMenuItem *menu_item,
   menu_item->accel_path = g_strdup (accel_path);
 
   /* forget accelerators associated with old path */
-  _gtk_widget_set_accel_path (widget, NULL, NULL);
+  gtk_widget_set_accel_path (widget, NULL, NULL);
 
   /* install accelerators associated with new path */
   if (widget->parent)
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index aa664e6350..755ae1b25a 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -2593,14 +2593,14 @@ widget_new_accel_closure (GtkWidget *widget,
  * @accel_mods:   modifier key combination of the accelerator
  * @accel_flags:  flag accelerators, e.g. %GTK_ACCEL_VISIBLE
  *
- * Installs an accelerator for this @widget in @accel_group, that causes
+ * Installs an accelerator for this @widget in @accel_group that causes
  * @accel_signal to be emitted if the accelerator is activated.
  * The @accel_group needs to be added to the widget's toplevel via
  * gtk_window_add_accel_group(), and the signal must be of type %G_RUN_ACTION.
  * Accelerators added through this function are not user changeable during
  * runtime. If you want to support accelerators that can be changed by the
- * user, use gtk_accel_map_add_entry() and gtk_menu_item_set_accel_path()
- * instead.
+ * user, use gtk_accel_map_add_entry() and gtk_widget_set_accel_path() or
+ * gtk_menu_item_set_accel_path() instead.
  */
 void
 gtk_widget_add_accelerator (GtkWidget      *widget,
@@ -2743,15 +2743,35 @@ destroy_accel_path (gpointer data)
   g_free (apath);
 }
 
-/* accel_group: the accel group used to activate this widget
- * accel_path:  the accel path, associating the accelerator
- *              to activate this widget
- * set accel path through which this widget can be actiavated.
- */
+
+/**
+ * gtk_widget_set_accel_path:
+ * @widget: a #GtkWidget
+ * @accel_path: path used to look up the the accelerator
+ * @accel_group: a #GtkAccelGroup.
+ * 
+ * Given an accelerator group, @accel_group, and an accelerator path,
+ * @accel_path, sets up an accelerator in @accel_group so whenever the
+ * key binding that is defined for @accel_path is pressed, @widget
+ * will be activated.  This removes any accelerators (for any
+ * accelerator group) installed by previous calls to
+ * gtk_widget_set_accel_path(). Associating accelerators with
+ * paths allows them to be modified by the user and the modifications
+ * to be saved for future use. (See gtk_accel_map_save().)
+ *
+ * This function is a low level function that would most likely
+ * be used by a menu creation system like #GtkItemFactory. If you
+ * use #GtkItemFactory, setting up accelerator paths will be done
+ * automatically.
+ *
+ * Even when you you aren't using #GtkItemFactory, if you only want to
+ * set up accelerators on menu items gtk_menu_item_set_accel_path()
+ * provides a somewhat more convenient interface.
+ **/
 void
-_gtk_widget_set_accel_path (GtkWidget     *widget,
-			    const gchar   *accel_path,
-			    GtkAccelGroup *accel_group)
+gtk_widget_set_accel_path (GtkWidget     *widget,
+			   const gchar   *accel_path,
+			   GtkAccelGroup *accel_group)
 {
   AccelPath *apath;
 
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index cc449f2923..d70a0ef676 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -488,7 +488,7 @@ gboolean   gtk_widget_remove_accelerator  (GtkWidget           *widget,
 					   GtkAccelGroup       *accel_group,
 					   guint                accel_key,
 					   GdkModifierType      accel_mods);
-void         _gtk_widget_set_accel_path   (GtkWidget           *widget,
+void       gtk_widget_set_accel_path      (GtkWidget           *widget,
 					   const gchar         *accel_path,
 					   GtkAccelGroup       *accel_group);
 const gchar* _gtk_widget_get_accel_path   (GtkWidget           *widget);