diff options
author | Murray Cumming <murrayc@murrayc.com> | 2013-10-08 09:38:10 +0200 |
---|---|---|
committer | Murray Cumming <murrayc@murrayc.com> | 2013-10-08 09:38:10 +0200 |
commit | 3aec72e2642f9daad798fb0206308b119b2a9684 (patch) | |
tree | 0fb4ff26b830ad0d3699f695edfb4e3c442f0906 | |
parent | 60635afca8eee801e24633b91c713bd0a1b11561 (diff) | |
download | glibmm-3aec72e2642f9daad798fb0206308b119b2a9684.tar.gz |
Docs: Add Action* and MenuItem docs.
-rw-r--r-- | gio/src/action.hg | 53 | ||||
-rw-r--r-- | gio/src/actiongroup.hg | 33 | ||||
-rw-r--r-- | gio/src/actionmap.hg | 3 | ||||
-rw-r--r-- | gio/src/menuitem.hg | 30 | ||||
-rw-r--r-- | gio/src/simpleaction.hg | 19 |
5 files changed, 125 insertions, 13 deletions
diff --git a/gio/src/action.hg b/gio/src/action.hg index 3e26652b..f5c4a687 100644 --- a/gio/src/action.hg +++ b/gio/src/action.hg @@ -79,9 +79,26 @@ public: _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: Docs //TODO: Is there any specific type that can really be used with this? A std::list<>. We must test this. // See also ActionGroup:::get_action_state_hint(). + /** Requests a hint about the valid range of values for the state of + * the action. + * + * If a null Variant 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. + * + * @param value This will be set to the state range hint. + */ template <typename T_Value> void get_state_hint(T_Value& value) const; @@ -118,13 +135,26 @@ public: _WRAP_METHOD(void change_state(const Glib::VariantBase& value), g_action_change_state, deprecated "Use the templated method instead, passing a normal C++ type.") - //TODO: Docs + /** Queries the current state of the action. + * + * If the action is not stateful then a null Variant will be returned. If the + * action is stateful then the type of the return value is the type + * given by get_state_type(). + * + * @param value This will be set to the current state of the action. + */ template <typename T_Value> void get_state(T_Value& value) const; _WRAP_METHOD(Glib::VariantBase get_state_variant() const, g_action_get_state) - //TODO: Docs + /** Activates the action. + * + * The @a parameter must be the correct type of parameter for the action (ie: + * the parameter type given at construction time), if any. + * + * @param parameter: The parameter to the activation + */ template <typename T_Value> void activate(const T_Value& parameter); @@ -143,7 +173,22 @@ public: //TODO: _WRAP_METHOD(static bool parse_detailed_name(const Glib::ustring& detailed_name, gchar** action_name, GVariant** target_value), g_action_parse_detailed_name, errthrow) - //TODO: Docs. + + /** Formats a detailed action name from @a action_name and @a target_value. + * + * It is an error to call this function with an invalid action name. + * + * This function is the opposite of parse_detailed_action_name(). + * It will produce a string that can be parsed back to the @a action_name + * and @a target_value by that function. + * + * See that function for the types of strings that will be printed by + * this function. + * + * @param action_name A valid action name. + * @param target_value A Variant target value. + * @result A detailed format string. + */ template <typename T_Value> Glib::ustring print_detailed_name(const Glib::ustring& action_name, const T_Value& value); diff --git a/gio/src/actiongroup.hg b/gio/src/actiongroup.hg index a715eeac..2edafaa2 100644 --- a/gio/src/actiongroup.hg +++ b/gio/src/actiongroup.hg @@ -78,7 +78,27 @@ public: _WRAP_METHOD(Glib::VariantContainerBase get_action_state_hint(const Glib::ustring& action_name) const, g_action_group_get_action_state_hint, deprecated "Use the get_action_state() method that takes an output parameter instead.") - //TODO: Docs + //TODO: How do we check for a NULL Variant? + /** + * Requests a hint about the valid range of values for the state of the + * named action within the action group + * + * If a null Variant 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 ariant array is returned then each item in the array is a + * possible value for the state. If 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. + * + * @param action_name The name of the action to query. + * @param value This will be set to the state range hint. + */ template <typename T_Value> void get_action_state_hint(const Glib::ustring& action_name, T_Value& value) const; @@ -87,7 +107,16 @@ public: _WRAP_METHOD(Glib::VariantBase get_action_state(const Glib::ustring& action_name) const, g_action_group_get_action_state, deprecated "Use the get_action_state() method that takes an output parameter instead.") - //TODO: Docs + //TODO: How do we check for a NULL Variant? + /** Queries the current state of the named action within the action group. + * + * If the action is not stateful then a null Variant will be returned. If the + * action is stateful then the type of the return value is the type + * given by get_action_state_type(). + * + * @param action_name The name of the action to query. + * @param value This will be set to the current state of the action. + */ template <typename T_Value> void get_action_state(const Glib::ustring& action_name, T_Value& value) const; diff --git a/gio/src/actionmap.hg b/gio/src/actionmap.hg index 97cf32a8..4400a68a 100644 --- a/gio/src/actionmap.hg +++ b/gio/src/actionmap.hg @@ -112,8 +112,7 @@ public: */ Glib::RefPtr<SimpleAction> add_action_bool(const Glib::ustring& name, bool state = false); -//TODO: Docs: Refer to this as a toggle action? - /** A convenience method for creating a boolean-stateful SimpleAction instance + /** A convenience method for creating a boolean-stateful (toggle) SimpleAction instance * and adding it to the ActionMap. * * @param name The name of the Action. diff --git a/gio/src/menuitem.hg b/gio/src/menuitem.hg index dae752b6..e7eb6c32 100644 --- a/gio/src/menuitem.hg +++ b/gio/src/menuitem.hg @@ -34,14 +34,38 @@ class MenuItem : public Glib::Object _CLASS_GOBJECT(MenuItem, GMenuItem, G_MENU_ITEM, Glib::Object, GObject) protected: - //TODO: Documentation + /** Creates a new MenuItem. + * + * If @a label is not empty it is used to set the "label" attribute of the + * new item. + * + * If @a detailed_action is not empty it is used to set the "action" and + * possibly the "target" attribute of the new item. See + * set_detailed_action() for more information. + * + * @param label The section label. + * @param detailed_action: The detailed action string. + */ explicit MenuItem(const Glib::ustring& label = Glib::ustring(), const Glib::ustring& detailed_action = Glib::ustring()); _IGNORE(g_menu_item_new) - //TODO: Documentation + /** Creates a new MenuItem representing a submenu. + * + * This is a convenience API around the MenuItem(label, detailed_action) constructor and + * set_submenu(). + * + * @param label The section label. + * @param A MenuModel with the items of the submenu. + */ explicit MenuItem(const Glib::ustring& label, const Glib::RefPtr<MenuModel>& submenu); - //TODO: Documentation + /** Creates a new MenuItem representing a submenu. + * + * This is a convenience API around the MenuItem(label, detailed_action) constructor and + * set_submenu(). + * + * @param A MenuModel with the items of the submenu. + */ explicit MenuItem(const Glib::RefPtr<MenuModel>& submenu); _IGNORE(g_menu_item_new_submenu) diff --git a/gio/src/simpleaction.hg b/gio/src/simpleaction.hg index 20a240d3..0a5059a3 100644 --- a/gio/src/simpleaction.hg +++ b/gio/src/simpleaction.hg @@ -45,10 +45,25 @@ class SimpleAction : public Glib::Object, public Action _STRUCT_NOT_HIDDEN protected: - //TODO: Docs + /** Creates a new action. + * + * The created action is stateless. + * + * @param name The name of the action. + * @param state The initial state of the action. + */ explicit SimpleAction(const Glib::ustring& name); - //TODO: Docs + /** Creates a new new stateful action. + * + * The created action is stateless. + * + * @a state is the initial state of the action. All future state values + * must have the same VariantType as the initial state. + * + * @param name The name of the action. + * @param state The initial state of the action. + */ SimpleAction(const Glib::ustring& name, const Glib::VariantBase& state); #m4 _CONVERSION(`const Glib::VariantType&',`const GVariantType*',`$3.gobj()') |