widget: Add a convenience api to activate actions

Since actions are used increasingly, we should
have a convenient way to trigger an action in
the context of a widget.

docs/reference/gtk/gtk4-sections.txt

@@ -4538,13 +4538,14 @@ gtk_widget_get_realized
 gtk_widget_get_mapped
 gtk_widget_device_is_shadowed
 gtk_widget_get_modifier_mask
-gtk_widget_insert_action_group
 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_measure
 gtk_widget_snapshot_child
 gtk_widget_get_next_sibling

gtk/gtkwidget.c

@@ -12890,6 +12890,36 @@ gtk_widget_get_action_group (GtkWidget   *widget,
   return NULL;
 }
 
+/**
+ * gtk_widget_activate_action:
+ * @widget: a #GtkWidget
+ * @name: a prefixed action name
+ * @parameter: parameters that required by the action
+ *
+ * Looks up the action in the action groups associated
+ * with @widget and its ancestors, and activates it.
+ *
+ * The action name is expected to be prefixed with the
+ * prefix that was used when adding the action group
+ * with gtk_widget_insert_action_group().
+ *
+ * The @parameter must match the actions expected parameter
+ * type, as returned by g_action_get_parameter_type().
+ */
+void
+gtk_widget_activate_action (GtkWidget  *widget,
+                            const char *name,
+                            GVariant   *parameter)
+{
+  GtkActionMuxer *muxer;
+
+  muxer = _gtk_widget_get_action_muxer (widget, FALSE);
+  if (muxer)
+    g_action_group_activate_action (G_ACTION_GROUP (muxer),
+                                    name,
+                                    parameter);
+}
+
 void
 gtk_widget_cancel_event_sequence (GtkWidget             *widget,
                                   GtkGesture            *gesture,

gtk/gtkwidget.h

@@ -1011,6 +1011,11 @@ GActionGroup           *gtk_widget_get_action_group     (GtkWidget             *
 GDK_AVAILABLE_IN_ALL
 const gchar **          gtk_widget_list_action_prefixes (GtkWidget             *widget);
 
+GDK_AVAILABLE_IN_ALL
+void                    gtk_widget_activate_action      (GtkWidget  *widget,
+                                                         const char *name,
+                                                         GVariant   *parameter);
+
 GDK_AVAILABLE_IN_ALL
 void                    gtk_widget_set_font_map         (GtkWidget             *widget,
                                                          PangoFontMap          *font_map);