[gtk+] document GtkActionable

[Ryan Lortie <ryanl src gnome org>]

commit 7fdf2e0bde1786b99082e64184476f28169206fd
Author: Ryan Lortie <desrt desrt ca>
Date:   Wed Jan 11 12:56:35 2012 +0100

    document GtkActionable
    
    This should have been done before it was merged...

 docs/reference/gtk/gtk-docs.sgml     |    1 +
 docs/reference/gtk/gtk3-sections.txt |   26 ++++++
 docs/reference/gtk/gtk3.types        |    1 +
 gtk/gtkactionable.c                  |  144 ++++++++++++++++++++++++++++++++++
 4 files changed, 172 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 9be29d7..06b94b6 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -339,6 +339,7 @@
       <title>Application support</title>
       <xi:include href="xml/gtkapplication.xml" />
       <xi:include href="xml/gtkapplicationwindow.xml" />
+      <xi:include href="xml/gtkactionable.xml" />
     </chapter>
   </part>
 
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 4aa6181..6f04025 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -7058,6 +7058,32 @@ GtkApplicationWindowPrivate
 </SECTION>
 
 <SECTION>
+<FILE>gtkactionable</FILE>
+<TITLE>GtkActionable</TITLE>
+GtkActionable
+GtkActionableInterface
+
+<SUBSECTION>
+gtk_actionable_get_action_name
+gtk_actionable_set_action_name
+
+<SUBSECTION>
+gtk_actionable_get_action_target_value
+gtk_actionable_set_action_target_value
+gtk_actionable_set_action_target
+
+<SUBSECTION>
+gtk_actionable_set_detailed_action_name
+
+<SUBSECTION Standard>
+gtk_actionable_get_type
+GTK_ACTIONABLE
+GTK_ACTIONABLE_GET_IFACE
+GTK_IS_ACTIONABLE
+GTK_TYPE_ACTIONABLE
+</SECTION>
+
+<SECTION>
 <FILE>gtkgrid</FILE>
 <TITLE>GtkGrid</TITLE>
 GtkGrid
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types
index 4a035af..7fe92ad 100644
--- a/docs/reference/gtk/gtk3.types
+++ b/docs/reference/gtk/gtk3.types
@@ -6,6 +6,7 @@ gtk_accel_group_get_type
 gtk_accel_label_get_type
 gtk_accel_map_get_type
 gtk_accessible_get_type
+gtk_actionable_get_type
 gtk_action_get_type
 gtk_action_group_get_type
 gtk_activatable_get_type
diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c
index f78474e..f49cd70 100644
--- a/gtk/gtkactionable.c
+++ b/gtk/gtkactionable.c
@@ -26,6 +26,43 @@
 #include "gtkwidget.h"
 #include "gtkintl.h"
 
+/**
+ * SECTION:gtkactionable
+ * @title: GtkActionable
+ * @short_description: an interface for widgets that can be associated
+ *                     with actions
+ *
+ * This interface provides a convenient way of associating widgets with
+ * actions on a #GtkApplicationWindow or #GtkApplication.
+ *
+ * It primarily consists of two properties: "action-name" and
+ * "action-target".  There are also some convenience APIs for setting
+ * these properties.
+ *
+ * This interface is presently only meaningful if used on a widget that
+ * is (or will be) located inside of a #GtkApplicationWindow and can
+ * only be used to associate the widget with actions on that window, or
+ * its associated #GtkApplication.
+ *
+ * Since: 3.4
+ **/
+
+/**
+ * GtkActionable:
+ *
+ * An opaque pointer type.
+ **/
+
+/**
+ * GtkActionableInterface:
+ * @get_action_name: virtual pointer for gtk_actionable_get_action_name
+ * @set_action_name: virtual pointer for gtk_actionable_set_action_name
+ * @get_action_target_value: virtual pointer for gtk_actionable_get_action_target_value
+ * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value
+ *
+ * The interface vtable for #GtkActionable.
+ **/
+
 G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET)
 
 static void
@@ -42,6 +79,18 @@ gtk_actionable_default_init (GtkActionableInterface *iface)
                           G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
 
+/**
+ * gtk_actionable_get_action_name:
+ * @actionable: a #GtkActionable widget
+ *
+ * Gets the action name for @actionable.
+ *
+ * See gtk_actionable_set_action_name() for more information.
+ *
+ * Returns: the action name, or %NULL if none is set
+ *
+ * Since: 3.4
+ **/
 const gchar *
 gtk_actionable_get_action_name (GtkActionable *actionable)
 {
@@ -51,6 +100,25 @@ gtk_actionable_get_action_name (GtkActionable *actionable)
     ->get_action_name (actionable);
 }
 
+/**
+ * gtk_actionable_set_action_name:
+ * @actionable: a #GtkActionable widget
+ * @action_name: an action name, or %NULL
+ *
+ * Specifies the name of the action with which this widget should be
+ * associated.  If @action_name is %NULL then the widget will be
+ * unassociated from any previous action.
+ *
+ * Usually this function is used when the widget is located (or will be
+ * located) within the hierarchy of a #GtkApplicationWindow.
+ *
+ * Names are of the form "win.save" or "app.quit" for actions on the
+ * containing #GtkApplicationWindow or its associated #GtkApplication,
+ * respectively.  This is the same form used for actions in the #GMenu
+ * associated with the window.
+ *
+ * Since: 3.4
+ **/
 void
 gtk_actionable_set_action_name (GtkActionable *actionable,
                                 const gchar   *action_name)
@@ -61,6 +129,18 @@ gtk_actionable_set_action_name (GtkActionable *actionable,
     ->set_action_name (actionable, action_name);
 }
 
+/**
+ * gtk_actionable_get_action_target_value:
+ * @actionable: a #GtkActionable widget
+ *
+ * Gets the current target value of @actionabe.
+ *
+ * See gtk_actionable_set_target_value() for more information.
+ *
+ * Returns: (transfer none): the current target value
+ *
+ * Since: 3.4
+ **/
 GVariant *
 gtk_actionable_get_action_target_value (GtkActionable *actionable)
 {
@@ -70,6 +150,33 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
     ->get_action_target_value (actionable);
 }
 
+/**
+ * gtk_actionable_set_action_target_value:
+ * @actionable: a #GtkActionable widget
+ * @target_value: a #GVariant to set as the target value, or %NULL
+ *
+ * Sets the target value of an actionable widget.
+ *
+ * If @target_value is %NULL then the target value is unset.
+ *
+ * The target value has two purposes.  First, it is used as the
+ * parameter to activation of the action associated with the
+ * #GtkActionable widget.  Second, it is used to determine if the widget
+ * should be rendered as "active" -- the widget is active if the state
+ * is equal to the given target.
+ *
+ * Consider the example of associating a set of buttons with a #GAction
+ * with string state in a typical "radio button" situation.  Each button
+ * will be associated with the same action, but with a different target
+ * value for that action.  Clicking on a particular button will activate
+ * the action with the target of that button, which will typically cause
+ * the action's state to change to that value.  Since the action's state
+ * is now equal to the target value of the button, the button will now
+ * be rendered as active (and the other buttons, with different targets,
+ * rendered inactive).
+ *
+ * Since: 3.4
+ **/
 void
 gtk_actionable_set_action_target_value (GtkActionable *actionable,
                                         GVariant      *target_value)
@@ -80,6 +187,24 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable,
     ->set_action_target_value (actionable, target_value);
 }
 
+/**
+ * gtk_actionable_set_action_target:
+ * @actionable: a #GtkActionable widget
+ * @format_string: a GVariant format string
+ * @...: arguments appropriate for @format_string
+ *
+ * Sets the target of an actionable widget.
+ *
+ * This is a convenience function that calls g_variant_new() for
+ * @format_string and uses the result to call
+ * gtk_actionable_set_action_target_value().
+ *
+ * If you are setting a string-valued target and want to set the action
+ * name at the same time, you can use
+ * gtk_actionable_set_detailed_action_name ().
+ *
+ * Since: 3.4
+ **/
 void
 gtk_actionable_set_action_target (GtkActionable *actionable,
                                   const gchar   *format_string,
@@ -92,6 +217,25 @@ gtk_actionable_set_action_target (GtkActionable *actionable,
   va_end (ap);
 }
 
+/**
+ * gtk_actionable_set_detailed_action_name:
+ * @actionable: a #GtkActionable widget
+ * @detailed_action_name: the detailed action name
+ *
+ * Sets the action-name and associated string target value of an
+ * actionable widget.
+ *
+ * This allows for the effect of both gtk_actionable_set_action_name()
+ * and gtk_actionable_set_target() in the common case that the target is
+ * string-valued.
+ *
+ * @detailed_action_name is a string of the form
+ * <literal>"action::target"</literal> where <literal>action</literal>
+ * is the action name and <literal>target</literal> is the string to use
+ * as the target.
+ *
+ * Since: 3.4
+ **/
 void
 gtk_actionable_set_detailed_action_name (GtkActionable *actionable,
                                          const gchar   *detailed_action_name)