After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 644113 - GApplication docs: No real explanation of "actions"
GApplication docs: No real explanation of "actions"
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: gapplication
2.28.x
Other Linux
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks: 637445
 
 
Reported: 2011-03-07 11:55 UTC by Murray Cumming
Modified: 2013-05-24 02:37 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Murray Cumming 2011-03-07 11:55:55 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.
Comment 1 Murray Cumming 2011-08-03 07:05:31 UTC
This would still be really useful. It's hard to know how best to wrap the GtkApplication API otherwise.
Comment 2 Murray Cumming 2011-09-16 12:30:30 UTC
This still seems necessary.
Comment 3 Matthias Clasen 2011-12-12 21:49:43 UTC
I've added some more now
Comment 4 Murray Cumming 2011-12-13 11:32:27 UTC
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
Comment 5 Matthias Clasen 2013-05-24 02:37:45 UTC
lets consider this done for now