[gtk/widget-class-actions] Add docs

[Matthias Clasen <matthiasc src gnome org>]

commit e59450d7d5713047d1dbe825c948cefff729ce8e
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Jun 14 14:32:08 2019 -0400

    Add docs
    
    Split action-related GtkWidget apis into their own
    subsection, and add the class action api to it.

 docs/reference/gtk/gtk4-sections.txt | 19 +++++++---
 gtk/gtkwidget.c                      | 70 ++++++++++++++++++++++++++++++++----
 gtk/gtkwidget.h                      | 48 +++++++++++++++++++++++++
 3 files changed, 126 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 4d072641da..8d27a99c27 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -4549,11 +4549,6 @@ gtk_widget_get_opacity
 gtk_widget_set_opacity
 gtk_widget_get_overflow
 gtk_widget_set_overflow
-gtk_widget_insert_action_group
-gtk_widget_list_action_prefixes
-gtk_widget_get_action_group
-gtk_widget_activate_action
-gtk_widget_activate_default
 gtk_widget_measure
 gtk_widget_snapshot_child
 gtk_widget_get_next_sibling
@@ -4630,6 +4625,20 @@ gtk_widget_class_set_connect_func
 gtk_widget_observe_children
 gtk_widget_observe_controllers
 
+<SUBSECTION Actions>
+gtk_widget_insert_action_group
+gtk_widget_list_action_prefixes
+gtk_widget_get_action_group
+gtk_widget_activate_action
+gtk_widget_activate_default
+GtkWidgetActionActivate
+GtkWidgetActionQuery
+GtkWidgetActionChange
+gtk_widget_class_install_action
+gtk_widget_add_class_actions
+gtk_widget_notify_class_action_enabled
+gtk_widget_notify_class_action_state
+
 <SUBSECTION Standard>
 GTK_WIDGET
 GTK_IS_WIDGET
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d94da05d88..b694282fb9 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -13481,12 +13481,30 @@ gtk_widget_should_layout (GtkWidget *widget)
   return TRUE;
 }
 
+/**
+ * gtk_widget_class_install_action:
+ * @widget_class: a #GtkWidgetClass
+ * @prefixed_name: a prefixed action name, such as "clipboard.paste"
+ * @activate: callback to use when the action is activated
+ * @query: callback to use when the action properties are queried
+ * @change: (allow-none): callback to use when the action state is
+ *     changed, or %NULL for stateless actions
+ *
+ * This should be called at class initialization time to specify
+ * actions to be added for all instances of this class.
+ *
+ * Actions installed in this way can be simple or stateful.
+ * See the #GAction documentation for more information.
+ *
+ * Note that any class that installs actions must call
+ * gtk_widget_add_class_actions() in the widget’s instance initializer.
+ */
 void
-gtk_widget_class_install_action (GtkWidgetClass             *widget_class,
-                                 const char                 *prefixed_name,
-                                 GtkWidgetActionActivate     activate,
-                                 GtkWidgetActionQuery        query,
-                                 GtkWidgetActionChange       change)
+gtk_widget_class_install_action (GtkWidgetClass          *widget_class,
+                                 const char              *prefixed_name,
+                                 GtkWidgetActionActivate  activate,
+                                 GtkWidgetActionQuery     query,
+                                 GtkWidgetActionChange    change)
 {
   GtkWidgetClassPrivate *priv = widget_class->priv;
   GtkWidgetAction *action;
@@ -13538,6 +13556,16 @@ gtk_widget_class_install_action (GtkWidgetClass             *widget_class,
   g_ptr_array_add (priv->actions, action);
 }
 
+/**
+ * gtk_widget_add_class_actions:
+ * @widget: a #GtkWidget
+ *
+ * Creates and adds any actions that are associated with the widget's class.
+ *
+ * This function must be called in the instance initializer for any
+ * class which installs actions with gtk_widget_class_install_action()
+ * at class initialization time.
+ */
 void
 gtk_widget_add_class_actions (GtkWidget *widget)
 {
@@ -13575,8 +13603,23 @@ gtk_widget_add_class_actions (GtkWidget *widget)
   g_hash_table_unref (prefixes);
 }
 
+/**
+ * gtk_widget_notify_class_action_enabled:
+ * @widget: a #GtkWidget
+ * @prefixed_name: a prefixed action name, such as "clipboard.paste"
+ *
+ * Convenience API to notify when an action installed
+ * with gtk_widget_class_install_action() changes its
+ * enabled state. It must be called after the change
+ * has taken place (we expect the @query callback to
+ * already return the new state).
+ *
+ * This function is a more convenient alternative
+ * to calling g_action_group_action_enabled_changed()
+ * directly.
+ */
 void
-gtk_widget_notify_class_action_enabled (GtkWidget *widget,
+gtk_widget_notify_class_action_enabled (GtkWidget  *widget,
                                         const char *prefixed_name)
 {
   GtkActionMuxer *muxer;
@@ -13595,6 +13638,21 @@ gtk_widget_notify_class_action_enabled (GtkWidget *widget,
   g_action_group_action_enabled_changed (group, name, enabled);
 }
 
+/**
+ * gtk_widget_notify_class_action_state:
+ * @widget: a #GtkWidget
+ * @prefixed_name: a prefixed action name, such as "clipboard.paste"
+ *
+ * Convenience API to notify when an action installed
+ * with gtk_widget_class_install_action() changes its
+ * state. It must be called after the change has taken
+ * place (we expect the @query callback to already
+ * return the new state).
+ *
+ * This function is a more convenient alternative
+ * to calling g_action_group_action_state_changed()
+ * directly.
+ */
 void
 gtk_widget_notify_class_action_state (GtkWidget  *widget,
                                       const char *prefixed_name)
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index d5703003d2..add11a318e 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -1030,9 +1030,38 @@ GDK_AVAILABLE_IN_ALL
 gboolean                gtk_widget_should_layout        (GtkWidget   *widget);
 
 
+/**
+ * GtkWidgetActionActivate:
+ * @widget: the widget to which the action belongs
+ * @action_name: the (unprefixed) action name
+ * @parameter: parameter for activation
+ *
+ * The type of the callback functions used for activating
+ * actions installed with gtk_widget_class_install_action().
+ *
+ * The @parameter must match the @parameter_type of the action.
+ */
 typedef void     (* GtkWidgetActionActivate)   (GtkWidget           *widget,
                                                 const char          *action_name,
                                                 GVariant            *parameter);
+/**
+ * GtkWidgetActionQuery:
+ * @widget: the widget to which the action belongs
+ * @action_name: the (unprefixed) action name
+ * @enabled: (out) (optional): return location for the enabled state
+ * @parameter_type: (out) (optional): return location for the parameter type
+ * @state_type: (out) (optional): return location for the state type
+ * @state_hint: (out) (optional): return location for the state hint
+ * @state: (out) (optional): return location for the state
+ *
+ * The type of the callback functions used to query
+ * the properties of actions installed with gtk_widget_class_install_action().
+ *
+ * See the #GAction documentation for more details about the
+ * meaning of these properties.
+ *
+ * Returns: %TRUE if the action was found
+ */
 typedef gboolean (* GtkWidgetActionQuery)      (GtkWidget           *widget,
                                                 const char          *action_name,
                                                 gboolean            *enabled,
@@ -1040,6 +1069,25 @@ typedef gboolean (* GtkWidgetActionQuery)      (GtkWidget           *widget,
                                                 const GVariantType **state_type,
                                                 GVariant           **state_hint,
                                                 GVariant           **state);
+
+/**
+ * GtkWidgetActionChange:
+ * @widget: the widget to which the action belongs
+ * @action_name: the (unprefixed) action name
+ * @state: the new state
+ *
+ * The type of the callback functions used to change the
+ * state of actions installed with gtk_widget_class_install_action().
+ *
+ * The @state must match the @state_type of the action.
+ *
+ * Note that you can change the enabledness and state
+ * of widget actions by other means, as long as you
+ * emit the required #GActionGroup notification signals,
+ * which can be done with GtkWidget convenience API.
+ * This callback is used when the action state is
+ * changed via the #GActionGroup API.
+ */
 typedef void     (*GtkWidgetActionChange)      (GtkWidget           *widget,
                                                 const char          *action_name,
                                                 GVariant            *state);