xml/org.freedesktop.atspi.Event.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2 <tp:struct name="EventListenerMode">
   3   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
   4     <p>A structure that encapsulates the characteristics of the event notifications
   5       that should be sent to an EventListener in response to a call to
   6       DeviceEventController.registerKeystrokeListener or
   7       DeviceEventController.registerDeviceEventListener. </p>
   8   </tp:docstring>
   9   <tp:member type="b" tp:name="synchronous">
  10   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  11     <p>If \c <code>True</code>, specifies that
  12       DeviceEventController should block while waiting
  13       for client to process the requested event notifications;
  14       ordinarily should be used only when client needs to perform
  15       operations synchronously with event delivery. Note that because
  16       of the architecture of device event systems in general,
  17       use of this flag may not block delivery of the event to
  18       the currently focussed application unless it is used in
  19       conjunction with the preemptive flag. </p>
  20   </tp:docstring>
  21   </tp:member>
  22   <tp:member type="b" tp:name="preemptive">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>If <code>True</code>, specifies that
  25       Listener is allowed to pre-empt the delivery of the event,
  26       effectively 'consuming' it such that it is not delivered
  27       to the currently focussed desktop application.
  28       Key events consumed via this API will not be
  29       available for use by other applications or services, so this
  30       option should be used sparingly. </p>
  31   </tp:docstring>
  32   </tp:member>
  33   <tp:member type="b" tp:name="global">
  34   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  35     <p>If <code>True</code>, specifies that
  36       Event notifications should be sent regardless of whether the
  37       currently focussed application participates in the AT-SPI
  38       infrastructure.  On systems with the XEvIE X extension, this flag
  39       also allows access to events which are already subject to
  40       interception via a 'system keygrab' (as described in the X Window System
  41       documentation for XGrabKey).  The 'global' and 'preemptive' flags
  42       should only be used together for the purposes of registering
  43       'system global key shortcuts' i.e. command keys for use by the
  44       assistive technology. </p>
  45   </tp:docstring>
  46   </tp:member>
  47 </tp:struct>
  48 <tp:struct name="DeviceEvent">
  49   <tp:docstring>
  50     A structure which encapsulates information about a device event.
  51   </tp:docstring>
  52   <tp:member type="u" tp:name="type">
  53   <tp:docstring>
  54     Identifies the type of the containing DeviceEvent.
  55   </tp:docstring>
  56   </tp:member>
  57   <tp:member type="i" tp:name="id">
  58   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  59     <p>An identifier which identifies this event in the event stream.
  60       On X Window systems this corresponds to the XEvent serial number.</p>
  61   </tp:docstring>
  62   </tp:member>
  63   <tp:member type="n" tp:name="hw_code">
  64   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  65     <p>A numeric code which is hardware and system-dependent, identifying the
  66       specific hardware button or key on the device for which the event has
  67       occurred. On X Window systems, for global key notifications and for most
  68       non-global key notifications as well, this code corresponds to the
  69       XKeycode.  For switch and button events it indicates the switch
  70       or button number.
  71     </p>
  72     <p>
  73       For technical reasons, this code may differ from the XKeycode
  74       when generated by Java applications for consumption by non-global
  75       key listeners.  This is subject to change in future versions of the
  76       DeviceEventController implementation.
  77     </p>
  78   </tp:docstring>
  79   </tp:member>
  80   <tp:member type="n" tp:name="modifiers">
  81   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  82     <p>An unsigned short int consisting of zero or more of the following
  83       values OR'ed together:
  84       <ol>
  85               <li><code>MODIFIER_SHIFT</code> (=1, corresponds to Xlib's ShiftMask)</li>
  86               <li><code>MODIFIER_SHIFTLOCK</code> (=2, corresponds to Xlib's LockMask)</li>
  87               <li><code>MODIFIER_CONTROL</code> (=4, corresponds to Xlib's ControlMask)</li>
  88               <li><code>MODIFIER_ALT</code> (=8, corresponds to Xlib's Mod1Mask)</li>
  89               <li><code>MODIFIER_META</code> (=16, corresponds to Xlib's Mod2Mask)</li>
  90               <li><code>MODIFIER_META2</code> (=32, corresponds to Xlib's Mod3Mask)</li>
  91               <li><code>MODIFIER_META3</code> (=64, corresponds to Xlib's Mod4Mask)</li>
  92       </ol>
  93     </p>
  94   </tp:docstring>
  95   </tp:member>
  96   <tp:member type="i" tp:name="timestamp">
  97   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  98     <p>An unsigned integer representing the time that the
  99       event occurred.  On X Window systems this event is
 100       a time in milliseconds from some arbitrary starting
 101       point; it therefore has a cycle time of approximately
 102       50 days.</p>
 103   </tp:docstring>
 104   </tp:member>
 105   <tp:member type="s" tp:name="event_string">
 106   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 107     <p>A string representation of the event.  If is_text is
 108       <code>True</code>, then this string represents the character or typographic
 109       sequence that would be received by a focussed text input field.
 110       event_string is in general suitable for exposure to the
 111       end-user for purposes of keyboard echo.</p>
 112   </tp:docstring>
 113   </tp:member>
 114   <tp:member type="b" tp:name="is_text">
 115   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 116     <p><code>True</code> if the event results in the insertion of characters
 117       into an input text buffer, or would do so if delivered to a focussed
 118       text input field. 'Typographical' key events have this field set to
 119       <code>True</code>, whereas 'control' key events generally do not.</p>
 120   </tp:docstring>
 121   </tp:member>
 122 </tp:struct>
 123 <tp:struct name="KeyDefinition">
 124   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 125     <p>A structure which defines the identity of a key for which notifications
 126       are to be requested.  The data in the members of a KeyDefinition are used to
 127       determine which keyboard events 'match' the notification request filed by a client.  </p>
 128
 129     <p>Ordinarily a KeyDefinition specifies one and only one of the criteria below;
 130       the result of using a KeyDefinition with multiple members defined as nonzero is
 131       undefined.</p>
 132
 133   </tp:docstring>
 134   <tp:member type="i" tp:name="keycode">
 135           <tp:docstring>
 136       If nonzero, the numeric, system-dependent value corresponding to a
 137       physical key on the keyboard.  Keycode values have no semantic meaning to the end-user,
 138       and may depend on the user's hardware and operating environment.  They therefore are
 139       rarely useful 'as-is' to AT clients, unless the client has used operating system
 140       services to identify the hardward keycode associated with a particular key symbol.
 141       Notifications for key events requested by keycode are less dependent on modifier state
 142       than <code>keysym</code> based notifications, but some hardware (notably many laptops) may generate
 143       more than one keycode for the same physical key, depending on the state of physical
 144       shift/modifier keys.
 145           </tp:docstring>
 146   </tp:member>
 147   <tp:member type="i" tp:name="keysym">
 148           <tp:docstring>
 149       If nonzero, the numeric value corresponding to the X Keysym of the key for which
 150       notification is requested.  Note that the presence of active modifiers will affect
 151       whether notification for key events requested via 'keysym' specification takes place,
 152       since the keysym depends on the modifier state for most keys.
 153           </tp:docstring>
 154   </tp:member>
 155   <tp:member type="s" tp:name="keystring">
 156           <tp:docstring>
 157       If non-NULL, the string value of the inserted characters if the corresponding
 158       key event has KeyEvent:.is_text set to <code>True</code>, or the string representing the
 159       'name' of the key.  On X11 systems, the string 'name' of non-printing keysyms corresponds
 160       to the values in 'keysymdef.h' as provided by Xlib, with the leading 'XK_'; stripped off.
 161           </tp:docstring>
 162   </tp:member>
 163 </tp:struct>
 164 <interface name="org.freedesktop.atspi.DeviceEventListener">
 165   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 166     <p>This interface should be implemented by AT-SPI clients who wish to
 167       make use of the DeviceEventController to receive device event notifications.
 168       DeviceEvents include keyboard events and mouse button/motion events.</p>
 169   </tp:docstring>
 170   <method name="notifyEvent">
 171     <tp:docstring>
 172       Notify an interested DeviceEventListener that a DeviceEvent has occurred.
 173     </tp:docstring>
 174     <arg direction="in" name="event" type="(uinnisb)" tp:type="DeviceEvent"/>
 175     <arg direction="out" type="b" tp:type="boolean">
 176     <tp:docstring>
 177       <code>True</code> if the recipient/consumer wishes to consume the event, i.e.prevent it from being delivered to the desktop, <code>False</code> if the event should continue to be delivered as normal.
 178     </tp:docstring>
 179     </arg>
 180   </method>
 181 </interface>
 182 <interface name="org.freedesktop.atspi.DeviceEventController">
 183   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 184     <p>The interface via which clients request notification of device events, and
 185       through which device events may be simulated.</p>
 186   </tp:docstring>
 187   <method name="registerKeystrokeListener">
 188     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 189       <p>Register to intercept keyboard events, and either pass them on or
 190         consume them.     </p>
 191     </tp:docstring>
 192     <arg direction="in" name="listener" type="o" tp:type="DeviceEventListener">
 193     <tp:docstring>
 194       A DeviceEventListener which will intercept key events.
 195     </tp:docstring>
 196     </arg>
 197     <arg direction="in" name="keys" type="a(iisi)" tp:type="KeySet">
 198     <tp:docstring>
 199       A KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 200     </tp:docstring>
 201     </arg>
 202     <arg direction="in" name="mask" type="u" tp:type="ControllerEventMask">
 203     <tp:docstring>
 204       A ControllerEventMask filtering the intercepted key events.
 205     </tp:docstring>
 206     </arg>
 207     <arg direction="in" name="type" type="au" tp:type="KeyEventTypeSeq">
 208     <tp:docstring>
 209       A KeyEventTypeSeq that may created by ORing event types together.
 210     </tp:docstring>
 211     </arg>
 212     <arg direction="in" name="mode" type="(bbb)" tp:type="EventListenerMode">
 213     <tp:docstring>
 214             An EventListenerMode indicating whether the listener should receive the events synchronously, potentially consuming them,or just be notified asynchronously of those events that havebeen generated.
 215
 216             Some platforms have limited support for global, preemptive EventListenerMode.Such a registration may fail if another client already has priority for preemptiveaccess to one or more of the members of the KeySet.  AT consumers have the optionof re-trying the request without the global flag, or without the preemptive flag,or of re-trying with a different KeySet.  The best support for pre-emptiveglobal keyboard listeners is provided on platforms whose Xserver implementationprovides the XEvIE extension.
 217     </tp:docstring>
 218     </arg>
 219     <arg direction="out" type="b" tp:type="boolean">
 220     <tp:docstring>
 221       <code>True</code> if the DeviceEventListener was successfully registeredfor the requested KeySet, ControllerEventMask, event types, and EventListenerMode; otherwise returns <code>False</code>.
 222     </tp:docstring>
 223     </arg>
 224   </method>
 225   <method name="deregisterKeystrokeListener">
 226     <tp:docstring>
 227       De-register a previously registered keyboard eventlistener.
 228     </tp:docstring>
 229     <arg direction="in" name="listener" type="o" tp:type="DeviceEventListener">
 230     <tp:docstring>
 231       A DeviceEventListener which will intercept key events.
 232     </tp:docstring>
 233     </arg>
 234     <arg direction="in" name="keys" type="a(iisi)" tp:type="KeySet">
 235     <tp:docstring>
 236       A KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 237     </tp:docstring>
 238     </arg>
 239     <arg direction="in" name="mask" type="u" tp:type="ControllerEventMask">
 240     <tp:docstring>
 241       A ControllerEventMask filtering the intercepted key events.
 242     </tp:docstring>
 243     </arg>
 244     <arg direction="in" name="type" type="au" tp:type="KeyEventTypeSeq">
 245     <tp:docstring>
 246       An EventType mask that may created by ORing event types together.
 247     </tp:docstring>
 248     </arg>
 249   </method>
 250   <method name="registerDeviceEventListener">
 251     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 252       <p>Register to intercept events, and either pass them on or
 253         consume them. To listen to keyboard events use registerKeystrokeListener
 254         instead.</p>
 255     </tp:docstring>
 256     <arg direction="in" name="listener" type="o" tp:type="DeviceEventListener">
 257     <tp:docstring>
 258       A DeviceEventListener which will intercept events.
 259     </tp:docstring>
 260     </arg>
 261     <arg direction="in" name="types" type="u" tp:type="EventTypeSeq">
 262     <tp:docstring>
 263       An EventTypeSeq indicating which event types to listen for.
 264     </tp:docstring>
 265     </arg>
 266     <arg direction="out" type="b" tp:type="boolean">
 267     <tp:docstring>
 268       <code>True</code> if successful, <code>False</code> if not
 269     </tp:docstring>
 270     </arg>
 271   </method>
 272   <method name="deregisterDeviceEventListener">
 273     <tp:docstring>
 274       De-register a previously registered keyboard eventlistener.
 275     </tp:docstring>
 276     <arg direction="in" name="listener" type="o" tp:type="DeviceEventListener">
 277     <tp:docstring>
 278       a DeviceEventListener which will intercept events.
 279     </tp:docstring>
 280     </arg>
 281     <arg direction="in" name="types" type="u" tp:type="EventTypeSeq">
 282     <tp:docstring>
 283       An EventTypeSeq indicating which event types to stoplistening for.
 284     </tp:docstring>
 285     </arg>
 286   </method>
 287   <method name="notifyListenersSync">
 288     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 289       <p>Notify the Registry instance that a device event has taken place, and
 290         allow pre-emptive listeners the opportunity to 'consume' the event
 291         and thus prevent its further issuance/forwarding.  This is the
 292         method used by accessibility bridges to forward 'toolkit dependent'
 293         device events to the Registry from the application's process space.</p>
 294
 295       <p>AT clients do not normally need to use this method, it is intended for use
 296         by toolkit bridges and special-purpose applications.</p>
 297     </tp:docstring>
 298     <arg direction="in" name="event" type="(uinnisb)" tp:type="DeviceEvent"/>
 299     <arg direction="out" type="b" tp:type="boolean">
 300     <tp:docstring>
 301       <code>True</code> if the event was consumed by a (pre-emptive) listener, <code>False</code> if not (in which case the device event will be forwardedas normal to any application which would normally receive it, e.g.the currently active application in the case of mouse or keyboard events).
 302     </tp:docstring>
 303     </arg>
 304   </method>
 305   <method name="notifyListenersAsync">
 306     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 307       <p>Notify the Registry instance that a device event has taken place in
 308         an asynchronous manner.  This is the
 309         method used by accessibility bridges to forward 'toolkit dependent'
 310         device events to the Registry from the application's process space.
 311         If the event in question is potentially pre-emptible.
 312         notifyListenersSync should be used instead.</p>
 313
 314       <p>AT clients do not normally need to use this method, it is intended for use
 315         by toolkit bridges and special-purpose applications.</p>
 316     </tp:docstring>
 317     <arg direction="in" name="event" type="(uinnisb)" tp:type="DeviceEvent"/>
 318   </method>
 319   <method name="generateKeyboardEvent">
 320     <tp:docstring>
 321       Synthesize a keyboard event.
 322     </tp:docstring>
 323     <arg direction="in" name="keycode" type="i">
 324     <tp:docstring>
 325       A long integer indicating the keycode ofthe keypress to be synthesized.
 326     </tp:docstring>
 327     </arg>
 328     <arg direction="in" name="keystring" type="s">
 329     <tp:docstring>
 330       An optional UTF-8 string indicating a complexkeyboard input event.
 331     </tp:docstring>
 332     </arg>
 333     <arg direction="in" name="type" type="u" tp:type="KeySynthType">
 334     <tp:docstring>
 335             <p>A KeySynthType indicating the type of event(s) to be synthesized: a key press, release, press-release pair,or a complex input string (for instance from aninternationalized or complex text input method, ora composed character).</p>
 336
 337             <p>Keycode may be truncated before beingprocessed, as keycode length may be platform-dependentand keycode ranges are generally much smaller thanCORBA_long. One or the other of keycode or keystring are generally NULL, (but not both), depending on the value of <code>type</code>.</p>
 338     </tp:docstring>
 339     </arg>
 340   </method>
 341   <method name="generateMouseEvent">
 342     <tp:docstring>
 343       Synthesize a mouse event.
 344     </tp:docstring>
 345     <arg direction="in" name="x" type="i">
 346     <tp:docstring>
 347       A long integer indicating the screen x coord for the mouse event.
 348     </tp:docstring>
 349     </arg>
 350     <arg direction="in" name="y" type="i">
 351     <tp:docstring>
 352       A long integer indicating the screen y coord for the mouse event.
 353     </tp:docstring>
 354     </arg>
 355     <arg direction="in" name="eventName" type="s">
 356     <tp:docstring>
 357             A string indicating the type of mouse event, e.g. 'button1up'.
 358     </tp:docstring>
 359     </arg>
 360   </method>
 361 </interface>
 362 </node>