idl/Accessibility_Registry.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems Inc.
   6  *
   7  * 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.
  11  *
  12  * 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.
  16  *
  17  * 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.
  21  */
  22
  23 #include <Bonobo_Unknown.idl>
  24 #include <Event.idl>
  25 #include <Application.idl>
  26 #include <Desktop.idl>
  27
  28 #ifndef _ACCESSIBILITY_REGISTRY_IDL_
  29 #define _ACCESSIBILITY_REGISTRY_IDL_
  30
  31 module Accessibility {
  32
  33   typedef sequence<Desktop> DesktopSeq;
  34
  35   interface DeviceEventController;
  36
  37   interface Registry : EventListener {
  38
  39         /**
  40          * registerApplication:
  41          * @application: a reference to the requesting @Application
  42          * return values: void
  43          *
  44          * Register a new application with the accessibility broker.
  45          *
  46          **/
  47         oneway void registerApplication (in Application application);
  48
  49         /**
  50          * deregisterApplication:
  51          * @application: a reference to the @Application
  52          * to be deregistered.
  53          * return values: void
  54          *
  55          * De-register an application previously registered with the broker.
  56          *
  57          **/
  58         void deregisterApplication (in Application application);
  59
  60         /**
  61          * registerGlobalEventListener:
  62          * @listener: a reference to the requesting @EventListener.
  63          * @eventName: a string which indicates the type of events about
  64          * which the client desires notification.
  65          * return values: void
  66          *
  67          * Register a client's interest in (all) application events of
  68          * a certain type.
  69          *
  70          **/
  71         void registerGlobalEventListener (in EventListener listener,
  72                                            in string eventName);
  73
  74         /**
  75          * deregisterGlobalEventListener:
  76          * @listener: the requesting @EventListener
  77          * @eventName: a string indicating the type of events
  78          * return values: void
  79          *
  80          * Request that a previously registered client stop receiving
  81          * global notifications for events of a certain type.
  82          *
  83          **/
  84
  85         void deregisterGlobalEventListenerAll (in EventListener listener);
  86         /**
  87          * deregisterGlobalEventListener:
  88          * @listener: the requesting @EventListener
  89          * @eventName: a string indicating the type of events
  90          * return values: void
  91          *
  92          * Request that a previously registered client stop receiving
  93          * global notifications for events of a certain type.
  94          *
  95          **/
  96
  97         void deregisterGlobalEventListener (in EventListener listener,
  98                                             in string event_name);
  99         /**
 100          * event types: "Window" "Desktop"
 101          *              "Window:Create" "Window:Destroy"
 102          *              "Window:Iconify" "Window:Restore"
 103          *              "Window:Fullscreen" "Window:Resize"
 104          *              "Desktop:Create" "Desktop:Destroy"
 105          *              "Desktop:Focus" "Desktop:Defocus"
 106          *              "Desktop:Reorder"
 107          *              "Focus"
 108          *              "GtkWidget:show"
 109          *              "GObject:notify:<propertyname>"
 110          *
 111          *  ( not sure we should allow these last 2 forms,
 112          *    since they are toolkit-specific, but they're powerful )
 113          *
 114          **/
 115
 116         /**
 117          * getDesktopCount:
 118          * return values: a short integer indicating the current number of
 119          * @Desktops.
 120          *
 121          * Get the current number of desktops.
 122          *
 123          **/
 124         short getDesktopCount ();
 125
 126         /**
 127          * getDesktop:
 128          * @n: the index of the requested @Desktop.
 129          * return values: a reference to the requested @Desktop.
 130          *
 131          * Get the nth accessible desktop.
 132          *
 133          **/
 134         Desktop getDesktop (in short n);
 135
 136         /**
 137          * getDesktopList:
 138          * return values: a sequence containing references to
 139          * the @Desktops.
 140          *
 141          * Get a list of accessible desktops.
 142          *
 143          **/
 144         DesktopSeq getDesktopList ();
 145
 146         /**
 147          * getDeviceEventController:
 148          * return values: an object implementing DeviceEventController
 149          *
 150          **/
 151         DeviceEventController getDeviceEventController ();
 152
 153     };
 154
 155   enum KeyEventType {
 156     KEY_PRESSED,
 157     KEY_RELEASED
 158   };
 159
 160   enum EventType {
 161     KEY_PRESSED_EVENT,
 162     KEY_RELEASED_EVENT
 163   };
 164
 165   enum KeySynthType {
 166     KEY_PRESS,
 167     KEY_RELEASE,
 168     KEY_PRESSRELEASE,
 169     KEY_SYM
 170   };
 171
 172   enum ModifierType {
 173     MODIFIER_SHIFT,
 174     MODIFIER_ALT,
 175     MODIFIER_CONTROL,
 176     MODIFIER_META,
 177     MODIFIER_META2,
 178     MODIFIER_META3,
 179     MODIFIER_SHIFTLOCK,
 180     MODIFIER_NUMLOCK
 181   };
 182
 183   struct ControllerEventMask {
 184     unsigned long value;
 185     unsigned short refcount;
 186   };
 187
 188   struct KeyStroke {
 189     long keyID;
 190     short keycode;
 191     unsigned long timestamp;
 192     KeyEventType type;
 193     unsigned short modifiers;
 194   };
 195
 196   struct DeviceEvent {
 197     long eventID;
 198     short hw_code;
 199     unsigned long timestamp;
 200     EventType type;
 201     unsigned short modifiers;
 202   };
 203
 204   typedef sequence< long > KeySet;
 205   typedef sequence< KeyEventType > KeyEventTypeSeq;
 206
 207   interface KeystrokeListener : Bonobo::Unknown {
 208         boolean keyEvent (in KeyStroke key);
 209   };
 210
 211   interface DeviceEventListener : Bonobo::Unknown {
 212         boolean notifyEvent (in DeviceEvent event);
 213   };
 214
 215   interface DeviceEventController : Bonobo::Unknown {
 216
 217         /**
 218          * registerKeystrokeListener:
 219          * @listener: a @KeystrokeListener which will intercept key events.
 220          * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 221          * @mask:     a @ControllerEventMask filtering the intercepted key events.
 222          * @type:     an @EventType mask that may created by ORing event types together.
 223          * @is_synchronous: a @boolean indicating whether the listener should
 224          *            receive the events synchronously, potentially consuming them,
 225          *            or just be notified asynchronously of those events that have
 226          *            been generated.
 227          * Returns: void
 228          *
 229          * Register to intercept keyboard events, and either pass them on or
 230          * consume them.
 231          *
 232          **/
 233         void registerKeystrokeListener (in KeystrokeListener listener,
 234                                         in KeySet keys,
 235                                         in ControllerEventMask mask,
 236                                         in KeyEventTypeSeq type,
 237                                         in boolean is_synchronous);
 238
 239         /**
 240          * deregisterKeystrokeListener:
 241          * @listener: a @KeystrokeListener which will intercept key events.
 242          * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 243          * @mask:     a @ControllerEventMask filtering the intercepted key events.
 244          * @type:     an @EventType mask that may created by ORing event types together.
 245          * @is_synchronous: a @boolean indicating whether the listener should
 246          *            receive the events synchronously, potentially consuming them,
 247          *            or just be notified asynchronously of those events that have
 248          *            been generated.
 249          * Returns: void
 250          *
 251          * De-register a previously registered keyboard eventlistener.
 252          *
 253          **/
 254         void deregisterKeystrokeListener (in KeystrokeListener listener,
 255                                         in KeySet keys,
 256                                         in ControllerEventMask mask,
 257                                         in KeyEventTypeSeq type,
 258                                         in boolean is_synchronous);
 259
 260         boolean notifyListenersSync (in DeviceEventListener listener,
 261                                      in DeviceEvent event);
 262
 263         oneway void notifyListenersAsync (in DeviceEventListener listener,
 264                                           in DeviceEvent event);
 265
 266         /**
 267          * generateKeyEvent:
 268          * @keycode: a long integer indicating the keycode of
 269          *          the keypress to be synthesized.
 270          *
 271          * Note that this long may be truncated before being
 272          *          processed, as keycode length may be platform-dependent
 273          *          and keycode ranges are generally much smaller than
 274          *          CORBA_long.
 275          *
 276          * Returns: void
 277          *
 278          * Synthesize a keypress event.
 279          *
 280          **/
 281          void generateKeyEvent (in long keycode, in KeySynthType type);
 282
 283         /**
 284          * generateMouseEvent:
 285          * @x: a long integer indicating the screen x coord for the mouse event.
 286          * @y: a long integer indicating the screen y coord for the mouse event.
 287          * @eventName: a string indicating the type of mouse event, e.g. "button1up"
 288          * Returns: void
 289          *
 290          * Synthesize a mouse event.
 291          *
 292          **/
 293          void generateMouseEvent (in long x, in long y, in string eventName);
 294     };
 295 };
 296
 297 #endif