2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems Inc.
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.
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.
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.
23 #include <Bonobo_Unknown.idl>
24 #include <Accessibility_Event.idl>
25 #include <Accessibility_Application.idl>
26 #include <Accessibility_Desktop.idl>
28 #ifndef _ACCESSIBILITY_REGISTRY_IDL_
29 #define _ACCESSIBILITY_REGISTRY_IDL_
31 module Accessibility {
33 typedef sequence<Desktop> DesktopSeq;
35 interface DeviceEventController;
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.
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
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.
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
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"
72 * @see Desktop, Application, Event, EventListener
74 interface Registry : EventListener {
77 * Register a new application with the accessibility broker.
78 * @param application: a reference to the requesting Application
80 oneway void registerApplication (in Application application);
83 * De-register an application previously registered with the broker.
84 * deregisterApplication:
85 * @param application: a reference to the Application
88 void deregisterApplication (in Application application);
91 * Register a client's interest in (all) application events of
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.
97 void registerGlobalEventListener (in EventListener listener,
101 * deregisterGlobalEventListenerAll:
102 * @param listener: the requesting EventListener
104 * Request that a previously registered client stop receiving
105 * global notifications for all events for which it was registered.
108 void deregisterGlobalEventListenerAll (in EventListener listener);
111 * deregisterGlobalEventListener:
112 * @param listener: the requesting EventListener
113 * @param eventName: a string indicating the type of events
115 * Request that a previously registered client stop receiving
116 * global notifications for events of a certain type.
119 void deregisterGlobalEventListener (in EventListener listener,
120 in string eventName);
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"
131 * "GObject:notify:<propertyname>"
133 * ( not sure we should allow these last 2 forms,
134 * since they are toolkit-specific, but they're powerful )
141 * Get the current number of desktops.
142 * @returns a short integer indicating the current number of
145 short getDesktopCount ();
149 * @n: the index of the requested Desktop.
151 * Get the nth accessible desktop.
153 * @returns a reference to the requested Desktop.
155 Desktop getDesktop (in short n);
158 * Get a list of accessible desktops.
160 * @returns: a sequence containing references to
163 DesktopSeq getDesktopList ();
166 * Obtain an object which can be used to request device event notifications.
168 * @returns: an object implementing DeviceEventController
170 DeviceEventController getDeviceEventController ();
175 * placeholders for future expansion.
177 void unImplemented ();
178 void unImplemented2 ();
179 void unImplemented3 ();
180 void unImplemented4 ();
181 void unImplemented5 ();
182 void unImplemented6 ();
186 /** Deprecated, DO NOT USE! */
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
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 */
205 /** Used when synthesizing keyboard input via DeviceEventController:generateKeyboardEvent.*/
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.
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.
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.
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.
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. */
283 * an unsigned short int consisting of zero or more of the following
284 * values OR'ed together:
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
291 typedef unsigned long ControllerEventMask;
293 /** A structure which encapsulates information about a device event. */
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.
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
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.
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)
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
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.
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.
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.
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
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.
368 struct KeyDefinition {
375 typedef sequence< KeyDefinition > KeySet;
376 typedef sequence< EventType > KeyEventTypeSeq;
377 typedef sequence< EventType > EventTypeSeq;
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.
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.
389 boolean notifyEvent (in DeviceEvent event);
391 void unImplemented__ ();
392 void unImplemented_2_ ();
393 void unImplemented_3_ ();
394 void unImplemented_4_ ();
395 void unImplemented_5_ ();
396 void unImplemented_6_ ();
401 * The interface via which clients request notification of device events, and
402 * through which device events may be simulated.
404 interface DeviceEventController : Bonobo::Unknown {
407 * Register to intercept keyboard events, and either pass them on or
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
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.
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.
430 boolean registerKeystrokeListener (in DeviceEventListener listener,
432 in ControllerEventMask mask,
433 in KeyEventTypeSeq type,
434 in EventListenerMode mode);
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.
443 void deregisterKeystrokeListener (in DeviceEventListener listener,
445 in ControllerEventMask mask,
446 in KeyEventTypeSeq type);
449 * Register to intercept events, and either pass them on or
450 * consume them. To listen to keyboard events use registerKeystrokeListener
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
456 boolean registerDeviceEventListener (in DeviceEventListener listener,
457 in EventTypeSeq typeseq);
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
465 void deregisterDeviceEventListener (in DeviceEventListener listener,
466 in EventTypeSeq typeseq);
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.
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.
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).
483 boolean notifyListenersSync (in DeviceEvent event);
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.
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.
496 oneway void notifyListenersAsync (in DeviceEvent event);
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).
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
514 * One or the other of keycode or keystring are generally NULL,
515 * (but not both), depending on the value of \c type.
518 void generateKeyboardEvent (in long keycode,
520 in KeySynthType type);
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"
528 void generateMouseEvent (in long x, in long y, in string eventName);
533 * placeholders for future expansion.
535 void unImplemented ();
536 void unImplemented2 ();
537 void unImplemented3 ();
538 void unImplemented4 ();