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 <Accessibility_Event.idl>
  25 #include <Accessibility_Application.idl>
  26 #include <Accessibility_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          *
  43          * Register a new application with the accessibility broker.
  44          *
  45          **/
  46         oneway void registerApplication (in Application application);
  47
  48         /**
  49          * deregisterApplication:
  50          * @application: a reference to the @Application
  51          * to be deregistered.
  52          *
  53          * De-register an application previously registered with the broker.
  54          *
  55          **/
  56         void deregisterApplication (in Application application);
  57
  58         /**
  59          * registerGlobalEventListener:
  60          * @listener: a reference to the requesting @EventListener.
  61          * @eventName: a string which indicates the type of events about
  62          * which the client desires notification.
  63          *
  64          * Register a client's interest in (all) application events of
  65          * a certain type.
  66          *
  67          **/
  68         void registerGlobalEventListener (in EventListener listener,
  69                                           in string eventName);
  70
  71         /**
  72          * deregisterGlobalEventListener:
  73          * @listener: the requesting @EventListener
  74          * @eventName: a string indicating the type of events
  75          *
  76          * Request that a previously registered client stop receiving
  77          * global notifications for events of a certain type.
  78          *
  79          **/
  80
  81         void deregisterGlobalEventListenerAll (in EventListener listener);
  82         /**
  83          * deregisterGlobalEventListener:
  84          * @listener: the requesting @EventListener
  85          * @eventName: a string indicating the type of events
  86          *
  87          * Request that a previously registered client stop receiving
  88          * global notifications for events of a certain type.
  89          *
  90          **/
  91
  92         void deregisterGlobalEventListener (in EventListener listener,
  93                                             in string event_name);
  94         /**
  95          * event types: "Window" "Desktop"
  96          *              "Window:Create" "Window:Destroy"
  97          *              "Window:Iconify" "Window:Restore"
  98          *              "Window:Fullscreen" "Window:Resize"
  99          *              "Desktop:Create" "Desktop:Destroy"
 100          *              "Desktop:Focus" "Desktop:Defocus"
 101          *              "Desktop:Reorder"
 102          *              "Focus"
 103          *              "GtkWidget:show"
 104          *              "GObject:notify:<propertyname>"
 105          *
 106          *  ( not sure we should allow these last 2 forms,
 107          *    since they are toolkit-specific, but they're powerful )
 108          *
 109          **/
 110
 111         /**
 112          * getDesktopCount:
 113          *
 114          * Get the current number of desktops.
 115          * Returns: a short integer indicating the current number of
 116          * @Desktops.
 117          **/
 118         short getDesktopCount ();
 119
 120         /**
 121          * getDesktop:
 122          * @n: the index of the requested @Desktop.
 123          *
 124          * Get the nth accessible desktop.
 125          *
 126          * Returns: a reference to the requested @Desktop.
 127          **/
 128         Desktop getDesktop (in short n);
 129
 130         /**
 131          * getDesktopList:
 132          *
 133          * Get a list of accessible desktops.
 134          *
 135          * Returns: a sequence containing references to
 136          * the @Desktops.
 137          **/
 138         DesktopSeq getDesktopList ();
 139
 140         /**
 141          * getDeviceEventController:
 142          *
 143          * Returns: an object implementing DeviceEventController
 144          **/
 145         DeviceEventController getDeviceEventController ();
 146
 147         /**
 148          * unImplemented:
 149          *
 150          * placeholders for future expansion.
 151          */
 152         void unImplemented ();
 153         void unImplemented2 ();
 154         void unImplemented3 ();
 155         void unImplemented4 ();
 156         void unImplemented5 ();
 157         void unImplemented6 ();
 158     };
 159
 160   /* Deprecated, DO NOT USE! */
 161   enum KeyEventType {
 162     KEY_PRESSED,
 163     KEY_RELEASED
 164   };
 165
 166   enum EventType {
 167     KEY_PRESSED_EVENT,
 168     KEY_RELEASED_EVENT,
 169     BUTTON_PRESSED_EVENT,
 170     BUTTON_RELEASED_EVENT
 171   };
 172
 173   enum KeySynthType {
 174     KEY_PRESS,
 175     KEY_RELEASE,
 176     KEY_PRESSRELEASE,
 177     KEY_SYM,
 178     KEY_STRING
 179   };
 180
 181   enum ModifierType {
 182     MODIFIER_SHIFT,
 183     MODIFIER_SHIFTLOCK,
 184     MODIFIER_CONTROL,
 185     MODIFIER_ALT,
 186     MODIFIER_META,
 187     MODIFIER_META2,
 188     MODIFIER_META3,
 189     MODIFIER_NUMLOCK
 190   };
 191
 192   struct EventListenerMode {
 193     boolean synchronous;
 194     boolean preemptive;
 195     boolean global;
 196   };
 197
 198   typedef unsigned long ControllerEventMask;
 199
 200   struct DeviceEvent {
 201     EventType type;
 202     long  id;
 203     short hw_code;
 204     unsigned short modifiers;
 205     unsigned long timestamp;
 206     string event_string;
 207     boolean is_text;
 208   };
 209
 210   struct KeyDefinition {
 211     long keycode;
 212     long keysym;
 213     string keystring;
 214     long unused;
 215   };
 216
 217   typedef sequence< KeyDefinition > KeySet;
 218   typedef sequence< EventType > KeyEventTypeSeq;
 219   typedef sequence< EventType > EventTypeSeq;
 220
 221   interface DeviceEventListener : Bonobo::Unknown {
 222         boolean notifyEvent (in DeviceEvent event);
 223         void    unImplemented__ ();
 224         void    unImplemented_2_ ();
 225         void    unImplemented_3_ ();
 226         void    unImplemented_4_ ();
 227         void    unImplemented_5_ ();
 228         void    unImplemented_6_ ();
 229   };
 230
 231   interface DeviceEventController : Bonobo::Unknown {
 232
 233         /**
 234          * registerKeystrokeListener:
 235          * @listener: a @DeviceEventListener which will intercept key events.
 236          * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 237          * @mask:     a @ControllerEventMask filtering the intercepted key events.
 238          * @type:     an @EventType mask that may created by ORing event types together.
 239          * @is_synchronous: a @boolean indicating whether the listener should
 240          *            receive the events synchronously, potentially consuming them,
 241          *            or just be notified asynchronously of those events that have
 242          *            been generated.
 243          * Returns: %true if successful, %false if not
 244          *
 245          * Register to intercept keyboard events, and either pass them on or
 246          * consume them.
 247          *
 248          **/
 249         boolean registerKeystrokeListener (in DeviceEventListener listener,
 250                                         in KeySet keys,
 251                                         in ControllerEventMask mask,
 252                                         in KeyEventTypeSeq type,
 253                                         in EventListenerMode mode);
 254
 255         /**
 256          * deregisterKeystrokeListener:
 257          * @listener: a @DeviceEventListener which will intercept key events.
 258          * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 259          * @mask:     a @ControllerEventMask filtering the intercepted key events.
 260          * @type:     an @EventType mask that may created by ORing event types together.
 261          *
 262          * Returns: void
 263          *
 264          * De-register a previously registered keyboard eventlistener.
 265          *
 266          **/
 267         void deregisterKeystrokeListener (in DeviceEventListener listener,
 268                                           in KeySet keys,
 269                                           in ControllerEventMask mask,
 270                                           in KeyEventTypeSeq type);
 271
 272         /**
 273          * registerDeviceEventListener:
 274          * @listener: a @DeviceEventListener which will intercept events.
 275          * @typeseq:  an @EventTypeSeq indicating which event types to listen for.
 276          * Returns: %true if successful, %false if not
 277          *
 278          * Register to intercept events, and either pass them on or
 279          * consume them. To listen to keyboard events use registerKeystrokeListener
 280          * instead.
 281          *
 282          **/
 283         boolean registerDeviceEventListener (in DeviceEventListener listener,
 284                                              in EventTypeSeq typeseq);
 285
 286         /**
 287          * deregisterDeviceEventListener:
 288          * @listener: a @DeviceEventListener which will intercept events.
 289          * @typeseq:  an @EventTypeSeq indicating which event types to stop
 290          *            listening for.
 291          *
 292          * Returns: void
 293          *
 294          * De-register a previously registered keyboard eventlistener.
 295          *
 296          **/
 297         void deregisterDeviceEventListener (in DeviceEventListener listener,
 298                                             in EventTypeSeq typeseq);
 299
 300         boolean notifyListenersSync (in DeviceEvent event);
 301
 302         oneway void notifyListenersAsync (in DeviceEvent event);
 303
 304         /**
 305          * generateKeyboardEvent:
 306          * @keycode: a long integer indicating the keycode of
 307          *          the keypress to be synthesized.
 308          * @keystring: an optional UTF-8 string indicating a complex
 309          *          keyboard input event.
 310          * @type: a #KeySynthType indicating the type of event(s) to be
 311          *          synthesized: a key press, release, press-release pair,
 312          *          or a complex input string (for instance from an
 313          *          internationalized or complex text input method, or
 314          *          a composed character).
 315          *
 316          * Note that @keycode may be truncated before being
 317          *          processed, as keycode length may be platform-dependent
 318          *          and keycode ranges are generally much smaller than
 319          *          CORBA_long.
 320          * One or the other of @keycode or @keystring are generally NULL,
 321          *          (but not both), depending on the value of @type.
 322          *
 323          * Returns: void
 324          *
 325          * Synthesize a keyboard event.
 326          *
 327          **/
 328          void generateKeyboardEvent (in long keycode,
 329                                      in string keystring,
 330                                      in KeySynthType type);
 331
 332         /**
 333          * generateMouseEvent:
 334          * @x: a long integer indicating the screen x coord for the mouse event.
 335          * @y: a long integer indicating the screen y coord for the mouse event.
 336          * @eventName: a string indicating the type of mouse event, e.g. "button1up"
 337          * Returns: void
 338          *
 339          * Synthesize a mouse event.
 340          *
 341          **/
 342          void generateMouseEvent (in long x, in long y, in string eventName);
 343
 344          /**
 345           * unImplemented:
 346           *
 347           * placeholders for future expansion.
 348           */
 349          void unImplemented ();
 350          void unImplemented2 ();
 351          void unImplemented3 ();
 352          void unImplemented4 ();
 353     };
 354 };
 355
 356 #endif