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
  29 #ifdef  __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * AccessibleEvent:
  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.
  42  *
  43  * A structure used to encapsulate event information.
  44  **/
  45 typedef struct {
  46   const char  *type;
  47   Accessible  *source;
  48   long         detail1;
  49   long         detail2;
  50 } AccessibleEvent;
  51
  52 /**
  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)
  57  * has been pressed.
  58  *@SPI_BUTTON_RELEASED: A device button or switch has been released.
  59  *
  60  *The type of an AccessibleDeviceEvent.
  61  **/
  62 typedef enum {
  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;
  68
  69 /**
  70  *AccessibleKeyEventType:
  71  *
  72  *This is a synonym for AccessibleDeviceEventType
  73  **/
  74 typedef AccessibleDeviceEventType AccessibleKeyEventType;
  75
  76 /**
  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
  83  * fixed time.
  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.
  88  *
  89  * A structure encapsulating information relevant to a device event notification.
  90  **/
  91 typedef struct {
  92   long                   keyID;
  93   short                  keycode;
  94   char *                 keystring;
  95   long                   timestamp;
  96   AccessibleDeviceEventType type;
  97   unsigned short         modifiers;
  98   SPIBoolean             is_text;
  99 } AccessibleDeviceEvent;
 100
 101 typedef AccessibleDeviceEvent AccessibleKeystroke;
 102
 103 /*
 104  * Function prototype typedefs for Event Listener Callbacks.
 105  * (see libspi/accessibleeventlistener.h for definition of SpiVoidEventListenerCB).
 106  *
 107  * usage: signatures should be
 108  * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
 109  *
 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)
 113  */
 114
 115 /**
 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.
 119  *
 120  * A function prototype for callbacks via which clients are notified of AT-SPI events.
 121  *
 122  **/
 123 typedef void       (*AccessibleEventListenerCB)     (const AccessibleEvent     *event,
 124                                                      void                      *user_data);
 125 /**
 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.
 130  *
 131  * A function prototype for a callback function called when a key event notification takes place.
 132  *
 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.
 136  **/
 137 typedef SPIBoolean (*AccessibleKeystrokeListenerCB) (const AccessibleKeystroke *stroke,
 138                                                      void                      *user_data);
 139 /**
 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.
 143  *
 144  * A callback function prototype via which clients receive device event notifications.
 145  *
 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.
 148  **/
 149 typedef SPIBoolean (*AccessibleDeviceListenerCB)    (const AccessibleDeviceEvent *stroke,
 150                                                      void                      *user_data);
 151
 152 #ifdef  __cplusplus
 153 }
 154 #endif
 155
 156 #endif