cspi/spi-listener.h

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001, 2002 Sun Microsystems Inc.,
   6  * Copyright 2001, 2002 Ximian, Inc.
   7  *
   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.
  12  *
  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.
  17  *
  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.
  22  */
  23
  24 #ifndef _SPI_LISTENER_H_
  25 #define _SPI_LISTENER_H_
  26
  27 #include <cspi/spi-impl.h>
  28 #include <glib-object.h>
  29 #include "common/spi-types.h"
  30
  31 #ifdef  __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 typedef enum
  36 {
  37   EVENT_DATA_STRING,
  38   EVENT_DATA_OBJECT,
  39   EVENT_DATA_RECT
  40 } EVENT_DATA_TYPE;
  41
  42 /**
  43  * AccessibleEvent:
  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.
  51  *
  52  * A structure used to encapsulate event information.
  53  **/
  54 typedef struct {
  55   const char  *type;
  56   Accessible  *source;
  57   long         detail1;
  58   long         detail2;
  59   EVENT_DATA_TYPE v_type;
  60   union
  61   {
  62     char *text;
  63     Accessible *accessible;
  64     SPIRect rect;
  65   } v;
  66 } AccessibleEvent;
  67
  68 /**
  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)
  73  * has been pressed.
  74  *@SPI_BUTTON_RELEASED: A device button or switch has been released.
  75  *
  76  *The type of an AccessibleDeviceEvent.
  77  **/
  78 typedef enum {
  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;
  84
  85 /**
  86  *AccessibleKeyEventType:
  87  *
  88  *This is a synonym for AccessibleDeviceEventType
  89  **/
  90 typedef AccessibleDeviceEventType AccessibleKeyEventType;
  91
  92 /**
  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
  99  * fixed time.
 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.
 104  *
 105  * A structure encapsulating information relevant to a device event notification.
 106  **/
 107 typedef struct {
 108   long                   keyID;
 109   short                  keycode;
 110   char *                 keystring;
 111   long                   timestamp;
 112   AccessibleDeviceEventType type;
 113   unsigned short         modifiers;
 114   SPIBoolean             is_text;
 115 } AccessibleDeviceEvent;
 116
 117 typedef AccessibleDeviceEvent AccessibleKeystroke;
 118
 119 /*
 120  * Function prototype typedefs for Event Listener Callbacks.
 121  * (see libspi/accessibleeventlistener.h for definition of SpiVoidEventListenerCB).
 122  *
 123  * usage: signatures should be
 124  * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
 125  *
 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)
 129  */
 130
 131 /**
 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.
 135  *
 136  * A function prototype for callbacks via which clients are notified of AT-SPI events.
 137  *
 138  **/
 139 typedef void       (*AccessibleEventListenerCB)     (const AccessibleEvent     *event,
 140                                                      void                      *user_data);
 141 /**
 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.
 146  *
 147  * A function prototype for a callback function called when a key event notification takes place.
 148  *
 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.
 152  **/
 153 typedef SPIBoolean (*AccessibleKeystrokeListenerCB) (const AccessibleKeystroke *stroke,
 154                                                      void                      *user_data);
 155 /**
 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.
 159  *
 160  * A callback function prototype via which clients receive device event notifications.
 161  *
 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.
 164  **/
 165 typedef SPIBoolean (*AccessibleDeviceListenerCB)    (const AccessibleDeviceEvent *stroke,
 166                                                      void                      *user_data);
 167
 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))
 174
 175 typedef struct {
 176         GObject parent;
 177         GList           *callbacks;
 178 } CSpiEventListener;
 179
 180 typedef struct {
 181   GObjectClass parent_class;
 182
 183   /* signals */
 184   void (*event) (CSpiEventListener    *listener,
 185                  AccessibleEvent *e);
 186 } CSpiEventListenerClass;
 187
 188 GType cspi_event_listener_get_type (void);
 189
 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))
 196
 197 typedef struct {
 198         GObject parent;
 199         guint id;
 200         GList            *callbacks;
 201 } CSpiDeviceListener;
 202
 203 typedef struct {
 204         GObjectClass parent_class;
 205         gboolean (*device_event) (CSpiDeviceListener *listener, const Accessibility_DeviceEvent *key);
 206 } CSpiDeviceListenerClass;
 207
 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,
 212                                   void                      *user_data);
 213 void cspi_device_listener_remove_cb (AccessibleDeviceListener  *al,
 214                                      AccessibleDeviceListenerCB callback);
 215 void cspi_device_listener_unref (AccessibleDeviceListener *listener);
 216 #ifdef  __cplusplus
 217 }
 218 #endif
 219
 220 #endif