From 486fbce42bdac6803390abb76a8753929a07ea64 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 19 Jul 2020 17:04:11 -0400 Subject: [PATCH] actionmuxer: Update docs and clean up headers Update the doc comment at the top to describe the current functionality of GtkActionMuxer. --- gtk/gtkactionmuxer.c | 30 ++++++++++++++++++------- gtk/gtkactionmuxerprivate.h | 44 +++++++++++++++++-------------------- 2 files changed, 42 insertions(+), 32 deletions(-) diff --git a/gtk/gtkactionmuxer.c b/gtk/gtkactionmuxer.c index 3c013507cb..31800680c2 100644 --- a/gtk/gtkactionmuxer.c +++ b/gtk/gtkactionmuxer.c @@ -105,10 +105,24 @@ gtk_accels_remove (GtkAccels *accels, /*< private > * SECTION:gtkactionmuxer - * @short_description: Aggregate and monitor several action groups + * @short_description: Aggregate and monitor actions from multiple sources * - * #GtkActionMuxer is a #GActionGroup and #GtkActionObservable that is - * capable of containing other #GActionGroup instances. + * #GtkActionMuxer is #GtkActionObservable and #GtkActionObserver that + * offers a #GActionGroup-like api and is capable of containing other + * #GActionGroup instances. #GtkActionMuxer does not implement the + * #GActionGroup interface because it requires excessive signal emissions + * and has poor scalability. We use the #GtkActionObserver machinery + * instead to propagate changes between action muxer instances and + * to other users. + * + * Beyond action groups, #GtkActionMuxer can incorporate actions that + * are associated with widget classes (*class actions*) and actions + * that are associated with the parent widget, allowing for recursive + * lookup. + * + * In addition to the action attributes provided by #GActionGroup, + * #GtkActionMuxer maintains a *primary accelerator* string for + * actions that can be shown in menuitems. * * The typical use is aggregating all of the actions applicable to a * particular context into a single action group, with namespacing. @@ -119,12 +133,12 @@ gtk_accels_remove (GtkAccels *accels, * application (such as “fullscreen”). * * In this case, each of these action groups could be added to a - * #GtkActionMuxer with the prefixes “app” and “win”, respectively. This - * would expose the actions as “app.quit” and “win.fullscreen” on the - * #GActionGroup interface presented by the #GtkActionMuxer. + * #GtkActionMuxer with the prefixes “app” and “win”, respectively. + * This would expose the actions as “app.quit” and “win.fullscreen” + * on the #GActionGroup-like interface presented by the #GtkActionMuxer. * - * Activations and state change requests on the #GtkActionMuxer are wired - * through to the underlying action group in the expected way. + * Activations and state change requests on the #GtkActionMuxer are + * wired through to the underlying actions in the expected way. * * This class is typically only used at the site of “consumption” of * actions (eg: when displaying a menu that contains many actions on diff --git a/gtk/gtkactionmuxerprivate.h b/gtk/gtkactionmuxerprivate.h index 7708d5eb1c..19e3365672 100644 --- a/gtk/gtkactionmuxerprivate.h +++ b/gtk/gtkactionmuxerprivate.h @@ -52,7 +52,7 @@ GType gtk_action_muxer_get_type (void); GtkActionMuxer * gtk_action_muxer_new (GtkWidget *widget); void gtk_action_muxer_insert (GtkActionMuxer *muxer, - const gchar *prefix, + const char *prefix, GActionGroup *action_group); void gtk_action_muxer_remove (GtkActionMuxer *muxer, @@ -65,13 +65,7 @@ GtkActionMuxer * gtk_action_muxer_get_parent (GtkActi void gtk_action_muxer_set_parent (GtkActionMuxer *muxer, GtkActionMuxer *parent); -void gtk_action_muxer_set_primary_accel (GtkActionMuxer *muxer, - const gchar *action_and_target, - const gchar *primary_accel); - -const char * gtk_action_muxer_get_primary_accel (GtkActionMuxer *muxer, - const gchar *action_and_target); - +/* GActionGroup equivalent api */ gboolean gtk_action_muxer_query_action (GtkActionMuxer *muxer, const char *action_name, gboolean *enabled, @@ -89,25 +83,27 @@ gboolean gtk_action_muxer_has_action (GtkActi const char *action_name); char ** gtk_action_muxer_list_actions (GtkActionMuxer *muxer); +/* api for class actions */ +void gtk_action_muxer_action_enabled_changed (GtkActionMuxer *muxer, + const char *action_name, + gboolean enabled); +void gtk_action_muxer_action_state_changed (GtkActionMuxer *muxer, + const char *action_name, + GVariant *state); +void gtk_action_muxer_connect_class_actions (GtkActionMuxer *muxer); -void -gtk_action_muxer_action_enabled_changed (GtkActionMuxer *muxer, - const char *action_name, - gboolean enabled); -void -gtk_action_muxer_action_state_changed (GtkActionMuxer *muxer, - const gchar *action_name, - GVariant *state); - - -void gtk_action_muxer_connect_class_actions (GtkActionMuxer *muxer); +/* api for accels */ +void gtk_action_muxer_set_primary_accel (GtkActionMuxer *muxer, + const char *action_and_target, + const char *primary_accel); +const char * gtk_action_muxer_get_primary_accel (GtkActionMuxer *muxer, + const char *action_and_target); /* No better place for these... */ -gchar * gtk_print_action_and_target (const gchar *action_namespace, - const gchar *action_name, - GVariant *target); - -gchar * gtk_normalise_detailed_action_name (const gchar *detailed_action_name); +char * gtk_print_action_and_target (const char *action_namespace, + const char *action_name, + GVariant *target); +char * gtk_normalise_detailed_action_name (const char *detailed_action_name); G_END_DECLS