1 <?xml version="1.0" encoding="UTF-8"?>
3 A library to allow applications to provide simple indications of
4 information to be displayed to users of the application through the
7 Copyright 2009 Canonical Ltd.
10 Ted Gould <ted@canonical.com>
11 Aurélien Gâteau <aurelien.gateau@canonical.com>
13 This program is free software: you can redistribute it and/or modify it
14 under the terms of either or both of the following licenses:
16 1) the GNU Lesser General Public License version 3, as published by the
17 Free Software Foundation; and/or
18 2) the GNU Lesser General Public License version 2.1, as published by
19 the Free Software Foundation.
21 This program is distributed in the hope that it will be useful, but
22 WITHOUT ANY WARRANTY; without even the implied warranties of
23 MERCHANTABILITY, SATISFACTORY QUALITY or FITNESS FOR A PARTICULAR
24 PURPOSE. See the applicable version of the GNU Lesser General Public
25 License for more details.
27 You should have received a copy of both the GNU Lesser General Public
28 License version 3 and version 2.1 along with this program. If not, see
29 <http://www.gnu.org/licenses/>
31 <node name="/" xmlns:dox="http://www.canonical.com/dbus/dox.dtd">
35 The goal of DBusMenu is to expose menus on DBus.
37 Main interface is documented here: @ref com::canonical::dbusmenu
39 <interface name="com.canonical.dbusmenu">
41 A DBus interface to expose menus on DBus.
43 Menu items are represented with a unique numeric id and a dictionary of
46 To reduce the amount of DBus traffic, a property should only be returned
47 if its value is not the default value.
49 Available properties are:
56 <th>Default Value</th>
62 - "standard": an item which can be clicked to trigger an action or
64 - "separator": a separator
66 Vendor specific types can be added by prefixing them with
74 <td>Text of the item, except that:
75 -# two consecutive underscore characters "__" are displayed as a
77 -# any remaining underscore characters are not displayed at all,
78 -# the first of those remaining underscore characters (unless it is
79 the last character in the string) indicates that the following
80 character is the access key.
87 <td>Whether the item can be activated or not.</td>
93 <td>True if the item is visible in the menu.</td>
99 <td>Icon name of the item, following the freedesktop.org icon spec.</td>
105 <td>PNG data of the icon.</td>
110 <td>array of arrays of strings</td>
111 <td>The shortcut of the item. Each array represents the key press
112 in the list of keypresses. Each list of strings contains a list of
113 modifiers and then the key that is used. The modifier strings
114 allowed are: "Control", "Alt", "Shift" and "Super".
116 - A simple shortcut like Ctrl+S is represented as:
118 - A complex shortcut like Ctrl+Q, Alt+X is represented as:
119 [["Control", "Q"], ["Alt", "X"]]</td>
126 If the item can be toggled, this property should be set to:
127 - "checkmark": Item is an independent togglable item
128 - "radio": Item is part of a group where only one item can be
130 - "": Item cannot be toggled
135 <td>toggle-state</td>
138 Describe the current state of a "togglable" item. Can be one of:
141 - anything else = indeterminate
144 The implementation does not itself handle ensuring that only one
145 item in a radio group is set to "on", or that a group does not have
146 "on" and "indeterminate" items simultaneously; maintaining this
147 policy is up to the toolkit wrappers.
152 <td>children-display</td>
155 If the menu item has children this property should be set to
162 Vendor specific properties can be added by prefixing them with
167 <property name="Version" type="u" access="read">
169 Provides the version of the DBusmenu API that this API is
174 <property name="Status" type="s" access="read">
176 Tells if the menus are in a normal state or they believe that they
177 could use some attention. Cases for showing them would be if help
178 were referring to them or they accessors were being highlighted.
179 This property can have two values: "normal" in almost all cases and
180 "notice" when they should have a higher priority to be shown.
186 <method name="GetLayout">
187 <annotation name="com.trolltech.QtDBus.QtTypeName.Out1" value="DBusMenuLayoutItem"/>
189 Provides the layout and propertiers that are attached to the entries
190 that are in the layout. It only gives the items that are children
191 of the item that is specified in @a parentId. It will return all of the
192 properties or specific ones depending of the value in @a propertyNames.
194 The format is recursive, where the second 'v' is in the same format
195 as the original 'a(ia{sv}av)'. Its content depends on the value
196 of @a recursionDepth.
198 <arg type="i" name="parentId" direction="in">
199 <dox:d>The ID of the parent node for the layout. For
200 grabbing the layout from the root node use zero.</dox:d>
202 <arg type="i" name="recursionDepth" direction="in">
204 The amount of levels of recursion to use. This affects the
205 content of the second variant array.
206 - -1: deliver all the items under the @a parentId.
207 - 0: no recursion, the array will be empty.
208 - n: array will contains items up to 'n' level depth.
211 <arg type="as" name="propertyNames" direction="in" >
213 The list of item properties we are
214 interested in. If there are no entries in the list all of
215 the properties will be sent.
218 <arg type="u" name="revision" direction="out">
219 <dox:d>The revision number of the layout. For matching
220 with layoutUpdated signals.</dox:d>
222 <arg type="(ia{sv}av)" name="layout" direction="out">
223 <dox:d>The layout, as a recursive structure.</dox:d>
227 <method name="GetGroupProperties">
228 <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="QList<int>"/>
229 <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="DBusMenuItemList"/>
231 Returns the list of items which are children of @a parentId.
233 <arg type="ai" name="ids" direction="in" >
235 A list of ids that we should be finding the properties
236 on. If the list is empty, all menu items should be sent.
239 <arg type="as" name="propertyNames" direction="in" >
241 The list of item properties we are
242 interested in. If there are no entries in the list all of
243 the properties will be sent.
246 <arg type="a(ia{sv})" name="properties" direction="out" >
248 An array of property values.
249 An item in this area is represented as a struct following
251 @li id unsigned the item id
252 @li properties map(string => variant) the requested item properties
257 <method name="GetProperty">
259 Get a signal property on a single item. This is not useful if you're
260 going to implement this interface, it should only be used if you're
261 debugging via a commandline tool.
263 <arg type="i" name="id" direction="in">
264 <dox:d>the id of the item which received the event</dox:d>
266 <arg type="s" name="name" direction="in">
267 <dox:d>the name of the property to get</dox:d>
269 <arg type="v" name="value" direction="out">
270 <dox:d>the value of the property</dox:d>
274 <method name="Event">
276 This is called by the applet to notify the application an event happened on a
279 @a type can be one of the following:
284 Vendor specific events can be added by prefixing them with "x-<vendor>-"
286 <arg type="i" name="id" direction="in" >
287 <dox:d>the id of the item which received the event</dox:d>
289 <arg type="s" name="eventId" direction="in" >
290 <dox:d>the type of event</dox:d>
292 <arg type="v" name="data" direction="in" >
293 <dox:d>event-specific data</dox:d>
295 <arg type="u" name="timestamp" direction="in" >
296 <dox:d>The time that the event occured if available or the time the message was sent if not</dox:d>
300 <method name="AboutToShow">
302 This is called by the applet to notify the application that it is about
303 to show the menu under the specified item.
305 <arg type="i" name="id" direction="in">
307 Which menu item represents the parent of the item about to be shown.
310 <arg type="b" name="needUpdate" direction="out">
312 Whether this AboutToShow event should result in the menu being updated.
318 <signal name="ItemsPropertiesUpdated">
319 <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="DBusMenuItemList"/>
320 <annotation name="com.trolltech.QtDBus.QtTypeName.In1" value="DBusMenuItemKeysList"/>
322 Triggered when there are lots of property updates across many items
323 so they all get grouped into a single dbus message. The format is
324 the ID of the item with a hashtable of names and values for those
327 <arg type="a(ia{sv})" name="updatedProps" direction="out" />
328 <arg type="a(ias)" name="removedProps" direction="out" />
331 <signal name="LayoutUpdated">
333 Triggered by the application to notify display of a layout update, up to
336 <arg type="u" name="revision" direction="out" >
337 <dox:d>The revision of the layout that we're currently on</dox:d>
339 <arg type="i" name="parent" direction="out" >
341 If the layout update is only of a subtree, this is the
342 parent item for the entries that have changed. It is zero if
343 the whole layout should be considered invalid.
347 <signal name="ItemActivationRequested">
349 The server is requesting that all clients displaying this
350 menu open it to the user. This would be for things like
351 hotkeys that when the user presses them the menu should
352 open and display itself to the user.
354 <arg type="i" name="id" direction="out" >
355 <dox:d>ID of the menu that should be activated</dox:d>
357 <arg type="u" name="timestamp" direction="out" >
358 <dox:d>The time that the event occured</dox:d>
362 <!-- End of interesting stuff -->