GNOME Bugzilla – Bug 644113
GApplication docs: No real explanation of "actions"
Last modified: 2013-05-24 02:37:45 UTC
The GApplication (and GtkApplication) documentation doesn't seem to have any real mention of what the "action"s are, what they are good for, or how they might be used or experienced by a user. The first thing GApplication's documentation says about actions is " GApplication also implements the GActionGroup interface and lets you easily export actions by adding them with g_application_set_action_group(). When invoking an action by calling g_action_group_activate_action() on the application, it is always invoked in the primary instance. " http://library.gnome.org/devel/gio/unstable/GApplication.html#GApplication.description It does not mention "scriptability", though the GtkApplication does: " provides some basic scriptability by exporting 'actions', " http://library.gnome.org/devel/gtk3/stable/GtkApplication.html#GtkApplication.description GActionGroup's documentation isn't much more enlightening: " GActionGroup represents a group of actions. Each action in the group has a unique name (which is a string). All method calls, except g_action_group_list_actions() take the name of an action as an argument. The GActionGroup API is meant to be the 'public' API to the action group. The calls here are exactly the interaction that 'external forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have with actions. 'Internal' APIs (ie: ones meant only to be accessed by the action group implementation) are found on subclasses. This is why you will find -- for example -- g_action_group_get_enabled() but not an equivalent set() call. Signals are emitted on the action group in response to state changes on individual actions. " http://library.gnome.org/devel/gio/unstable/GActionGroup.html#GActionGroup.description At the least, those paragraphs should be reordered. And these sentences are almost completely meaningless: "GActionGroup represents a group of actions" "The GActionGroup API is meant to be the 'public' API to the action group." But mostly there's just a lack of overview and no mention of the real world.
This would still be really useful. It's hard to know how best to wrap the GtkApplication API otherwise.
This still seems necessary.
I've added some more now
Thanks. Note to self: This is the change: http://git.gnome.org/browse/glib/commit/?id=e24241384793b9d4648d00df8ac972dafcbc87a0 I also need to adapt the gtkmm documentation for this change: http://git.gnome.org/browse/glib/commit/?id=dec7ed8abad74baa70160e0652171666d5ca461f
lets consider this done for now