[glibmm] Gio::Action: Add more documentation of get_state_hint() and get_state().
- From: Kjell Ahlstedt <kjellahl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glibmm] Gio::Action: Add more documentation of get_state_hint() and get_state().
- Date: Fri, 28 Dec 2012 14:56:37 +0000 (UTC)
commit fea3c2189ad1398f1b69f03f3db4385322c61a8c
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date: Fri Dec 28 15:51:22 2012 +0100
Gio::Action: Add more documentation of get_state_hint() and get_state().
* gio/src/action.hg: get_state_hint() and get_state() returns void, which
makes them useless. That can't be fixed until the next ABI break. Explain in
the documentation what to do instead of calling these methods. Bug #690134.
ChangeLog | 8 ++++++
gio/src/action.hg | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4a41e0e..a33a7ea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2012-12-28 Kjell Ahlstedt <kjell ahlstedt bredband net>
+
+ Gio::Action: Add more documentation of get_state_hint() and get_state().
+
+ * gio/src/action.hg: get_state_hint() and get_state() returns void, which
+ makes them useless. That can't be fixed until the next ABI break. Explain in
+ the documentation what to do instead of calling these methods. Bug #690134.
+
2012-12-27 Kjell Ahlstedt <kjell ahlstedt bredband net>
SignalProxy: Fix the documentation, especially of connect_notify().
diff --git a/gio/src/action.hg b/gio/src/action.hg
index baa9b22..c14fa84 100644
--- a/gio/src/action.hg
+++ b/gio/src/action.hg
@@ -77,8 +77,71 @@ public:
_WRAP_METHOD(Glib::ustring get_name() const, g_action_get_name)
_WRAP_METHOD(Glib::VariantType get_parameter_type() const, g_action_get_parameter_type)
_WRAP_METHOD(Glib::VariantType get_state_type() const, g_action_get_state_type)
+
+ //TODO: Change the return type of get_state_hint() when we can break ABI.
+ // See https://bugzilla.gnome.org/show_bug.cgi?id=690134
+ /** Requests a hint about the valid range of values for the state of
+ * @a action.
+ *
+ * @note
+ * This method is useless in its present form. It should return Glib::VariantBase,
+ * but it returns @c void. This bug cannot be fixed until the ABI of glibmm can be broken.
+ * Meanwhile you can use the C function in glib like so:
+ * @code
+ * Glib::VariantBase state_hint = Glib::wrap(g_action_get_state_hint(myAction.gobj()));
+ * @endcode
+ * If myAction is a const object:
+ * @code
+ * Glib::VariantBase state_hint = Glib::wrap(g_action_get_state_hint(const_cast<GAction*>(myAction.gobj())));
+ * @endcode
+ *
+ * If <tt>0</tt> is returned it either means that the action is not stateful
+ * or that there is no hint about the valid range of values for the
+ * state of the action.
+ *
+ * If a Variant array is returned then each item in the array is a
+ * possible value for the state. If a Variant pair (ie: two-tuple) is
+ * returned then the tuple specifies the inclusive lower and upper bound
+ * of valid values for the state.
+ *
+ * In any case, the information is merely a hint. It may be possible to
+ * have a state value outside of the hinted range and setting a value
+ * within the range may fail.
+ *
+ * @newin{2,28}
+ * @return The state range hint.
+ */
_WRAP_METHOD(void get_state_hint() const, g_action_get_state_hint)
+
_WRAP_METHOD(bool get_enabled() const, g_action_get_enabled)
+
+ //TODO: Change the return type of get_state() when we can break ABI.
+ // See https://bugzilla.gnome.org/show_bug.cgi?id=690134
+ /** Queries the current state of @a action.
+ *
+ * @note
+ * This method is useless in its present form. It should return Glib::VariantBase,
+ * but it returns @c void. This bug cannot be fixed until the ABI of glibmm can be broken.
+ * Meanwhile you can use property_state() like so:
+ * @code
+ * Glib::VariantBase state = myAction.property_state();
+ * @endcode
+ * You can also use the C function in glib like so:
+ * @code
+ * Glib::VariantBase state = Glib::wrap(g_action_get_state(myAction.gobj()));
+ * @endcode
+ * If myAction is a const object:
+ * @code
+ * Glib::VariantBase state = Glib::wrap(g_action_get_state(const_cast<GAction*>(myAction.gobj())));
+ * @endcode
+ *
+ * If the action is not stateful then <tt>0</tt> will be returned. If the
+ * action is stateful then the type of the return value is the type
+ * given by get_state_type().
+ *
+ * @newin{2,28}
+ * @return The current state of the action.
+ */
_WRAP_METHOD(void get_state() const, g_action_get_state)
_WRAP_METHOD(void change_state(const Glib::VariantBase& value), g_action_change_state)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]