diff options
author | José Alburquerque <jaalburqu@svn.gnome.org> | 2012-02-24 00:22:29 -0500 |
---|---|---|
committer | José Alburquerque <jaalburqu@svn.gnome.org> | 2012-02-24 00:22:29 -0500 |
commit | 55c1a9cd689d17df4656845e95074ee75788c2af (patch) | |
tree | a6e91239f826fc199ca84329075eded4c71a4904 | |
parent | 0ffe3600df4acd89eaeb5fe4acc4d0d3535a0543 (diff) | |
download | glibmm-55c1a9cd689d17df4656845e95074ee75788c2af.tar.gz |
MenuModel: Add the attribute and link constants.
* gio/src/dbusmenumodel.hg:
* gio/src/menumodel.ccg: Add the class documentation. Also add the
attribute and link constants from the C API in enums and re-wrap the
existing methods to use the enums (this was adapted from gstreamermm).
-rw-r--r-- | ChangeLog | 9 | ||||
-rw-r--r-- | gio/src/menumodel.ccg | 25 | ||||
-rw-r--r-- | gio/src/menumodel.hg | 113 |
3 files changed, 141 insertions, 6 deletions
@@ -1,3 +1,12 @@ +2012-02-24 José Alburquerque <jaalburquerque@gmail.com> + + MenuModel: Add the attribute and link constants. + + * gio/src/dbusmenumodel.hg: + * gio/src/menumodel.ccg: Add the class documentation. Also add the + attribute and link constants from the C API in enums and re-wrap the + existing methods to use the enums (this was adapted from gstreamermm). + 2012-02-23 José Alburquerque <jaalburquerque@gmail.com> giomm: Add the DBus::MenuModel class. diff --git a/gio/src/menumodel.ccg b/gio/src/menumodel.ccg index 75c2bd17..5d6612eb 100644 --- a/gio/src/menumodel.ccg +++ b/gio/src/menumodel.ccg @@ -22,4 +22,29 @@ namespace Gio { +// Make sure the order here is the same order as in Gio::MenuAttribute. +static const char* const _attribute_strings[] = +{ + G_MENU_ATTRIBUTE_ACTION, + G_MENU_ATTRIBUTE_LABEL, + G_MENU_ATTRIBUTE_TARGET +}; + +const char* giomm_get_menu_attribute(MenuAttribute attribute) +{ + return _attribute_strings[attribute]; +} + +// Make sure the order here is the same order as in Gio::MenuLink. +static const char* const _link_strings[] = +{ + G_MENU_LINK_SECTION, + G_MENU_LINK_SUBMENU +}; + +const char* giomm_get_menu_link(MenuLink link) +{ + return _link_strings[link]; +} + } // namespace Gio diff --git a/gio/src/menumodel.hg b/gio/src/menumodel.hg index 181fd25b..70a6258f 100644 --- a/gio/src/menumodel.hg +++ b/gio/src/menumodel.hg @@ -23,10 +23,103 @@ _PINCLUDE(glibmm/private/object_p.h) namespace Gio { +enum MenuAttribute +{ + /// The "action" menu attribute. + MENU_ATTRIBUTE_ACTION, + + /// The "label" menu attribute. + MENU_ATTRIBUTE_LABEL, + + /// The "target" menu attribute. + MENU_ATTRIBUTE_TARGET +}; + +enum MenuLink +{ + /// The "section" menu link. + MENU_LINK_SECTION, + + /// The "submenu" menu link. + MENU_LINK_SUBMENU +}; + class MenuAttributeIter; class MenuLinkIter; -/** TODO (When the docs is available from the C API). +/** MenuModel - An abstract class representing the contents of a menu. + * MenuModel represents the contents of a menu -- an ordered list of menu + * items. The items are associated with actions, which can be activated through + * them. Items can be grouped in sections, and may have submenus associated + * with them. Both items and sections usually have some representation data, + * such as labels or icons. The type of the associated action (ie whether it is + * stateful, and what kind of state it has) can influence the representation of + * the item. + * + * The conceptual model of menus in MenuModel is hierarchical: sections and + * submenus are again represented by MenuModels. Menus themselves do not define + * their own roles. Rather, the role of a particular MenuModel is defined by + * the item that references it (or, in the case of the 'root' menu, is defined + * by the context in which it is used). + * + * The motivation for this abstract model of application controls is that + * modern user interfaces tend to make these controls available outside the + * application. Examples include global menus, jumplists, dash boards, etc. To + * support such uses, it is necessary to 'export' information about actions and + * their representation in menus, which is exactly what + * Gio::DBus::Connection::export_action_group() and the + * Gio::DBus::Connection::export_menu_model() do for ActionGroup and MenuModel. + * The client-side counterparts to make use of the exported information are + * Gio::DBus::ActionGroup and Gio::DBus::MenuModel. + * + * The API of MenuModel is very generic, with iterators for the attributes and + * links of an item, see iterate_item_attributes() and iterate_item_links(). + * The 'standard' attributes and link types have predefined names: + * Gio::MENU_ATTRIBUTE_LABEL, Gio::MENU_ATTRIBUTE_ACTION, + * Gio::MENU_ATTRIBUTE_TARGET, Gio::MENU_LINK_SECTION and + * Gio::MENU_LINK_SUBMENU. + * + * Items in a MenuModel represent active controls if they refer to an action + * that can get activated when the user interacts with the menu item. The + * reference to the action is encoded by the string id in the + * Gio::MENU_ATTRIBUTE_ACTION attribute. An action id uniquely identifies an + * action in an action group. Which action group(s) provide actions depends on + * the context in which the menu model is used. E.g. when the model is exported + * as the application menu of a Gtk::Application, actions can be + * application-wide or window-specific (and thus come from two different action + * groups). By convention, the application-wide actions have names that start + * with "app.", while the names of window-specific actions start with "win.". + * + * While a wide variety of stateful actions is possible, the following is the + * minimum that is expected to be supported by all users of exported menu + * information: + * + * - an action with no parameter type and no state + * - an action with no parameter type and boolean state + * - an action with string parameter type and string state + * + * <b>Stateless.</b> A stateless action typically corresponds to an ordinary + * menu item. Selecting such a menu item will activate the action (with no + * parameter). + * + * <b>Boolean State.</b> An action with a boolean state will most typically be + * used with a "toggle" or "switch" menu item. The state can be set directly, + * but activating the action (with no parameter) results in the state being + * toggled. Selecting a toggle menu item will activate the action. The menu + * item should be rendered as "checked" when the state is true. + * + * <b>String Parameter and State.</b> Actions with string parameters and state + * will most typically be used to represent an enumerated choice over the items + * available for a group of radio menu items. Activating the action with a + * string parameter is equivalent to setting that parameter as the state. Radio + * menu items, in addition to being associated with the action, will have a + * target value. Selecting that menu item will result in activation of the + * action with the target value as the parameter. The menu item should be + * rendered as "selected" when the state of the action is equal to the target + * value of the menu item. + * + * See the C API docs for a graphical example. + * @newin{2,32} */ class MenuModel : public Glib::Object { @@ -36,13 +129,21 @@ protected: _CTOR_DEFAULT public: - _WRAP_METHOD(Glib::VariantBase get_item_attribute(int item_index, const Glib::ustring& attribute, const Glib::VariantType& expected_type), g_menu_model_get_item_attribute_value) - _WRAP_METHOD(const Glib::VariantBase get_item_attribute(int item_index, const Glib::ustring& attribute, const Glib::VariantType& expected_type) const, g_menu_model_get_item_attribute_value, constversion) +#m4begin +dnl See the .ccg implementation for how this conversion works. + _CONVERSION(`MenuAttribute',`const gchar*',`giomm_get_menu_attribute($3)') +#m4end + _WRAP_METHOD(Glib::VariantBase get_item_attribute(int item_index, MenuAttribute attribute, const Glib::VariantType& expected_type), g_menu_model_get_item_attribute_value) + _WRAP_METHOD(const Glib::VariantBase get_item_attribute(int item_index, MenuAttribute attribute, const Glib::VariantType& expected_type) const, g_menu_model_get_item_attribute_value, constversion) - //TODO?: _WRAP_METHOD(bool get_item_attribute(int item_index, const Glib::ustring& attribute, const Glib::ustring& format_string, ...), g_menu_model_get_item_attribute) + //TODO?: _WRAP_METHOD(bool get_item_attribute(int item_index, MenuAttribute attribute, const Glib::ustring& format_string, ...), g_menu_model_get_item_attribute) - _WRAP_METHOD(Glib::RefPtr<MenuModel> get_item_link(int item_index, const Glib::ustring& link), g_menu_model_get_item_link) - _WRAP_METHOD(Glib::RefPtr<const MenuModel> get_item_link(int item_index, const Glib::ustring& link) const, g_menu_model_get_item_link, constversion) +#m4begin +dnl See the .ccg implementation for how this conversion works. + _CONVERSION(`MenuLink',`const gchar*',`giomm_get_menu_link($3)') +#m4end + _WRAP_METHOD(Glib::RefPtr<MenuModel> get_item_link(int item_index, MenuLink link), g_menu_model_get_item_link) + _WRAP_METHOD(Glib::RefPtr<const MenuModel> get_item_link(int item_index, MenuLink link) const, g_menu_model_get_item_link, constversion) _WRAP_METHOD(Glib::RefPtr<MenuAttributeIter> iterate_item_attributes(int item_index), g_menu_model_iterate_item_attributes) _WRAP_METHOD(Glib::RefPtr<const MenuAttributeIter> iterate_item_attributes(int item_index) const, g_menu_model_iterate_item_attributes, constversion) |