mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-09 19:06:15 +01:00
Add references to the dbus interface docs on the wiki
And strip out the (now) redundant copy of that information from the sources.
This commit is contained in:
Matthias Clasen
parent
adbfa38c8e
commit
68706bfa2b
@ -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 *
|
||||
|
||||
Loading…
Reference in New Issue
Block a user