2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001, 2002 Sun Microsystems Inc.,
6 * Copyright 2001, 2002 Ximian, Inc.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
24 #ifndef _SPI_LISTENER_H_
25 #define _SPI_LISTENER_H_
27 #include <cspi/spi-impl.h>
35 * @type: a string representing the type of the event, with increasing specificity
36 * from left to right, delimited by colons. Leftmost token represents event source type,
37 * next token represents event category, and next token represents the subcategory
38 * of the event, for instance the specific property, state, or attribute being notified.
39 * @source: The #Accessible from which the event originated.
40 * @detail1: an event-type-specific integer value.
41 * @detail2: an event-type-specific integer value.
43 * A structure used to encapsulate event information.
53 *AccessibleDeviceEventType:
54 *@SPI_KEY_PRESSED: A device key has been pressed.
55 *@SPI_KEY_RELEASED: A device key has been released.
56 *@SPI_BUTTON_PRESSED: A device button or switch (other than a keyboard key)
58 *@SPI_BUTTON_RELEASED: A device button or switch has been released.
60 *The type of an AccessibleDeviceEvent.
63 SPI_KEY_PRESSED = 1<<0,
64 SPI_KEY_RELEASED = 1<<1,
65 SPI_BUTTON_PRESSED = 1<<2,
66 SPI_BUTTON_RELEASED = 1<<3
67 } AccessibleDeviceEventType;
70 *AccessibleKeyEventType:
72 *This is a synonym for AccessibleDeviceEventType
74 typedef AccessibleDeviceEventType AccessibleKeyEventType;
77 * AccessibleDeviceEvent:
78 * @keyID: Symbolic representation for the key or switch generating the event, e.g. keysym or button number.
79 * @keystring: A symbolic name for the key or switch, or, if is_text is true, a string approximating the
80 * inserted text characters which would result from this event, if a text entry field has keyboard focus.
81 * @timestamp: A time in ms when this event occurred, relative to some unspecified starting point.
82 * Timestamp values should therefore be used to compare events but should not be tested against a
84 * @type: The #AccessibleDeviceEventType identifying the specific type of event.
85 * @is_text: A boolean value indicating whether the event represents 'printable' text (i.e. whether it
86 * changes the current insertion buffer of a focussed text entry component or not). Whitespace
87 * is considered "printable" in this context, since it typically inserts characters into the buffer.
89 * A structure encapsulating information relevant to a device event notification.
96 AccessibleDeviceEventType type;
97 unsigned short modifiers;
99 } AccessibleDeviceEvent;
101 typedef AccessibleDeviceEvent AccessibleKeystroke;
104 * Function prototype typedefs for Event Listener Callbacks.
105 * (see libspi/accessibleeventlistener.h for definition of SpiVoidEventListenerCB).
107 * usage: signatures should be
108 * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
110 * SPIBoolean (*AccessibleKeystrokeListenerCB) (AccessibleKeystrokeEvent *Event);
111 * Note that AccessibleKeystrokeListeners may consume the event received
112 * if one of their callbacks returns TRUE (see SPI_registerAccessibleKeystrokeListener)
116 * AccessibleEventListenerCB:
117 * @event: The event for which notification is sent.
118 * @user_data: User data which is passed to the callback each time a notification takes place.
120 * A function prototype for callbacks via which clients are notified of AT-SPI events.
123 typedef void (*AccessibleEventListenerCB) (const AccessibleEvent *event,
126 * AccessibleKeystrokeListenerCB:
127 * @stroke: the #AccessibleKeystroke event for which notification is taking place.
128 * @user_data: data passed to the callback each time it is notified, according to the data
129 * which was passed in when the listener/callback was registered.
131 * A function prototype for a callback function called when a key event notification takes place.
133 * Returns: %TRUE if the client wishes to consume the event and prevent its
134 * dispatch to other listeners or the currently focussed application, if
135 * the relevant callback was registered with the #SPI_KEYLISTENER_CANCONSUME flag.
137 typedef SPIBoolean (*AccessibleKeystrokeListenerCB) (const AccessibleKeystroke *stroke,
140 * AccessibleDeviceListenerCB:
141 * @stroke: The #AccessibleDeviceEvent for which notification is being received.
142 * @user_data: Data which is passed to the client each time this callback is notified.
144 * A callback function prototype via which clients receive device event notifications.
146 * Returns: %TRUE if the client wishes to consume/preempt the event, preventing it from being
147 * relayed to the currently focussed application, %FALSE if the event delivery should proceed as normal.
149 typedef SPIBoolean (*AccessibleDeviceListenerCB) (const AccessibleDeviceEvent *stroke,