1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
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>
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>
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>
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>
32 <p>@since AT-SPI 1.7.0</p>
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"/>
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>
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>
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
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>
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,
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 "keyboard:" 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>
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>
84 <p>@see Accessible, Component, Image, Selection, Table, Text, Value.</p>
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>
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>
109 <tp:member type="i" tp:name="detail2">
111 see description of detail2
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>
121 <p>@note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.</p>
125 <interface name="org.freedesktop.atspi.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>
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
136 @param e The Event about which the listener is being notified.</p>
138 <arg direction="in" name="e" type="(soiiv)" tp:type="Event"/>
140 <method name="unImplemented_">
145 <method name="unImplemented2_">
147 <method name="unImplemented3_">
149 <method name="unImplemented4_">