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     /**
  38      * The Registry is a service through which applications providing
  39      * accessibility services (servers) can rendezvous with consumers of those
  40      * services (Assistive Technologies).  The Registry is the first "port of call" for
  41      * accessible applications and for assistive technologies wishing to query and
  42      * interact with those applications.
  43      *
  44      * The Registry service provides four basic functions to Assistive Technology (AT) clients:
  45      * \li it provides a list of the applications who have registered with the AT-SPI
  46      * framework, thereby announcing their participation in the AT-SPI framework;
  47      * \li it allows AT clients to register for notification of changes in application
  48      * state (at-spi Events);
  49      * \li it dispatches/relays said events from participating applications to
  50      * the registered listeners;
  51      * \li it gives access to system device events via the associated DeviceEventController
  52      * interface.
  53      *
  54      * From the point of view of accessible applications (i.e. AT-SPI service producers),
  55      * the Registry is primarily a registration and event delivery service.  Applications
  56      * normally only call the registerApplication and deregisterApplication Registry methods,
  57      * and its inherited EventListener::notifyEvent method.
  58      *
  59      * @note Although all application events are dispatched via the Registry, other AT client
  60      * calls are serviced directly by the applications, rather than being relayed via the
  61      * Registry.  The AT client obtains references to these application objects
  62      * via the enumeration of Desktop instances whose children are Application instances
  63      * (Registry::getDesktopList) and via examination of the 'source' member of the Event
  64      * structure.
  65      *
  66      * The Registry normally lives in its own process space; communication via Registry and
  67      * both application services and AT clients takes place via IPC.  A process space diagram
  68      * illustrating the relationship between applications, Registry, and AT is shown below.
  69      * @image html "http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png"
  70      *
  71      *
  72      * @see Desktop, Application, Event, EventListener
  73      **/
  74   interface Registry : EventListener {
  75
  76         /**
  77          * Register a new application with the accessibility broker.
  78          * @param application: a reference to the requesting Application
  79          **/
  80         oneway void registerApplication (in Application application);
  81
  82         /**
  83          * De-register an application previously registered with the broker.
  84          * deregisterApplication:
  85          * @param application: a reference to the Application
  86          * to be deregistered.
  87          **/
  88         void deregisterApplication (in Application application);
  89
  90         /**
  91          * Register a client's interest in (all) application events of
  92          * a certain type.
  93          * @param listener: a reference to the requesting ::EventListener.
  94          * @param eventName: a string which indicates the type of events about
  95          * which the client desires notification.
  96          **/
  97         void registerGlobalEventListener (in EventListener listener,
  98                                           in string eventName);
  99
 100         /**
 101          * deregisterGlobalEventListenerAll:
 102          * @param listener: the requesting EventListener
 103          *
 104          * Request that a previously registered client stop receiving
 105          * global notifications for all events for which it was registered.
 106          *
 107          **/
 108         void deregisterGlobalEventListenerAll (in EventListener listener);
 109
 110         /**
 111          * deregisterGlobalEventListener:
 112          * @param listener: the requesting EventListener
 113          * @param eventName: a string indicating the type of events
 114          *
 115          * Request that a previously registered client stop receiving
 116          * global notifications for events of a certain type.
 117          *
 118          **/
 119         void deregisterGlobalEventListener (in EventListener listener,
 120                                             in string eventName);
 121         /**
 122          * event types: "Window" "Desktop"
 123          *              "Window:Create" "Window:Destroy"
 124          *              "Window:Iconify" "Window:Restore"
 125          *              "Window:Fullscreen" "Window:Resize"
 126          *              "Desktop:Create" "Desktop:Destroy"
 127          *              "Desktop:Focus" "Desktop:Defocus"
 128          *              "Desktop:Reorder"
 129          *              "Focus"
 130          *              "GtkWidget:show"
 131          *              "GObject:notify:<propertyname>"
 132          *
 133          *  ( not sure we should allow these last 2 forms,
 134          *    since they are toolkit-specific, but they're powerful )
 135          *
 136          **/
 137
 138         /**
 139          * getDesktopCount:
 140          *
 141          * Get the current number of desktops.
 142          * @returns a short integer indicating the current number of
 143          * Desktops.
 144          **/
 145         short getDesktopCount ();
 146
 147         /**
 148          * getDesktop:
 149          * @n: the index of the requested Desktop.
 150          *
 151          * Get the nth accessible desktop.
 152          *
 153          * @returns a reference to the requested Desktop.
 154          **/
 155         Desktop getDesktop (in short n);
 156
 157         /**
 158          * Get a list of accessible desktops.
 159          *
 160          * @returns: a sequence containing references to
 161          * the Desktops.
 162          **/
 163         DesktopSeq getDesktopList ();
 164
 165         /**
 166          * Obtain an object which can be used to request device event notifications.
 167          *
 168          * @returns: an object implementing DeviceEventController
 169          **/
 170         DeviceEventController getDeviceEventController ();
 171
 172         /** \cond
 173          * unImplemented:
 174          *
 175          * placeholders for future expansion.
 176          */
 177         void unImplemented ();
 178         void unImplemented2 ();
 179         void unImplemented3 ();
 180         void unImplemented4 ();
 181         void unImplemented5 ();
 182         void unImplemented6 ();
 183       /** \endcond */
 184     };
 185
 186     /** Deprecated, DO NOT USE! */
 187   enum KeyEventType {
 188     KEY_PRESSED,
 189     KEY_RELEASED
 190   };
 191
 192   /** Used to specify the event types of interest to an EventListener, or
 193    * to identify the type of an event for which notification has been sent.
 194    * @see EventTypeSeq, DeviceEvent::type
 195    */
 196   enum EventType {
 197       KEY_PRESSED_EVENT, /**< key on a keyboard device was pressed. */
 198       KEY_RELEASED_EVENT, /**< key on a keyboard device was released. */
 199       BUTTON_PRESSED_EVENT,/**< button on a non-keyboard human interface device
 200                             * (HID) was pressed */
 201       BUTTON_RELEASED_EVENT /**< button on a non-keyboard human interface device
 202                              * (HID) was pressed */
 203   };
 204
 205     /** Used when synthesizing keyboard input via DeviceEventController:generateKeyboardEvent.*/
 206   enum KeySynthType {
 207     KEY_PRESS,/** emulate the pressing of a hardware keyboard key. */
 208     KEY_RELEASE,/** emulate the release of a hardware keyboard key. */
 209     KEY_PRESSRELEASE,/** a hardware keyboard key is pressed and immediately released. */
 210     KEY_SYM,/** a symbolic key event is generated, without specifying a hardware key.
 211              * @note if the keysym is not present in the current keyboard map,
 212              * the DeviceEventController instance has a limited ability to generate
 213              * such keysyms on-the-fly.  Reliability of generateKeyboardEvent calls
 214              * using out-of-keymap keysyms will vary from system to system, and on the
 215              * number of different out-of-keymap being generated in quick succession.
 216              * In practice this is rarely significant, since the keysyms of interest to
 217              * AT clients and keyboard emulators are usually part of the current keymap, i.e.
 218              * present on the system keyboard for the current locale (even if a physical
 219              * hardware keyboard is not connected.
 220              */
 221     KEY_STRING /** a string is converted to its equivalent keyboard events and emitted.
 222                 * If the string consists of complex character or composed characters
 223                 * which are not in the current keymap, string emission is subject to the
 224                 * out-of-keymap limitations described for KeySynthType::KEY_SYM.
 225                 * In practice this limitation primarily effects Chinese and Japanese locales.
 226                 */
 227   };
 228
 229   enum ModifierType {
 230     MODIFIER_SHIFT, /** The left or right 'Shift' key */
 231     MODIFIER_SHIFTLOCK, /** The ShiftLock or CapsLock key */
 232     MODIFIER_CONTROL,/** 'Control'/'Ctrl' */
 233     MODIFIER_ALT,/** The Alt key (as opposed to AltGr) */
 234     MODIFIER_META,/** depending on the platform this may map to 'Window', 'Function', 'Meta',
 235                    * 'Menu', or 'NumLock'.
 236                    *  Such 'Meta keys' will map to one of META, META2, META3.
 237                    * On X Windows platforms these META values map to
 238                    * the modifier masks Mod1Mask, Mod2Mask, Mod3Mask, e.g. an event having
 239                    * ModifierType::MODIFIER_META2 means that the 'Mod2Mask' bit is
 240                    * set in the corresponding XEvent.
 241                    */
 242     MODIFIER_META2,
 243     MODIFIER_META3,
 244     MODIFIER_NUMLOCK/** A symbolic meta key name that is mapped by AT-SPI to the
 245                      *  appropriate META value, for the convenience of the client.
 246                      */
 247   };
 248
 249   /** A structure that encapsulates the characteristics of the event notifications
 250    * that should be sent to an EventListener in response to a call to
 251    * DeviceEventController::registerKeystrokeListener or
 252    * DeviceEventController::registerDeviceEventListener. */
 253   struct EventListenerMode {
 254     boolean synchronous; /**< If \c True, specifies that
 255                           * DeviceEventController should block while waiting
 256                           * for client to process the requested event notifications;
 257                           * ordinarily should be used only when client needs to perform
 258                           * operations synchronously with event delivery. Note that because
 259                           * of the architecture of device event systems in general,
 260                           * use of this flag may not block delivery of the event to
 261                           * the currently focussed application unless it is used in
 262                           * conjunction with the preemptive flag. */
 263     boolean preemptive; /**< If \c True, specifies that
 264                          * Listener is allowed to pre-empt the delivery of the event,
 265                          * effectively "consuming" it such that it is not delivered
 266                          * to the currently focussed desktop application.
 267                          * Key events consumed via this API will not be
 268                          * available for use by other applications or services, so this
 269                          * option should be used sparingly. */
 270     boolean global; /**< If \c True, specifies that
 271                      * Event notifications should be sent regardless of whether the
 272                      * currently focussed application participates in the AT-SPI
 273                      * infrastructure.  On systems with the XEvIE X extension, this flag
 274                      * also allows access to events which are already subject to
 275                      * interception via a "system keygrab" (as described in the X Window System
 276                      * documentation for XGrabKey).  The 'global' and 'preemptive' flags
 277                      * should only be used together for the purposes of registering
 278                      * "system global key shortcuts" i.e. command keys for use by the
 279                      * assistive technology. */
 280   };
 281
 282   /**
 283    * an unsigned short int consisting of zero or more of the following
 284    * values OR'ed together:
 285    *
 286    * \li \c 1<<::KEY_PRESSED_EVENT  = 1
 287    * \li \c 1<<::KEY_RELEASED_EVENT = 2
 288    * \li \c 1<<::BUTTON_PRESSED_EVENT = 3,
 289    * \li \c 1<<::BUTTON_RELEASED_EVENT = 4
 290    **/
 291   typedef unsigned long ControllerEventMask;
 292
 293   /** A structure which encapsulates information about a device event. */
 294   struct DeviceEvent {
 295     EventType type; /**< Identifies the type of the containing DeviceEvent. */
 296     long  id; /**< an identifier which identifies this event in the event stream.
 297                * On X Window systems this corresponds to the XEvent serial number.
 298                */
 299     short hw_code; /**< a numeric code which is hardware and system-dependent, identifying the
 300                     * specific hardware button or key on the device for which the event has
 301                     * occurred. On X Window systems, for global key notifications and for most
 302                     * non-global key notifications as well, this code corresponds to the
 303                     * XKeycode.  For switch and button events it indicates the switch
 304                     * or button number.
 305                     * @note
 306                     * For technical reasons, this code may differ from the XKeycode
 307                     * when generated by Java applications for consumption by non-global
 308                     * key listeners.  This is subject to change in future versions of the
 309                     * DeviceEventController implementation.
 310                     */
 311
 312     unsigned short modifiers; /**< an unsigned short int consisting of zero or more of the following
 313                                * values OR'ed together:
 314                                * \li \c 1<<::MODIFIER_SHIFT   (=1, corresponds to Xlib's ShiftMask)
 315                                * \li \c 1<<::MODIFIER_SHIFTLOCK    (=2, corresponds to Xlib's LockMask)
 316                                * \li \c 1<<::MODIFIER_CONTROL (=4, corresponds to Xlib's ControlMask)
 317                                * \li \c 1<<::MODIFIER_ALT    (=8, corresponds to Xlib's Mod1Mask)
 318                                * \li \c 1<<::MODIFIER_META    (=16, corresponds to Xlib's Mod2Mask)
 319                                * \li \c 1<<::MODIFIER_META2    (=32, corresponds to Xlib's Mod3Mask)
 320                                * \li \c 1<<::MODIFIER_META3    (=64, corresponds to Xlib's Mod4Mask)
 321                                **/
 322     unsigned long timestamp; /**< an unsigned integer representing the time that the
 323                               * event occurred.  On X Window systems this event is
 324                               * a time in milliseconds from some arbitrary starting
 325                               * point; it therefore has a cycle time of approximately
 326                               * 50 days.
 327                               */
 328     string event_string; /**< A string representation of the event.  If is_text is
 329                           * \c True, then this string represents the character or typographic
 330                           * sequence that would be received by a focussed text input field.
 331                           * event_string is in general suitable for exposure to the
 332                           * end-user for purposes of keyboard echo.
 333                           */
 334     boolean is_text; /**< \c True if the event results in the insertion of characters
 335                       * into an input text buffer, or would do so if delivered to a focussed
 336                       * text input field. ¨Typographical¨ key events have this field set to
 337                       * \c True, whereas ¨control¨ key events generally do not.
 338                       */
 339   };
 340
 341   /**
 342    * A structure which defines the identity of a key for which notifications
 343    * are to be requested.  The data in the members of a ::KeyDefinition are used to
 344    * determine which keyboard events 'match' the notification request filed by a client.
 345    *
 346    * @note Ordinarily a KeyDefinition specifies one and only one of the criteria below;
 347    * the result of using a KeyDefinition with multiple members defined as nonzero is
 348    * undefined.
 349    *
 350    * @param keycode if nonzero, the numeric, system-dependent value corresponding to a
 351    * physical key on the keyboard.  Keycode values have no semantic meaning to the end-user,
 352    * and may depend on the user's hardware and operating environment.  They therefore are
 353    * rarely useful "as-is" to AT clients, unless the client has used operating system
 354    * services to identify the hardward keycode associated with a particular key symbol.
 355    * Notifications for key events requested by keycode are less dependent on modifier state
 356    * than \c keysym based notifications, but some hardware (notably many laptops) may generate
 357    * more than one keycode for the same physical key, depending on the state of physical
 358    * shift/modifier keys.
 359    * @param keysym if nonzero, the numeric value corresponding to the X Keysym of the key for which
 360    * notification is requested.  Note that the presence of active modifiers will affect
 361    * whether notification for key events requested via "keysym" specification takes place,
 362    * since the keysym depends on the modifier state for most keys.
 363    * @param keystring if non-NULL, the string value of the inserted characters if the corresponding
 364    * key event has ::KeyEvent:is_text set to \c True, or the string representing the
 365    * 'name' of the key.  On X11 systems, the string 'name' of non-printing keysyms corresponds
 366    * to the values in "keysymdef.h" as provided by Xlib, with the leading "XK_" stripped off.
 367    **/
 368   struct KeyDefinition {
 369     long keycode;
 370     long keysym;
 371     string keystring;
 372     long unused;
 373   };
 374
 375   typedef sequence< KeyDefinition > KeySet;
 376   typedef sequence< EventType > KeyEventTypeSeq;
 377   typedef sequence< EventType > EventTypeSeq;
 378
 379   /** This interface should be implemented by AT-SPI clients who wish to
 380    * make use of the DeviceEventController to receive device event notifications.
 381    * DeviceEvents include keyboard events and mouse button/motion events.
 382    **/
 383   interface DeviceEventListener : Bonobo::Unknown {
 384       /** Notify an interested DeviceEventListener that a DeviceEvent has occurred.
 385        * @returns \c True if the recipient/consumer wishes to consume the event, i.e.
 386        * prevent it from being delivered to the desktop, \c False if the event should
 387        * continue to be delivered as normal.
 388        */
 389         boolean notifyEvent (in DeviceEvent event);
 390       /** \cond */
 391         void    unImplemented__ ();
 392         void    unImplemented_2_ ();
 393         void    unImplemented_3_ ();
 394         void    unImplemented_4_ ();
 395         void    unImplemented_5_ ();
 396         void    unImplemented_6_ ();
 397       /** \endcond */
 398   };
 399
 400   /**
 401    * The interface via which clients request notification of device events, and
 402    * through which device events may be simulated.
 403    ***/
 404   interface DeviceEventController : Bonobo::Unknown {
 405
 406         /**
 407          * Register to intercept keyboard events, and either pass them on or
 408          * consume them.
 409          *
 410          * @param listener: a DeviceEventListener which will intercept key events.
 411          * @param keys:     a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 412          * @param mask:     a ControllerEventMask filtering the intercepted key events.
 413          * @param type:     a KeyEventTypeSeq that may created by ORing event types together.
 414          * @param mode: an EventListenerMode indicating whether the listener should
 415          *            receive the events synchronously, potentially consuming them,
 416          *            or just be notified asynchronously of those events that have
 417          *            been generated.
 418          * @note Some platforms have limited support for global, preemptive EventListenerMode.
 419          * Such a registration may fail if another client already has priority for preemptive
 420          * access to one or more of the members of the KeySet.  AT consumers have the option
 421          * of re-trying the request without the global flag, or without the preemptive flag,
 422          * or of re-trying with a different KeySet.  The best support for pre-emptive
 423          * global keyboard listeners is provided on platforms whose Xserver implementation
 424          * provides the XEvIE extension.
 425          *
 426          * @returns \c True if the DeviceEventListener was successfully registered
 427          * for the requested KeySet, ControllerEventMask, event types, and EventListenerMode;
 428          * otherwise returns \c False.
 429          **/
 430         boolean registerKeystrokeListener (in DeviceEventListener listener,
 431                                         in KeySet keys,
 432                                         in ControllerEventMask mask,
 433                                         in KeyEventTypeSeq type,
 434                                         in EventListenerMode mode);
 435
 436         /**
 437          * De-register a previously registered keyboard eventlistener.
 438          * @param listener: a DeviceEventListener which will intercept key events.
 439          * @param keys:     a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
 440          * @param mask:     a ControllerEventMask filtering the intercepted key events.
 441          * @param type:     an EventType mask that may created by ORing event types together.
 442          **/
 443         void deregisterKeystrokeListener (in DeviceEventListener listener,
 444                                           in KeySet keys,
 445                                           in ControllerEventMask mask,
 446                                           in KeyEventTypeSeq type);
 447
 448         /**
 449          * Register to intercept events, and either pass them on or
 450          * consume them. To listen to keyboard events use registerKeystrokeListener
 451          * instead.
 452          * @param listener: a DeviceEventListener which will intercept events.
 453          * @param typeseq:  an EventTypeSeq indicating which event types to listen for.
 454          * @returns \c True if successful, \c False if not
 455          **/
 456         boolean registerDeviceEventListener (in DeviceEventListener listener,
 457                                              in EventTypeSeq typeseq);
 458
 459         /**
 460          * De-register a previously registered keyboard eventlistener.
 461          * @param listener: a DeviceEventListener which will intercept events.
 462          * @param typeseq:  an EventTypeSeq indicating which event types to stop
 463          *            listening for.
 464          **/
 465         void deregisterDeviceEventListener (in DeviceEventListener listener,
 466                                             in EventTypeSeq typeseq);
 467
 468       /**
 469        * Notify the Registry instance that a device event has taken place, and
 470        *       allow pre-emptive listeners the opportunity to 'consume' the event
 471        *       and thus prevent its further issuance/forwarding.  This is the
 472        *       method used by accessibility bridges to forward "toolkit dependent"
 473        *       device events to the Registry from the application's process space.
 474        *
 475        * @note AT clients do not normally need to use this method, it is intended for use
 476        *       by toolkit bridges and special-purpose applications.
 477        *
 478        * @returns \c True if the event was consumed by a (pre-emptive) listener,
 479        *          \c False if not (in which case the device event will be forwarded
 480        *          as normal to any application which would normally receive it, e.g.
 481        *          the currently active application in the case of mouse or keyboard events).
 482        **/
 483         boolean notifyListenersSync (in DeviceEvent event);
 484
 485       /**
 486        * Notify the Registry instance that a device event has taken place in
 487        *       an asynchronous manner.  This is the
 488        *       method used by accessibility bridges to forward "toolkit dependent"
 489        *       device events to the Registry from the application's process space.
 490        *       If the event in question is potentially pre-emptible.
 491        *       ::notifyListenersSync should be used instead.
 492        *
 493        * @note AT clients do not normally need to use this method, it is intended for use
 494        *       by toolkit bridges and special-purpose applications.
 495        **/
 496         oneway void notifyListenersAsync (in DeviceEvent event);
 497
 498         /**
 499          * Synthesize a keyboard event.
 500          * @param keycode: a long integer indicating the keycode of
 501          *          the keypress to be synthesized.
 502          * @param keystring: an optional UTF-8 string indicating a complex
 503          *          keyboard input event.
 504          * @param type: a KeySynthType indicating the type of event(s) to be
 505          *          synthesized: a key press, release, press-release pair,
 506          *          or a complex input string (for instance from an
 507          *          internationalized or complex text input method, or
 508          *          a composed character).
 509          *
 510          * @note keycode may be truncated before being
 511          *          processed, as keycode length may be platform-dependent
 512          *          and keycode ranges are generally much smaller than
 513          *          CORBA_long.
 514          * One or the other of keycode or keystring are generally NULL,
 515          *          (but not both), depending on the value of \c type.
 516          *
 517          **/
 518          void generateKeyboardEvent (in long keycode,
 519                                      in string keystring,
 520                                      in KeySynthType type);
 521
 522         /**
 523          * Synthesize a mouse event.
 524          * @param x: a long integer indicating the screen x coord for the mouse event.
 525          * @param y: a long integer indicating the screen y coord for the mouse event.
 526          * @param eventName: a string indicating the type of mouse event, e.g. "button1up"
 527          **/
 528          void generateMouseEvent (in long x, in long y, in string eventName);
 529
 530          /** \cond
 531           * unImplemented:
 532           *
 533           * placeholders for future expansion.
 534           */
 535          void unImplemented ();
 536          void unImplemented2 ();
 537          void unImplemented3 ();
 538          void unImplemented4 ();
 539       /** \endcond */
 540     };
 541 };
 542
 543 #endif