X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=idl%2FAccessibility_Registry.idl;h=17d4a34f7166e0bb71d37d82834724b507653f64;hb=4768dab126202eaad5cceb413e0a55ad4930a5b8;hp=e2b4a87c934bda52e0815880e6e1e4ce7f5227b7;hpb=aca3c37006a1198a76e5ead8e29a7534f94f2569;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/idl/Accessibility_Registry.idl b/idl/Accessibility_Registry.idl index e2b4a87..17d4a34 100644 --- a/idl/Accessibility_Registry.idl +++ b/idl/Accessibility_Registry.idl @@ -20,10 +20,9 @@ * Boston, MA 02111-1307, USA. */ -#include -#include -#include -#include +#include +#include +#include #ifndef _ACCESSIBILITY_REGISTRY_IDL_ #define _ACCESSIBILITY_REGISTRY_IDL_ @@ -34,55 +33,90 @@ module Accessibility { interface DeviceEventController; + /** + * The Registry is a service through which applications providing + * accessibility services (servers) can rendezvous with consumers of those + * services (Assistive Technologies). The Registry is the first "port of call" for + * accessible applications and for assistive technologies wishing to query and + * interact with those applications. + * + * The Registry service provides four basic functions to Assistive Technology (AT) clients: + * \li it provides a list of the applications who have registered with the AT-SPI + * framework, thereby announcing their participation in the AT-SPI framework; + * \li it allows AT clients to register for notification of changes in application + * state (at-spi Events); + * \li it dispatches/relays said events from participating applications to + * the registered listeners; + * \li it gives access to system device events via the associated DeviceEventController + * interface. + * + * From the point of view of accessible applications (i.e. AT-SPI service producers), + * the Registry is primarily a registration and event delivery service. Applications + * normally only call the registerApplication and deregisterApplication Registry methods, + * and its inherited EventListener::notifyEvent method. + * + * @note Although all application events are dispatched via the Registry, other AT client + * calls are serviced directly by the applications, rather than being relayed via the + * Registry. The AT client obtains references to these application objects + * via the enumeration of Desktop instances whose children are Application instances + * (Registry::getDesktopList) and via examination of the 'source' member of the Event + * structure. + * + * The Registry normally lives in its own process space; communication via Registry and + * both application services and AT clients takes place via IPC. A process space diagram + * illustrating the relationship between applications, Registry, and AT is shown below. + * @image html "http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png" + * + * + * @see Desktop, Application, Event, EventListener + **/ interface Registry : EventListener { /** - * registerApplication: - * @application: a reference to the requesting @Application - * return values: void - * * Register a new application with the accessibility broker. - * + * @param app: a reference to the requesting Application **/ - void registerApplication (in Application application); + oneway void registerApplication (in Application app); /** + * De-register an application previously registered with the broker. * deregisterApplication: - * @application: a reference to the @Application + * @param app: a reference to the Application * to be deregistered. - * return values: void - * - * De-register an application previously registered with the broker. - * **/ - void deregisterApplication (in Application application); + void deregisterApplication (in Application app); /** - * registerGlobalEventListener: - * @listener: a reference to the requesting @EventListener. - * @eventName: a string which indicates the type of events about - * which the client desires notification. - * return values: void - * * Register a client's interest in (all) application events of * a certain type. - * + * @param listener: a reference to the requesting ::EventListener. + * @param eventName: a string which indicates the type of events about + * which the client desires notification. **/ void registerGlobalEventListener (in EventListener listener, - in string eventName); + in string eventName); + + /** + * deregisterGlobalEventListenerAll: + * @param listener: the requesting EventListener + * + * Request that a previously registered client stop receiving + * global notifications for all events for which it was registered. + * + **/ + void deregisterGlobalEventListenerAll (in EventListener listener); /** * deregisterGlobalEventListener: - * @listener: the requesting @EventListener - * @eventName: a string indicating the type of events - * return values: void + * @param listener: the requesting EventListener + * @param eventName: a string indicating the type of events * * Request that a previously registered client stop receiving * global notifications for events of a certain type. * **/ - - void deregisterGlobalEventListener (in EventListener listener); + void deregisterGlobalEventListener (in EventListener listener, + in string eventName); /** * event types: "Window" "Desktop" * "Window:Create" "Window:Destroy" @@ -102,103 +136,406 @@ module Accessibility { /** * getDesktopCount: - * return values: a short integer indicating the current number of - * @Desktops. * * Get the current number of desktops. - * + * @returns a short integer indicating the current number of + * Desktops. **/ short getDesktopCount (); /** * getDesktop: - * @n: the index of the requested @Desktop. - * return values: a reference to the requested @Desktop. + * @n: the index of the requested Desktop. * * Get the nth accessible desktop. * + * @returns a reference to the requested Desktop. **/ Desktop getDesktop (in short n); /** - * getDesktopList: - * return values: a sequence containing references to - * the @Desktops. - * * Get a list of accessible desktops. * + * @returns: a sequence containing references to + * the Desktops. **/ DesktopSeq getDesktopList (); /** - * getDeviceEventController: - * return values: an object implementing DeviceEventController + * Obtain an object which can be used to request device event notifications. * + * @returns: an object implementing DeviceEventController **/ DeviceEventController getDeviceEventController (); + /** \cond + * unImplemented: + * + * placeholders for future expansion. + */ + void unImplemented (); + void unImplemented2 (); + void unImplemented3 (); + void unImplemented4 (); + void unImplemented5 (); + void unImplemented6 (); + /** \endcond */ }; + /** Deprecated, DO NOT USE! */ enum KeyEventType { KEY_PRESSED, KEY_RELEASED }; + /** Used to specify the event types of interest to an EventListener, or + * to identify the type of an event for which notification has been sent. + * @see EventTypeSeq, DeviceEvent::type + */ + enum EventType { + KEY_PRESSED_EVENT, /**< key on a keyboard device was pressed. */ + KEY_RELEASED_EVENT, /**< key on a keyboard device was released. */ + BUTTON_PRESSED_EVENT,/**< button on a non-keyboard human interface device + * (HID) was pressed */ + BUTTON_RELEASED_EVENT /**< button on a non-keyboard human interface device + * (HID) was pressed */ + }; + + /** Used when synthesizing keyboard input via DeviceEventController:generateKeyboardEvent.*/ + enum KeySynthType { + KEY_PRESS,/** emulate the pressing of a hardware keyboard key. */ + KEY_RELEASE,/** emulate the release of a hardware keyboard key. */ + KEY_PRESSRELEASE,/** a hardware keyboard key is pressed and immediately released. */ + KEY_SYM,/** a symbolic key event is generated, without specifying a hardware key. + * @note if the keysym is not present in the current keyboard map, + * the DeviceEventController instance has a limited ability to generate + * such keysyms on-the-fly. Reliability of generateKeyboardEvent calls + * using out-of-keymap keysyms will vary from system to system, and on the + * number of different out-of-keymap being generated in quick succession. + * In practice this is rarely significant, since the keysyms of interest to + * AT clients and keyboard emulators are usually part of the current keymap, i.e. + * present on the system keyboard for the current locale (even if a physical + * hardware keyboard is not connected. + */ + KEY_STRING /** a string is converted to its equivalent keyboard events and emitted. + * If the string consists of complex character or composed characters + * which are not in the current keymap, string emission is subject to the + * out-of-keymap limitations described for KeySynthType::KEY_SYM. + * In practice this limitation primarily effects Chinese and Japanese locales. + */ + }; + enum ModifierType { - MODIFIER_ALT, - MODIFIER_META, - MODIFIER_CONTROL, - MODIFIER_SHIFT, + MODIFIER_SHIFT, /** The left or right 'Shift' key */ + MODIFIER_SHIFTLOCK, /** The ShiftLock or CapsLock key */ + MODIFIER_CONTROL,/** 'Control'/'Ctrl' */ + MODIFIER_ALT,/** The Alt key (as opposed to AltGr) */ + MODIFIER_META,/** depending on the platform this may map to 'Window', 'Function', 'Meta', + * 'Menu', or 'NumLock'. + * Such 'Meta keys' will map to one of META, META2, META3. + * On X Windows platforms these META values map to + * the modifier masks Mod1Mask, Mod2Mask, Mod3Mask, e.g. an event having + * ModifierType::MODIFIER_META2 means that the 'Mod2Mask' bit is + * set in the corresponding XEvent. + */ MODIFIER_META2, - MODIFIER_META3 + MODIFIER_META3, + MODIFIER_NUMLOCK/** A symbolic meta key name that is mapped by AT-SPI to the + * appropriate META value, for the convenience of the client. + */ }; - typedef sequence ModifierSeq; + /** A structure that encapsulates the characteristics of the event notifications + * that should be sent to an EventListener in response to a call to + * DeviceEventController::registerKeystrokeListener or + * DeviceEventController::registerDeviceEventListener. */ + struct EventListenerMode { + boolean synchronous; /**< If \c True, specifies that + * DeviceEventController should block while waiting + * for client to process the requested event notifications; + * ordinarily should be used only when client needs to perform + * operations synchronously with event delivery. Note that because + * of the architecture of device event systems in general, + * use of this flag may not block delivery of the event to + * the currently focussed application unless it is used in + * conjunction with the preemptive flag. */ + boolean preemptive; /**< If \c True, specifies that + * Listener is allowed to pre-empt the delivery of the event, + * effectively "consuming" it such that it is not delivered + * to the currently focussed desktop application. + * Key events consumed via this API will not be + * available for use by other applications or services, so this + * option should be used sparingly. */ + boolean global; /**< If \c True, specifies that + * Event notifications should be sent regardless of whether the + * currently focussed application participates in the AT-SPI + * infrastructure. On systems with the XEvIE X extension, this flag + * also allows access to events which are already subject to + * interception via a "system keygrab" (as described in the X Window System + * documentation for XGrabKey). The 'global' and 'preemptive' flags + * should only be used together for the purposes of registering + * "system global key shortcuts" i.e. command keys for use by the + * assistive technology. */ + }; + + /** + * an unsigned short int consisting of zero or more of the following + * values OR'ed together: + * + * \li \c 1<<::KEY_PRESSED_EVENT = 1 + * \li \c 1<<::KEY_RELEASED_EVENT = 2 + * \li \c 1<<::BUTTON_PRESSED_EVENT = 3, + * \li \c 1<<::BUTTON_RELEASED_EVENT = 4 + **/ + typedef unsigned long ControllerEventMask; + + /** A structure which encapsulates information about a device event. */ + struct DeviceEvent { + EventType type; /**< Identifies the type of the containing DeviceEvent. */ + long id; /**< an identifier which identifies this event in the event stream. + * On X Window systems this corresponds to the XEvent serial number. + */ + short hw_code; /**< a numeric code which is hardware and system-dependent, identifying the + * specific hardware button or key on the device for which the event has + * occurred. On X Window systems, for global key notifications and for most + * non-global key notifications as well, this code corresponds to the + * XKeycode. For switch and button events it indicates the switch + * or button number. + * @note + * For technical reasons, this code may differ from the XKeycode + * when generated by Java applications for consumption by non-global + * key listeners. This is subject to change in future versions of the + * DeviceEventController implementation. + */ - struct KeyStroke { - long keyID; - KeyEventType type; - ModifierSeq modifiers; + unsigned short modifiers; /**< an unsigned short int consisting of zero or more of the following + * values OR'ed together: + * \li \c 1<<::MODIFIER_SHIFT (=1, corresponds to Xlib's ShiftMask) + * \li \c 1<<::MODIFIER_SHIFTLOCK (=2, corresponds to Xlib's LockMask) + * \li \c 1<<::MODIFIER_CONTROL (=4, corresponds to Xlib's ControlMask) + * \li \c 1<<::MODIFIER_ALT (=8, corresponds to Xlib's Mod1Mask) + * \li \c 1<<::MODIFIER_META (=16, corresponds to Xlib's Mod2Mask) + * \li \c 1<<::MODIFIER_META2 (=32, corresponds to Xlib's Mod3Mask) + * \li \c 1<<::MODIFIER_META3 (=64, corresponds to Xlib's Mod4Mask) + **/ + unsigned long timestamp; /**< an unsigned integer representing the time that the + * event occurred. On X Window systems this event is + * a time in milliseconds from some arbitrary starting + * point; it therefore has a cycle time of approximately + * 50 days. + */ + string event_string; /**< A string representation of the event. If is_text is + * \c True, then this string represents the character or typographic + * sequence that would be received by a focussed text input field. + * event_string is in general suitable for exposure to the + * end-user for purposes of keyboard echo. + */ + boolean is_text; /**< \c True if the event results in the insertion of characters + * into an input text buffer, or would do so if delivered to a focussed + * text input field. ¨Typographical¨ key events have this field set to + * \c True, whereas ¨control¨ key events generally do not. + */ }; - interface KeystrokeListener { - boolean keyEvent (in KeyStroke key); + /** + * A structure which defines the identity of a key for which notifications + * are to be requested. The data in the members of a ::KeyDefinition are used to + * determine which keyboard events 'match' the notification request filed by a client. + * + * @note Ordinarily a KeyDefinition specifies one and only one of the criteria below; + * the result of using a KeyDefinition with multiple members defined as nonzero is + * undefined. + * + * @param keycode if nonzero, the numeric, system-dependent value corresponding to a + * physical key on the keyboard. Keycode values have no semantic meaning to the end-user, + * and may depend on the user's hardware and operating environment. They therefore are + * rarely useful "as-is" to AT clients, unless the client has used operating system + * services to identify the hardward keycode associated with a particular key symbol. + * Notifications for key events requested by keycode are less dependent on modifier state + * than \c keysym based notifications, but some hardware (notably many laptops) may generate + * more than one keycode for the same physical key, depending on the state of physical + * shift/modifier keys. + * @param keysym if nonzero, the numeric value corresponding to the X Keysym of the key for which + * notification is requested. Note that the presence of active modifiers will affect + * whether notification for key events requested via "keysym" specification takes place, + * since the keysym depends on the modifier state for most keys. + * @param keystring if non-NULL, the string value of the inserted characters if the corresponding + * key event has ::KeyEvent:is_text set to \c True, or the string representing the + * 'name' of the key. On X11 systems, the string 'name' of non-printing keysyms corresponds + * to the values in "keysymdef.h" as provided by Xlib, with the leading "XK_" stripped off. + **/ + struct KeyDefinition { + long keycode; + long keysym; + string keystring; + long unused; + }; + + typedef sequence< KeyDefinition > KeySet; + typedef sequence< EventType > KeyEventTypeSeq; + typedef sequence< EventType > EventTypeSeq; + + /** This interface should be implemented by AT-SPI clients who wish to + * make use of the DeviceEventController to receive device event notifications. + * DeviceEvents include keyboard events and mouse button/motion events. + **/ + interface DeviceEventListener : Bonobo::Unknown { + /** Notify an interested DeviceEventListener that a DeviceEvent has occurred. + * @returns \c True if the recipient/consumer wishes to consume the event, i.e. + * prevent it from being delivered to the desktop, \c False if the event should + * continue to be delivered as normal. + */ + boolean notifyEvent (in DeviceEvent event); + /** \cond */ + void unImplemented__ (); + void unImplemented_2_ (); + void unImplemented_3_ (); + void unImplemented_4_ (); + void unImplemented_5_ (); + void unImplemented_6_ (); + /** \endcond */ }; - interface DeviceEventController { + /** + * The interface via which clients request notification of device events, and + * through which device events may be simulated. + ***/ + interface DeviceEventController : Bonobo::Unknown { /** - * registerKeystrokeListener: - * @listener: a @KeystrokeListener which will intercept key events. - * Returns: void - * * Register to intercept keyboard events, and either pass them on or * consume them. * + * @param listener: a DeviceEventListener which will intercept key events. + * @param keys: a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS. + * @param mask: a ControllerEventMask filtering the intercepted key events. + * @param type: a KeyEventTypeSeq that may created by ORing event types together. + * @param mode: an EventListenerMode indicating whether the listener should + * receive the events synchronously, potentially consuming them, + * or just be notified asynchronously of those events that have + * been generated. + * @note Some platforms have limited support for global, preemptive EventListenerMode. + * Such a registration may fail if another client already has priority for preemptive + * access to one or more of the members of the KeySet. AT consumers have the option + * of re-trying the request without the global flag, or without the preemptive flag, + * or of re-trying with a different KeySet. The best support for pre-emptive + * global keyboard listeners is provided on platforms whose Xserver implementation + * provides the XEvIE extension. + * + * @returns \c True if the DeviceEventListener was successfully registered + * for the requested KeySet, ControllerEventMask, event types, and EventListenerMode; + * otherwise returns \c False. + **/ + boolean registerKeystrokeListener (in DeviceEventListener listener, + in KeySet keys, + in ControllerEventMask mask, + in KeyEventTypeSeq type, + in EventListenerMode mode); + + /** + * De-register a previously registered keyboard eventlistener. + * @param listener: a DeviceEventListener which will intercept key events. + * @param keys: a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS. + * @param mask: a ControllerEventMask filtering the intercepted key events. + * @param type: an EventType mask that may created by ORing event types together. + **/ + void deregisterKeystrokeListener (in DeviceEventListener listener, + in KeySet keys, + in ControllerEventMask mask, + in KeyEventTypeSeq type); + + /** + * Register to intercept events, and either pass them on or + * consume them. To listen to keyboard events use registerKeystrokeListener + * instead. + * @param listener: a DeviceEventListener which will intercept events. + * @param typeseq: an EventTypeSeq indicating which event types to listen for. + * @returns \c True if successful, \c False if not + **/ + boolean registerDeviceEventListener (in DeviceEventListener listener, + in EventTypeSeq typeseq); + + /** + * De-register a previously registered keyboard eventlistener. + * @param listener: a DeviceEventListener which will intercept events. + * @param typeseq: an EventTypeSeq indicating which event types to stop + * listening for. **/ - void registerKeystrokeListener (in KeystrokeListener listener); + void deregisterDeviceEventListener (in DeviceEventListener listener, + in EventTypeSeq typeseq); + /** + * Notify the Registry instance that a device event has taken place, and + * allow pre-emptive listeners the opportunity to 'consume' the event + * and thus prevent its further issuance/forwarding. This is the + * method used by accessibility bridges to forward "toolkit dependent" + * device events to the Registry from the application's process space. + * + * @note AT clients do not normally need to use this method, it is intended for use + * by toolkit bridges and special-purpose applications. + * + * @returns \c True if the event was consumed by a (pre-emptive) listener, + * \c False if not (in which case the device event will be forwarded + * as normal to any application which would normally receive it, e.g. + * the currently active application in the case of mouse or keyboard events). + **/ + boolean notifyListenersSync (in DeviceEvent event); + + /** + * Notify the Registry instance that a device event has taken place in + * an asynchronous manner. This is the + * method used by accessibility bridges to forward "toolkit dependent" + * device events to the Registry from the application's process space. + * If the event in question is potentially pre-emptible. + * ::notifyListenersSync should be used instead. + * + * @note AT clients do not normally need to use this method, it is intended for use + * by toolkit bridges and special-purpose applications. + **/ + oneway void notifyListenersAsync (in DeviceEvent event); + /** - * generateKeyEvent: - * @keyEventID: a long integer indicating which keypress is synthesized. - * Returns: void - * - * Synthesize a keypress event. - * + * Synthesize a keyboard event. + * @param keycode: a long integer indicating the keycode of + * the keypress to be synthesized. + * @param keystring: an optional UTF-8 string indicating a complex + * keyboard input event. + * @param type: a KeySynthType indicating the type of event(s) to be + * synthesized: a key press, release, press-release pair, + * or a complex input string (for instance from an + * internationalized or complex text input method, or + * a composed character). + * + * @note keycode may be truncated before being + * processed, as keycode length may be platform-dependent + * and keycode ranges are generally much smaller than + * CORBA_long. + * One or the other of keycode or keystring are generally NULL, + * (but not both), depending on the value of \c type. + * **/ - void generateKeyEvent (in long keyEventID); + void generateKeyboardEvent (in long keycode, + in string keystring, + in KeySynthType type); /** - * generateMouseEvent: - * @x: a long integer indicating the screen x coord for the mouse event. - * @y: a long integer indicating the screen y coord for the mouse event. - * @eventName: a string indicating the type of mouse event, e.g. "button1up" - * Returns: void - * * Synthesize a mouse event. - * + * @param x: a long integer indicating the screen x coord for the mouse event. + * @param y: a long integer indicating the screen y coord for the mouse event. + * @param eventName: a string indicating the type of mouse event, e.g. "button1up" **/ void generateMouseEvent (in long x, in long y, in string eventName); + + /** \cond + * unImplemented: + * + * placeholders for future expansion. + */ + void unImplemented (); + void unImplemented2 (); + void unImplemented3 (); + void unImplemented4 (); + /** \endcond */ }; };