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>
28 #include <glib-object.h>
29 #include "common/spi-types.h"
44 * @type: a string representing the type of the event, with increasing specificity
45 * from left to right, delimited by colons. Leftmost token represents event source type,
46 * next token represents event category, and next token represents the subcategory
47 * of the event, for instance the specific property, state, or attribute being notified.
48 * @source: The #Accessible from which the event originated.
49 * @detail1: an event-type-specific integer value.
50 * @detail2: an event-type-specific integer value.
52 * A structure used to encapsulate event information.
59 EVENT_DATA_TYPE v_type;
63 Accessible *accessible;
69 *AccessibleDeviceEventType:
70 *@SPI_KEY_PRESSED: A device key has been pressed.
71 *@SPI_KEY_RELEASED: A device key has been released.
72 *@SPI_BUTTON_PRESSED: A device button or switch (other than a keyboard key)
74 *@SPI_BUTTON_RELEASED: A device button or switch has been released.
76 *The type of an AccessibleDeviceEvent.
79 SPI_KEY_PRESSED = 1<<0,
80 SPI_KEY_RELEASED = 1<<1,
81 SPI_BUTTON_PRESSED = 1<<2,
82 SPI_BUTTON_RELEASED = 1<<3
83 } AccessibleDeviceEventType;
86 *AccessibleKeyEventType:
88 *This is a synonym for AccessibleDeviceEventType
90 typedef AccessibleDeviceEventType AccessibleKeyEventType;
93 * AccessibleDeviceEvent:
94 * @keyID: Symbolic representation for the key or switch generating the event, e.g. keysym or button number.
95 * @keystring: A symbolic name for the key or switch, or, if is_text is true, a string approximating the
96 * inserted text characters which would result from this event, if a text entry field has keyboard focus.
97 * @timestamp: A time in ms when this event occurred, relative to some unspecified starting point.
98 * Timestamp values should therefore be used to compare events but should not be tested against a
100 * @type: The #AccessibleDeviceEventType identifying the specific type of event.
101 * @is_text: A boolean value indicating whether the event represents 'printable' text (i.e. whether it
102 * changes the current insertion buffer of a focussed text entry component or not). Whitespace
103 * is considered "printable" in this context, since it typically inserts characters into the buffer.
105 * A structure encapsulating information relevant to a device event notification.
112 AccessibleDeviceEventType type;
113 unsigned short modifiers;
115 } AccessibleDeviceEvent;
117 typedef AccessibleDeviceEvent AccessibleKeystroke;
120 * Function prototype typedefs for Event Listener Callbacks.
121 * (see libspi/accessibleeventlistener.h for definition of SpiVoidEventListenerCB).
123 * usage: signatures should be
124 * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
126 * SPIBoolean (*AccessibleKeystrokeListenerCB) (AccessibleKeystrokeEvent *Event);
127 * Note that AccessibleKeystrokeListeners may consume the event received
128 * if one of their callbacks returns TRUE (see SPI_registerAccessibleKeystrokeListener)
132 * AccessibleEventListenerCB:
133 * @event: The event for which notification is sent.
134 * @user_data: User data which is passed to the callback each time a notification takes place.
136 * A function prototype for callbacks via which clients are notified of AT-SPI events.
139 typedef void (*AccessibleEventListenerCB) (const AccessibleEvent *event,
142 * AccessibleKeystrokeListenerCB:
143 * @stroke: the #AccessibleKeystroke event for which notification is taking place.
144 * @user_data: data passed to the callback each time it is notified, according to the data
145 * which was passed in when the listener/callback was registered.
147 * A function prototype for a callback function called when a key event notification takes place.
149 * Returns: %TRUE if the client wishes to consume the event and prevent its
150 * dispatch to other listeners or the currently focussed application, if
151 * the relevant callback was registered with the #SPI_KEYLISTENER_CANCONSUME flag.
153 typedef SPIBoolean (*AccessibleKeystrokeListenerCB) (const AccessibleKeystroke *stroke,
156 * AccessibleDeviceListenerCB:
157 * @stroke: The #AccessibleDeviceEvent for which notification is being received.
158 * @user_data: Data which is passed to the client each time this callback is notified.
160 * A callback function prototype via which clients receive device event notifications.
162 * Returns: %TRUE if the client wishes to consume/preempt the event, preventing it from being
163 * relayed to the currently focussed application, %FALSE if the event delivery should proceed as normal.
165 typedef SPIBoolean (*AccessibleDeviceListenerCB) (const AccessibleDeviceEvent *stroke,
168 #define CSPI_EVENT_LISTENER_TYPE (cspi_event_listener_get_type ())
169 #define CSPI_EVENT_LISTENER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), CSPI_EVENT_LISTENER_TYPE, CSpiEventListener))
170 #define CSPI_EVENT_LISTENER_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), CSPI_EVENT_LISTENER_TYPE, CSpiEventListenerClass))
171 #define CSPI_IS_EVENT_LISTENER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), CSPI_EVENT_LISTENER_TYPE))
172 #define CSPI_IS_EVENT_LISTENER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), CSPI_EVENT_LISTENER_TYPE))
173 #define CSPI_EVENT_LISTENER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CSPI_EVENT_LISTENER_TYPE, CSpiEventListenerClass))
181 GObjectClass parent_class;
184 void (*event) (CSpiEventListener *listener,
186 } CSpiEventListenerClass;
188 GType cspi_event_listener_get_type (void);
190 #define CSPI_DEVICE_LISTENER_TYPE (cspi_device_listener_get_type ())
191 #define CSPI_DEVICE_LISTENER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), CSPI_DEVICE_LISTENER_TYPE, CSpiDeviceListener))
192 #define CSPI_DEVICE_LISTENER_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), CSPI_DEVICE_LISTENER_TYPE, CSpiDeviceListenerClass))
193 #define CSPI_IS_DEVICE_LISTENER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), CSPI_DEVICE_LISTENER_TYPE))
194 #define CSPI_IS_DEVICE_LISTENER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), CSPI_DEVICE_LISTENER_TYPE))
195 #define CSPI_DEVICE_LISTENER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CSPI_DEVICE_LISTENER_TYPE, CSpiDeviceListenerClass))
201 } CSpiDeviceListener;
204 GObjectClass parent_class;
205 gboolean (*device_event) (CSpiDeviceListener *listener, const Accessibility_DeviceEvent *key);
206 } CSpiDeviceListenerClass;
208 GType cspi_device_listener_get_type (void);
209 gpointer cspi_device_listener_new (void);
210 void cspi_device_listener_add_cb (AccessibleDeviceListener *al,
211 AccessibleDeviceListenerCB callback,
213 void cspi_device_listener_remove_cb (AccessibleDeviceListener *al,
214 AccessibleDeviceListenerCB callback);
215 void cspi_device_listener_unref (AccessibleDeviceListener *listener);