Migrate GtkActionGroup API docs

1 files changed, 60 insertions, 0 deletions

diff --git a/gtk/gtkactiongroup.c b/gtk/gtkactiongroup.c
index 658a1cad76..4ed7e38204 100644
--- a/gtk/gtkactiongroup.c
+++ b/gtk/gtkactiongroup.c
@@ -28,6 +28,66 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkactiongroup
+ * @Short_description: A group of actions
+ * @Title: GtkActionGroup
+ *
+ * Actions are organised into groups. An action group is essentially a
+ * map from names to #GtkAction objects.
+ *
+ * All actions that would make sense to use in a particular context
+ * should be in a single group. Multiple action groups may be used for a
+ * particular user interface. In fact, it is expected that most nontrivial
+ * applications will make use of multiple groups. For example, in an
+ * application that can edit multiple documents, one group holding global
+ * actions (e.g. quit, about, new), and one group per document holding
+ * actions that act on that document (eg. save, cut/copy/paste, etc). Each
+ * window's menus would be constructed from a combination of two action
+ * groups.
+ * </para>
+ * <para id="Action-Accel">
+ * Accelerators are handled by the GTK+ accelerator map. All actions are
+ * assigned an accelerator path (which normally has the form
+ * <literal>&lt;Actions&gt;/group-name/action-name</literal>)
+ * and a shortcut is associated with this accelerator path. All menuitems
+ * and toolitems take on this accelerator path. The GTK+ accelerator map
+ * code makes sure that the correct shortcut is displayed next to the menu
+ * item.
+ *
+ * <refsect2 id="GtkActionGroup-BUILDER-UI">
+ * <title>GtkActionGroup as GtkBuildable</title>
+ * <para>
+ * The #GtkActionGroup implementation of the #GtkBuildable interface accepts
+ * #GtkAction objects as &lt;child&gt; elements in UI definitions.
+ *
+ * Note that it is probably more common to define actions and action groups
+ * in the code, since they are directly related to what the code can do.
+ *
+ * The GtkActionGroup implementation of the GtkBuildable interface supports
+ * a custom &lt;accelerator&gt; element, which has attributes named key and
+ * modifiers and allows to specify accelerators. This is similar to the
+ * &lt;accelerator&gt; element of #GtkWidget, the main difference is that
+ * it doesn't allow you to specify a signal.
+ * </para>
+ * <example>
+ * <title>A #GtkDialog UI definition fragment.</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkActionGroup" id="actiongroup">
+ *   <child>
+ *       <object class="GtkAction" id="About">
+ *           <property name="name">About</property>
+ *           <property name="stock_id">gtk-about</property>
+ *           <signal handler="about_activate" name="activate"/>
+ *       </object>
+ *       <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
+
 #include "config.h"
 #include <string.h>