Commit 68706bfa authored by Matthias Clasen's avatar Matthias Clasen

Add references to the dbus interface docs on the wiki

And strip out the (now) redundant copy of that information
from the sources.
parent adbfa38c
......@@ -79,104 +79,14 @@ g_action_group_describe_action (GActionGroup *action_group,
return g_variant_builder_end (&builder);
}
/* The org.gtk.Actions interface
* =============================
*
* This interface describes a group of actions.
*
* Each action:
* - has a unique string name
* - can be activated
* - optionally has a parameter type that must be given to the activation
* - has an enabled state that may be true or false
* - optionally has a state which can change value, but not type
*
* Methods
* -------
*
* List :: () → (as)
*
* Lists the names of the actions exported at this object path.
*
* Describe :: (s) → (bgav)
*
* Describes a single action, or a given name.
*
* The return value has the following components:
* b: specifies if the action is currently enabled. This is
* a hint that attempting to interact with the action will
* produce no effect.
* g: specifies the optional parameter type. If not "",
* the string specifies the type of argument that must
* be passed to the activation.
* av: specifies the optional state. If not empty, the array
* contains the current value of the state as a variant
*
* DescribeAll :: () → (a{s(bgav)})
*
* Describes all actions in a single round-trip.
*
* The dictionary maps action name strings to their descriptions
* (in the format discussed above).
*
* Activate :: (sava{sv}) → ()
*
* Requests activation of the named action.
*
* The action is named by the first parameter (s).
*
* If the action activation requires a parameter then this parameter
* must be given in the second parameter (av). If there is no parameter
* to be specified, the array must be empty.
*
* The final parameter (a{sv}) is a list of "platform data".
*
* This method is not guaranteed to have any particular effect. The
* implementation may take some action (including changing the state
* of the action, if it is stateful) or it may take none at all. In
* particular, callers should expect their request to be completely
* ignored when the enabled flag is false (but even this is not
* guaranteed).
*
* SetState :: (sva{sv}) → ()
*
* Requests the state of an action to be changed to the given value.
*
* The action is named by the first parameter (s).
*
* The requested new state is given in the second parameter (v).
* It must be equal in type to the existing state.
*
* The final parameter (a{sv}) is a list of "platform data".
*
* This method is not guaranteed to have any particular effect.
* The implementation of an action can choose to ignore the requested
* state change, or choose to change its state to something else or
* to trigger other side effects. In particular, callers should expect
* their request to be completely ignored when the enabled flag is
* false (but even this is not guaranteed).
*
* Signals
* -------
*
* Changed :: (asa{sb}a{sv}a{s(bgav)})
*
* Signals that some change has occured to the action group.
*
* Four separate types of changes are possible, and the 4 parameters
* of the change signal reflect these possibilities:
* as: a list of removed actions
* a{sb}: a list of actions that had their enabled flag changed
* a{sv}: a list of actions that had their state changed
* a{s(bgav)}: a list of new actions added in the same format as
* the return value of the DescribeAll method
*/
/* Using XML saves us dozens of relocations vs. using the introspection
* structure types. We only need to burn cycles and memory if we
* actually use the exporter -- not in every single app using GIO.
*
* It's also a lot easier to read. :)
*
* For documentation of this interface, see
* http://live.gnome.org/GTK+/GApplication-dbus-apis
*/
const char org_gtk_Actions_xml[] =
"<node>"
......
......@@ -45,6 +45,10 @@ g_dbus_action_group_sync (GDBusActionGroup *group,
/* DBus Interface definition {{{1 */
/* For documentation of these interfaces, see
* http://live.gnome.org/GTK+/GApplication-dbus-apis
*/
static const gchar org_gtk_Application_xml[] =
"<node>"
" <interface name='org.gtk.Application'>"
......
......@@ -42,104 +42,8 @@
/* {{{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
/* For documentation of this interface, see
* http://live.gnome.org/GTK+/GApplication-dbus-apis
*/
static GDBusInterfaceInfo *
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment