diff options
author | Kjell Ahlstedt <kjellahlstedt@gmail.com> | 2022-06-06 18:57:01 +0200 |
---|---|---|
committer | Kjell Ahlstedt <kjellahlstedt@gmail.com> | 2022-06-06 19:00:10 +0200 |
commit | 08609ba2fd62113260d5bf0d10fac0620e22cb69 (patch) | |
tree | 7ecaeb53aa3bb0cb64965b1d16d9c85b8f62a495 | |
parent | a84b807b88b55c633ddccd1ebe48357abc49d728 (diff) | |
download | glibmm-08609ba2fd62113260d5bf0d10fac0620e22cb69.tar.gz |
Gio::Action: Improve the documentation
See issue #100
-rw-r--r-- | gio/src/action.hg | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/gio/src/action.hg b/gio/src/action.hg index 9b947622..9e603a79 100644 --- a/gio/src/action.hg +++ b/gio/src/action.hg @@ -32,33 +32,34 @@ typedef struct _GActionInterface GActionInterface; namespace Gio { -/** Action - An action. - * Action represents a single named action. +/** %Action - An action interface. + * %Action represents a single named action. * * The main interface to an action is that it can be activated with activate(). * This results in the signal_activate() signal being emitted. An activation - * has a Glib::VariantBase parameter (which may be <tt>0</tt>). The correct - * type for the parameter is determined by a static parameter type (which is - * given at construction time). + * may optionally have a parameter, activate(const T_Value& parameter). + * The correct type for the parameter is determined by a static parameter type + * (which is given at construction time). * * An action may optionally have a state, in which case the state may be set - * with change_state(). This call takes a Glib::VariantBase. The correct type - * for the state is determined by a static state type (which is given at - * construction time). + * with change_state(). The correct type for the state is determined by a static + * state type (which is given at construction time). + * + * An %Action can have a state, but no parameter, or vice versa. If it has both, + * the parameter type can differ from the state type. * * The state may have a hint associated with it, specifying its valid range. * - * Action is merely the interface to the concept of an action, as described - * above. Various implementations of actions exist, including SimpleAction and - * Gtk::Action. + * %Action is merely the interface to the concept of an action, as described + * above. Various implementations of actions exist, including SimpleAction. * * In all cases, the implementing class is responsible for storing the name of * the action, the parameter type, the enabled state, the optional state type * and the state and emitting the appropriate signals when these change. The - * implementor responsible for filtering calls to activate() and change_state() + * implementor is responsible for filtering calls to activate() and change_state() * for type safety and for the state being enabled. * - * Probably the only useful thing to do with a Action is to put it inside of a + * Probably the only useful thing to do with an %Action is to put it inside of a * SimpleActionGroup. * * @newin{2,32} @@ -142,16 +143,16 @@ public: _WRAP_METHOD(Glib::VariantBase get_state_variant() const, g_action_get_state) - /** Activates the action. + /** Activates the action without a parameter. */ void activate(); - /** Activates the action. + /** Activates the action with a parameter. * * The @a parameter must be the correct type of parameter for the action (ie: - * the parameter type given at construction time), if any. + * the parameter type given at construction time). * - * @param parameter: The parameter to the activation + * @param parameter The parameter to the activation */ template <typename T_Value> void activate(const T_Value& parameter); |