Describe the org.gtk.Menus interface

Even though we consider the interface to be an implementation
detail, we should have internal documentation of the interface.

1 files changed, 101 insertions, 0 deletions

diff --git a/gio/gmenuexporter.c b/gio/gmenuexporter.c
index 0f173c507..6d9df454d 100644
--- a/gio/gmenuexporter.c
+++ b/gio/gmenuexporter.c
@@ -41,6 +41,107 @@
  */
 
 /* {{{1 D-Bus Interface description */
+
+/* The org.gtk.Menus interface
+ * ===========================
+ *
+ * The interface is primarily concerned with three things:
+ *
+ * - communicating menus to the client
+ * - establishing links between menus and other menus
+ * - notifying clients of changes
+ *
+ * As a basic principle, it is recognised that the menu structure
+ * of an application is often large. It is also recognised that some
+ * menus are liable to frequently change without the user ever having
+ * opened the menu. For both of these reasons, the individual menus are
+ * arranged into subscription groups. Each subscription group is specified
+ * by an unsigned integer. The assignment of integers need not be consecutive.
+ *
+ * Within a subscription group there are multiple menus. Each menu is
+ * identified with an unsigned integer, unique to its subscription group.
+ *
+ * By convention, the primary menu is numbered 0 without subscription group 0.
+ *
+ * Actionable menu items (ie: those that produce some effect in the
+ * application when they are activated) have a related action, specified by
+ * a string. This string specifies the name of the action, according to the
+ * org.gtk.Actions interface, at the same object path as the menu.
+ *
+ * Methods
+ * -------
+ *
+ * Start :: (au) → (a(uuaa{sv}))
+ *
+ *   The Start method is used to indicate that a client is interested in
+ *   tracking and displaying the content of the menus of a particular list
+ *   of subscription groups.
+ *
+ *   Most typically, the client will request subscription group 0 to start.
+ *
+ *   The call has two effects. First, it replies with all menus defined
+ *   within the requested subscription groups. The format of the reply is
+ *   an array of tuples, where the items in each tuple are:
+ *   - the subscription group of the menu
+ *   - the number of the menu within that group
+ *   - an array of menu items
+ *
+ *   Each menu item is a dictionary of attributes (a{sv}).
+ *
+ *   Secondly, this call has a side effect: it atomically requests that
+ *   the Changed signal start to be emitted for the requested subscription
+ *   group. Each group has a subscription count and only signals changes
+ *   on itself when this count is greater than zero.
+ *
+ *   If a group is specified multiple times then the result is that the
+ *   contents of that group is only returned once, but the subscription
+ *   count is increased multiple times.
+ *
+ *   If a client disconnects from the bus while holding subscriptions then
+ *   its subscriptions will be cancelled. This prevents "leaking" subscriptions
+ *   in the case of crashes and is also useful for applications that want
+ *   to exit without manually cleaning up.
+ *
+ * End :: (au)
+ *
+ *   The End method reverses the previous effects of a call to Start.
+ *
+ *   When clients are no longer interested in the contents of a subscription
+ *   group, they should call the End method.
+ *
+ *   The parameter lists the subscription groups. A subscription group
+ *   needs to be cancelled the same number of times as it was requested.
+ *   For this reason, it might make sense to specify the same subscription
+ *   group multiple times (if multiple Start calls were made for this group).
+ *
+ * Signals
+ * -------
+ *
+ * Changed :: (a(uuuuaa{sv}))
+ *
+ *   The changed signal indicates changes to a particular menu.
+ *
+ *   The changes come as an array of tuples where the items in each tuple are:
+ *   - the subscription group of the menu
+ *   - the number of the menu within that group
+ *   - the position in the menu at which to make the change
+ *   - the number of items to delete from that position
+ *   - a list of new items to insert at that position
+ *
+ *   Each new menu item is a dictionary of attributes (a{sv}).
+ *
+ * Attributes
+ * ----------
+ *
+ * label (string): the label to display
+ * action (string): the name of the action
+ * target (variant): the parameter to pass when activating the action
+ * :section ((uu)): the menu to use to populate that section, specified
+ *     as a pair of subscription group and menu within that group
+ * :submenu ((uu)): the menu to use as a submenu, specified
+ *     as a pair of subscription group and menu within that group
+ */
+
 static GDBusInterfaceInfo *
 org_gtk_Menus_get_interface (void)
 {