From: Matthias Clasen Date: Tue, 20 Dec 2011 17:15:05 +0000 (-0500) Subject: Add references to the dbus interface docs on the wiki X-Git-Tag: 2.31.8~95 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=68706bfa2b91d4eb33cddfca2b640fcc3ce80637;p=platform%2Fupstream%2Fglib.git Add references to the dbus interface docs on the wiki And strip out the (now) redundant copy of that information from the sources. --- diff --git a/gio/gactiongroupexporter.c b/gio/gactiongroupexporter.c index 67cfa49..d1e9243 100644 --- a/gio/gactiongroupexporter.c +++ b/gio/gactiongroupexporter.c @@ -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[] = "" diff --git a/gio/gapplicationimpl-dbus.c b/gio/gapplicationimpl-dbus.c index aaf3787..d307f2a 100644 --- a/gio/gapplicationimpl-dbus.c +++ b/gio/gapplicationimpl-dbus.c @@ -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[] = "" " " diff --git a/gio/gmenuexporter.c b/gio/gmenuexporter.c index 4fab789..e57ad47 100644 --- a/gio/gmenuexporter.c +++ b/gio/gmenuexporter.c @@ -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 *