xml/Accessibility_Event.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001, 2002 Sun Microsystems Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>This library is free software; you can redistribute it and/or
   8     modify it under the terms of the GNU Library General Public
   9     License as published by the Free Software Foundation; either
  10     version 2 of the License, or (at your option) any later version.</p>
  11
  12   <p>This library is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15     Library General Public License for more details.</p>
  16
  17   <p>You should have received a copy of the GNU Library General Public
  18     License along with this library; if not, write to the
  19     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20     Boston, MA 02111-1307, USA.</p>
  21 </tp:license>
  22 <tp:struct name="EventDetails">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>A struct encapsulating detailed information about an Event.
  25       This struct supercedes the previous use of the 'any' field
  26       in EventDetails; the content previously stored in Event::any_data
  27       is now stored in EventDetails::any_data, and Event::any_data
  28       points to an instance of the EventDetails structure, if
  29       the object's implementation supports event detail reporting,
  30       otherwise Event::any_data contains CORBA_OBJECT_NIL.  </p>
  31
  32     <p>@since AT-SPI 1.7.0</p>
  33   </tp:docstring>
  34   <tp:member type="o" tp:name="host_application"/>
  35   <tp:member type="u" tp:name="source_role"/>
  36   <tp:member type="s" tp:name="source_name"/>
  37   <tp:member type="v" tp:name="any_data"/>
  38 </tp:struct>
  39 <tp:struct name="Event">
  40   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  41     <p>A structure encapsulating information about an event
  42       for which notification was requested.  Usually such notification
  43       is requested via a call to Registry::registerGlobalEventListener.
  44       The structure contains a colon-delimited string indicating the event
  45       type, a reference to the generating Accessible, two detail fields whose
  46       interpretation is event-type-specific, and a final field containing
  47       event-type-specific data.  </p>
  48
  49     <p>@note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
  50       struct, which encapsulates additional information about the event
  51       and its generating object.</p>
  52   </tp:docstring>
  53   <tp:member type="s" tp:name="type">
  54   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  55     <p>A colon-delimited string indicating the type of the event.
  56       The string can be interpreted as
  57       \c class:type:subtype
  58       For instance ¨object:text-changed:insert¨ is an event
  59       from the 'Object' class, which corresponds to Accessible objects
  60       general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
  61       content of an implementor of the Text interface), and the
  62       specific subtype of the change is an insertion event.  </p>
  63
  64     <p>Event classes include the following:
  65       \li focus:   an object has received keyboard focus.  This event has no type or subtype.
  66       \li window:  a toplevel window has changed state.
  67       \li object:  an object (i.e. Accessible) has undergone some change in state, content,
  68       or hierarchy
  69       \li document:a change to a document's content has occurred, or its
  70       content loading status has changed.
  71       \li mouse:   an event originating from the pointing device.  Rarely used;
  72       in most cases clients will wish to register for pointer events via
  73       the DeviceEventController::registerDeviceEvent method instead.
  74       \li keyboard: an event indicating that the keyboard state (for example, the
  75       modifier state) has changed significantly.
  76       &quot;keyboard:&quot; events are not sent for individual keystrokes except as
  77       a side-effect of certain keys, for instance modifier keys.
  78       Clients interested in key events should listen for DeviceEvents
  79       via DeviceEventController::registerKeystrokeListener instead.  </p>
  80
  81     <p>@note For more information on specific event types, see the documentation for
  82       each of the individual interfaces supported by some Accessible objects.  </p>
  83
  84     <p>@see Accessible, Component, Image, Selection, Table, Text, Value.</p>
  85   </tp:docstring>
  86   </tp:member>
  87   <tp:member type="o" tp:name="source">
  88   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  89     <p>The Accessible object which is the source of the event.  The source object is the object
  90       to which the change inferred by the event emission occurs; for instance,
  91       the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
  92       Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
  93       not the inserted child.</p>
  94   </tp:docstring>
  95   </tp:member>
  96   <tp:member type="i" tp:name="detail1">
  97   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  98     <p>An integer whose meaning is event type dependent.  It may indicate the offset of
  99       text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
 100       newly added child in the case of ¨object:children-changed:add¨.
 101       @note since most AT-SPI clients react to events via an asynchronous queue, for
 102       performance reasons, this field may be of limited utility unless the client maintains
 103       a large client-side cache of the hierarchy and contained data.  This is because by the time
 104       such an event is asynchronously processed, the state of the originating object may have
 105       changed.  In other words, the data in the detail1 member is not state-coherent outside
 106       of the event handler.  More useful results are gotten by examination of the 'any_data' field.</p>
 107   </tp:docstring>
 108   </tp:member>
 109   <tp:member type="i" tp:name="detail2">
 110   <tp:docstring>
 111     see description of detail2
 112   </tp:docstring>
 113   </tp:member>
 114   <tp:member type="v" tp:name="any_data">
 115   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 116     <p>A generic storage location for event-type-specific data which provides more specific
 117       information about the event; for instance, in AT-SPI versions prior to 1.7.0,
 118       in the case of ¨object:text-changed:insert¨ events, this field contains a string
 119       indicating the inserted text.  </p>
 120
 121     <p>@note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.</p>
 122   </tp:docstring>
 123   </tp:member>
 124 </tp:struct>
 125 <interface name="org.freedesktop.accessibility.EventListener">
 126   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 127     <p>A generic interface implemented by objects for the
 128       receipt of event notifications.  EventListener is the interface from which
 129       Accessibility::Registry is derived, and via which clients of the Registry
 130       receive notification of changes to an application's user interface and content.</p>
 131   </tp:docstring>
 132   <method name="notifyEvent">
 133     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 134       <p>Synchronously notify an EventListener that an event has occurred, by passing it an
 135         Event struct.
 136         @param e The Event about which the listener is being notified.</p>
 137     </tp:docstring>
 138     <arg direction="in" name="e" type="(soiiv)" tp:type="Event"/>
 139   </method>
 140   <method name="unImplemented_">
 141     <tp:docstring>
 142       \cond
 143     </tp:docstring>
 144   </method>
 145   <method name="unImplemented2_">
 146   </method>
 147   <method name="unImplemented3_">
 148   </method>
 149   <method name="unImplemented4_">
 150   </method>
 151 </interface>
 152 </node>