src/com.canonical.dbusmenu.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3 A library to allow applications to provide simple indications of
   4 information to be displayed to users of the application through the
   5 interface shell.
   6
   7 Copyright 2009 Canonical Ltd.
   8
   9 Authors:
  10     Ted Gould <ted@canonical.com>
  11     Aurélien Gâteau <aurelien.gateau@canonical.com>
  12
  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:
  15
  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.
  20
  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.
  26
  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/>
  30 -->
  31 <node name="/" xmlns:dox="http://www.canonical.com/dbus/dox.dtd">
  32     <dox:d><![CDATA[
  33     @mainpage
  34
  35     The goal of DBusMenu is to expose menus on DBus.
  36
  37     Main interface is documented here: @ref com::canonical::dbusmenu
  38     ]]></dox:d>
  39         <interface name="com.canonical.dbusmenu">
  40                 <dox:d><![CDATA[
  41                 A DBus interface to expose menus on DBus.
  42
  43                 Menu items are represented with a unique numeric id and a dictionary of
  44                 properties.
  45
  46                 To reduce the amount of DBus traffic, a property should only be returned
  47                 if its value is not the default value.
  48
  49                 Available properties are:
  50
  51                 <table>
  52                 <tr>
  53                         <th>Name</th>
  54                         <th>Type</th>
  55                         <th>Description</th>
  56                         <th>Default Value</th>
  57                 </tr>
  58                 <tr>
  59                         <td>type</td>
  60                         <td>String</td>
  61                         <td>Can be one of:
  62                         - "standard": an item which can be clicked to trigger an action or
  63                           show another menu
  64                         - "separator": a separator
  65
  66                         Vendor specific types can be added by prefixing them with
  67                         "x-<vendor>-".
  68                         </td>
  69                         <td>"standard"</td>
  70                 </tr>
  71                 <tr>
  72                         <td>label</td>
  73                         <td>string</td>
  74                         <td>Text of the item, except that:
  75                         -# two consecutive underscore characters "__" are displayed as a
  76                         single underscore,
  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.
  81                         </td>
  82                         <td>""</td>
  83                 </tr>
  84                 <tr>
  85                         <td>enabled</td>
  86                         <td>boolean</td>
  87                         <td>Whether the item can be activated or not.</td>
  88                         <td>true</td>
  89                 </tr>
  90                 <tr>
  91                         <td>visible</td>
  92                         <td>boolean</td>
  93                         <td>True if the item is visible in the menu.</td>
  94                         <td>true</td>
  95                 </tr>
  96                 <tr>
  97                         <td>icon-name</td>
  98                         <td>string</td>
  99                         <td>Icon name of the item, following the freedesktop.org icon spec.</td>
 100                         <td>""</td>
 101                 </tr>
 102                 <tr>
 103                         <td>icon-data</td>
 104                         <td>binary</td>
 105                         <td>PNG data of the icon.</td>
 106                         <td>Empty</td>
 107                 </tr>
 108                 <tr>
 109                         <td>shortcut</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".
 115
 116                         - A simple shortcut like Ctrl+S is represented as:
 117                           [["Control", "S"]]
 118                         - A complex shortcut like Ctrl+Q, Alt+X is represented as:
 119                           [["Control", "Q"], ["Alt", "X"]]</td>
 120                         <td>Empty</td>
 121                 </tr>
 122                 <tr>
 123                         <td>toggle-type</td>
 124                         <td>string</td>
 125                         <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
 129                           toggled at a time
 130                         - "": Item cannot be toggled
 131                         </td>
 132                         <td>""</td>
 133                 </tr>
 134                 <tr>
 135                         <td>toggle-state</td>
 136                         <td>int</td>
 137                         <td>
 138                         Describe the current state of a "togglable" item. Can be one of:
 139                         - 0 = off
 140                         - 1 = on
 141                         - anything else = indeterminate
 142
 143                         Note:
 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.
 148                         </td>
 149                         <td>-1</td>
 150                 </tr>
 151                 <tr>
 152                         <td>children-display</td>
 153                         <td>string</td>
 154                         <td>
 155                         If the menu item has children this property should be set to
 156                         "submenu".
 157                         </td>
 158                         <td>""</td>
 159                 </tr>
 160                 </table>
 161
 162                 Vendor specific properties can be added by prefixing them with
 163                 "x-<vendor>-".
 164                 ]]></dox:d>
 165
 166 <!-- Properties -->
 167                 <property name="Version" type="u" access="read">
 168                         <dox:d>
 169                         Provides the version of the DBusmenu API that this API is
 170                         implementing.
 171                         </dox:d>
 172                 </property>
 173
 174         <property name="Status" type="s" access="read">
 175             <dox:d>
 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.
 181             </dox:d>
 182         </property>
 183
 184 <!-- Functions -->
 185
 186                 <method name="GetLayout">
 187                         <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="DBusMenuLayoutItem"/>
 188                         <dox:d>
 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.
 193
 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.
 197                         </dox:d>
 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>
 201                         </arg>
 202                         <arg type="i" name="recursionDepth" direction="in">
 203                                 <dox:d>
 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.
 209                                 </dox:d>
 210                         </arg>
 211                         <arg type="as" name="propertyNames" direction="in" >
 212                                 <dox:d>
 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.
 216                                 </dox:d>
 217                         </arg>
 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>
 221                         </arg>
 222                         <arg type="(ia{sv}av)" name="layout" direction="out">
 223                                 <dox:d>The layout, as a recursive structure.</dox:d>
 224                         </arg>
 225                 </method>
 226
 227                 <method name="GetGroupProperties">
 228                         <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QList&lt;int&gt;"/>
 229                         <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="DBusMenuItemList"/>
 230                         <dox:d>
 231                         Returns the list of items which are children of @a parentId.
 232                         </dox:d>
 233                         <arg type="ai" name="ids" direction="in" >
 234                                 <dox:d>
 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.
 237                                 </dox:d>
 238                         </arg>
 239                         <arg type="as" name="propertyNames" direction="in" >
 240                                 <dox:d>
 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.
 244                                 </dox:d>
 245                         </arg>
 246                         <arg type="a(ia{sv})" name="properties" direction="out" >
 247                                 <dox:d>
 248                                         An array of property values.
 249                                         An item in this area is represented as a struct following
 250                                         this format:
 251                                         @li id unsigned the item id
 252                                         @li properties map(string => variant) the requested item properties
 253                                 </dox:d>
 254                         </arg>
 255                 </method>
 256
 257                 <method name="GetProperty">
 258                         <dox:d>
 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.
 262                         </dox:d>
 263                         <arg type="i" name="id" direction="in">
 264                                 <dox:d>the id of the item which received the event</dox:d>
 265                         </arg>
 266                         <arg type="s" name="name" direction="in">
 267                                 <dox:d>the name of the property to get</dox:d>
 268                         </arg>
 269                         <arg type="v" name="value" direction="out">
 270                                 <dox:d>the value of the property</dox:d>
 271                         </arg>
 272                 </method>
 273
 274                 <method name="Event">
 275                         <dox:d><![CDATA[
 276                         This is called by the applet to notify the application an event happened on a
 277                         menu item.
 278
 279                         @a type can be one of the following:
 280
 281                         @li "clicked"
 282                         @li "hovered"
 283
 284                         Vendor specific events can be added by prefixing them with "x-<vendor>-"
 285                         ]]></dox:d>
 286                         <arg type="i" name="id" direction="in" >
 287                                 <dox:d>the id of the item which received the event</dox:d>
 288                         </arg>
 289                         <arg type="s" name="eventId" direction="in" >
 290                                 <dox:d>the type of event</dox:d>
 291                         </arg>
 292                         <arg type="v" name="data" direction="in" >
 293                                 <dox:d>event-specific data</dox:d>
 294                         </arg>
 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>
 297                         </arg>
 298                 </method>
 299
 300                 <method name="AboutToShow">
 301                         <dox:d>
 302                         This is called by the applet to notify the application that it is about
 303                         to show the menu under the specified item.
 304                         </dox:d>
 305                         <arg type="i" name="id" direction="in">
 306                                 <dox:d>
 307                                 Which menu item represents the parent of the item about to be shown.
 308                                 </dox:d>
 309                         </arg>
 310                         <arg type="b" name="needUpdate" direction="out">
 311                                 <dox:d>
 312                                 Whether this AboutToShow event should result in the menu being updated.
 313                                 </dox:d>
 314                         </arg>
 315                 </method>
 316
 317 <!-- Signals -->
 318                 <signal name="ItemsPropertiesUpdated">
 319                         <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="DBusMenuItemList"/>
 320                         <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="DBusMenuItemKeysList"/>
 321                         <dox:d>
 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
 325                         properties.
 326                         </dox:d>
 327                         <arg type="a(ia{sv})" name="updatedProps" direction="out" />
 328                         <arg type="a(ias)" name="removedProps" direction="out" />
 329                 </signal>
 330
 331                 <signal name="LayoutUpdated">
 332                         <dox:d>
 333                         Triggered by the application to notify display of a layout update, up to
 334                         revision
 335                         </dox:d>
 336                         <arg type="u" name="revision" direction="out" >
 337                                 <dox:d>The revision of the layout that we're currently on</dox:d>
 338                         </arg>
 339                         <arg type="i" name="parent" direction="out" >
 340                                 <dox:d>
 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.
 344                                 </dox:d>
 345                         </arg>
 346                 </signal>
 347                 <signal name="ItemActivationRequested">
 348                         <dox:d>
 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.
 353                         </dox:d>
 354                         <arg type="i" name="id" direction="out" >
 355                                 <dox:d>ID of the menu that should be activated</dox:d>
 356                         </arg>
 357                         <arg type="u" name="timestamp" direction="out" >
 358                                 <dox:d>The time that the event occured</dox:d>
 359                         </arg>
 360                 </signal>
 361
 362 <!-- End of interesting stuff -->
 363
 364         </interface>
 365 </node>