diff options
author | Jasper St. Pierre <jstpierre@mecheye.net> | 2013-05-13 15:11:41 -0400 |
---|---|---|
committer | Jasper St. Pierre <jstpierre@mecheye.net> | 2013-05-13 15:22:45 -0400 |
commit | e5f22c649239d8da4c858535818ef8e9f699df5e (patch) | |
tree | 9995c307be494307270ea803338b8ce1f4a0aa4a | |
parent | 6f8fdf22ac202c89305495660e3f339bf463ae77 (diff) | |
download | gtk+-wip/gtkmenutrackeritem-rebased.tar.gz |
Add some usage docs for the new private copy/paste APIswip/gtkmenutrackeritem-rebased
-rw-r--r-- | gtk/gtkmenutracker.c | 34 | ||||
-rw-r--r-- | gtk/gtkmenutrackeritem.c | 51 |
2 files changed, 85 insertions, 0 deletions
diff --git a/gtk/gtkmenutracker.c b/gtk/gtkmenutracker.c index ba8c4b9b10..fad9b44ac2 100644 --- a/gtk/gtkmenutracker.c +++ b/gtk/gtkmenutracker.c @@ -23,6 +23,40 @@ #include "gtkmenutracker.h" +/** + * SECTION:gtkmenutracker + * @Title: GtkMenuTracker + * @Short_description: A helper class for interpreting #GMenuModel + * + * #GtkMenuTracker is a simple object to ease implementations of #GMenuModel. + * Given a #GtkActionObservable (usually a #GActionMuxer) along with a + * #GMenuModel, it will tell you which menu items to create and where to place + * them. If a menu item is removed, it will tell you the position of the menu + * item to remove. + * + * Using #GtkMenuTracker is fairly simple. The only guarantee you must make + * to #GtkMenuTracker is that you must obey all insert signals and track the + * position of items that #GtkMenuTracker gives you. That is, #GtkMenuTracker + * expects positions of all the latter items to change when it calls your + * insertion callback with an early position, as it may ask you to remove + * an item with a readjusted position later. + * + * #GtkMenuTracker will give you a #GtkMenuTrackerItem in your callback. You + * must hold onto this object until a remove signal is emitted. This item + * represents a signal menu item, which can be one of three classes: normal item, + * separator, or submenu. + * + * Certain properties on the #GtkMenuTrackerItem are mutable, and you must + * listen for changes in the item. For more details, see the documentation + * for #GtkMenuTrackerItem along with https://live.gnome.org/GApplication/GMenuModel. + * + * The idea of @with_separators is for special cases where menu models may + * be tracked in places where separators are not available, like in toplevel + * "File", "Edit" menu bars. Ignoring separator items is wrong, as #GtkMenuTracker + * expects the position to change, so we must tell #GtkMenuTracker to ignore + * separators itself. + */ + typedef struct _GtkMenuTrackerSection GtkMenuTrackerSection; struct _GtkMenuTracker diff --git a/gtk/gtkmenutrackeritem.c b/gtk/gtkmenutrackeritem.c index 3c6e8f54a8..237fa49729 100644 --- a/gtk/gtkmenutrackeritem.c +++ b/gtk/gtkmenutrackeritem.c @@ -23,6 +23,57 @@ #include "gtkmenutrackeritem.h" +/** + * SECTION:gtkmenutrackeritem + * @Title: GtkMenuTrackerItem + * @Short_description: Small helper for model menu items + * + * A #GtkMenuTrackerItem is a small helper class used by #GtkMenuTracker to + * represent menu items. It has one of three classes: normal item, separator, + * or submenu. + * + * If an item is one of the non-normal classes (submenu, separator), only the + * label of the item needs to be respected. Otherwise, all the properties + * of the item contribute to the item's appearance and state. + * + * Implementing the appearance of the menu item is up to toolkits, and certain + * toolkits may choose to ignore certain properties, like icon or accel. The + * role of the item determines its accessibility role, along with its + * decoration if the GtkMenuTrackerItem::toggled property is true. As an + * example, if the item has the role %GTK_MENU_TRACKER_ITEM_ROLE_CHECK and + * GtkMenuTrackerItem::toggled is %FALSE, its accessible role should be that of + * a check menu item, and no decoration should be drawn. But if + * GtkMenuTrackerItem::toggled is %TRUE, a checkmark should be drawn. + * + * All properties except for the two class-determining properties, + * GtkMenuTrackerItem::is-separator and GtkMenuTrackerItem::has-submenu are + * allowed to change, so either bind the properties to properties of your + * appearance's implementation, or listen to the notify signals to update + * your appearance. + * + * When an item is clicked, simply call gtk_menu_tracker_item_activated() in + * response. The #GtkMenuTrackerItem will take care of everything related to + * activating the item and will itself update the state of all items in + * response. + * + * Submenus are a special case of menu item. When an item is a submenu, you + * should create a submenu for it with gtk_menu_tracker_new_item_for_submenu(), + * and apply the same menu tracking logic you would for a toplevel menu. + * Applications using submenus may want to lazily build their submenus in + * response to the user clicking on it, as building a submenu may be expensive. + * + * Thus, the submenu has two special controls -- the submenu's visibility + * should be controlled by the GtkMenuTrackerItem::submenu-shown property, + * and if a user clicks on the submenu, do not immediately show the menu, + * but call gtk_menu_tracker_item_request_submenu_shown() and wait for the + * GtkMenuTrackerItem::submenu-shown property to update. If the user navigates, + * the application may want to be notified so it can cancel the expensive + * operation that it was using to build the submenu. Thus, + * gtk_menu_tracker_item_request_submenu_shown() takes a boolean parameter. + * Use %TRUE when the user wants to open the submenu, and %FALSE when the + * user wants to close the submenu. + */ + typedef GObjectClass GtkMenuTrackerItemClass; struct _GtkMenuTrackerItem |