Registry queries

Registry queries

Synopsis

enum                AccessibleKeySynthType;
int                 SPI_getDesktopCount                 (void);
Accessible *        SPI_getDesktop                      (int i);
int                 SPI_getDesktopList                  (Accessible ***desktop_list);
void                SPI_freeDesktopList                 (Accessible **desktop_list);

SPIBoolean          (*AccessibleKeystrokeListenerCB)    (const AccessibleKeystroke *stroke,
                                                         void *user_data);
typedef             AccessibleKeyEventMask;
typedef             AccessibleModifierMaskType;
typedef             AccessibleKeyMaskType;
typedef             AccessibleKeyEventType;
enum                AccessibleKeyListenerSyncType;
typedef             AccessibleKeystroke;
AccessibleKeySet *  SPI_createAccessibleKeySet          (int len,
                                                         const char *keysyms,
                                                         short *keycodes,
                                                         const char **keystrings);
void                SPI_freeAccessibleKeySet            (AccessibleKeySet *keyset);
AccessibleKeystrokeListener * SPI_createAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListenerCB callback,
                                                         void *user_data);
SPIBoolean          SPI_registerGlobalEventListener     (AccessibleEventListener *listener,
                                                         const char *eventType);
SPIBoolean          SPI_deregisterGlobalEventListener   (AccessibleEventListener *listener,
                                                         const char *eventType);
SPIBoolean          SPI_deregisterGlobalEventListenerAll
                                                        (AccessibleEventListener *listener);
SPIBoolean          SPI_registerAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeySet *keys,
                                                         AccessibleKeyMaskType modmask,
                                                         AccessibleKeyEventMask eventmask,
                                                         AccessibleKeyListenerSyncType sync_type);
SPIBoolean          SPI_deregisterAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeyMaskType modmask);
void                AccessibleKeystrokeListener_unref   (AccessibleKeystrokeListener *listener);
SPIBoolean          AccessibleKeystrokeListener_removeCallback
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeystrokeListenerCB callback);
SPIBoolean          AccessibleKeystrokeListener_addCallback
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeystrokeListenerCB callback,
                                                         void *user_data);
SPIBoolean          SPI_generateKeyboardEvent           (long int keyval,
                                                         char *keystring,
                                                         AccessibleKeySynthType synth_type);
SPIBoolean          SPI_generateMouseEvent              (long int x,
                                                         long int y,
                                                         char *name);
                    AccessibleDeviceEvent;
typedef             AccessibleDeviceEventMask;
enum                AccessibleDeviceEventType;
SPIBoolean          (*AccessibleDeviceListenerCB)       (const AccessibleDeviceEvent *stroke,
                                                         void *user_data);
AccessibleDeviceListener * SPI_createAccessibleDeviceListener
                                                        (AccessibleDeviceListenerCB callback,
                                                         void *user_data);
SPIBoolean          SPI_registerDeviceEventListener     (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceEventMask eventmask,
                                                         void *filter);
SPIBoolean          SPI_deregisterDeviceEventListener   (AccessibleDeviceListener *listener,
                                                         void *filter);
SPIBoolean          AccessibleDeviceListener_addCallback
                                                        (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceListenerCB callback,
                                                         void *user_data);
SPIBoolean          AccessibleDeviceListener_removeCallback
                                                        (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceListenerCB callback);
void                AccessibleDeviceListener_unref      (AccessibleDeviceListener *listener);

Description

Details

enum AccessibleKeySynthType

typedef enum {
  SPI_KEY_PRESS,
  SPI_KEY_RELEASE, 
  SPI_KEY_PRESSRELEASE,
  SPI_KEY_SYM,
  SPI_KEY_STRING
} AccessibleKeySynthType;

Specifies the type of a generated event.

SPI_KEY_PRESS

 Generates a keypress event (requires a subsequent SPI_KEY_RELEASE event)

SPI_KEY_RELEASE

 Generates a key-release event

SPI_KEY_PRESSRELEASE

 Generates a key press/release event pair.

SPI_KEY_SYM

 Injects a "keysym" event into the stream, as if a press/release pair occurred; allows the user to specify the key via its symbolic name, as opposed to simulating a hardware press of a specific key.

SPI_KEY_STRING

 Injects one or more keysym events into the keyboard buffer, or directly inserts a string value into the currently focussed text widget, if the widgets supports this. SPI_KEY_STRING synthesis provides a shortcut for text substring insertion, and also allows the insertion of text which is not currently available via the current keyboard's keymap.

SPI_getDesktopCount ()

int                 SPI_getDesktopCount                 (void);

Get the number of virtual desktops. NOTE: currently multiple virtual desktops are not implemented, this function always returns '1'.

Returns :

 an integer indicating the number of active virtual desktops.

SPI_getDesktop ()

Accessible *        SPI_getDesktop                      (int i);

Get the virtual desktop indicated by index i. NOTE: currently multiple virtual desktops are not implemented, this function always returns '1'.

i :

 an integer indicating which of the accessible desktops is to be returned.

Returns :

 a pointer to the 'i-th' virtual desktop's Accessible representation.

SPI_getDesktopList ()

int                 SPI_getDesktopList                  (Accessible ***desktop_list);

Get the list of virtual desktops. On return, list will point to a newly-created, NULL terminated array of virtual desktop pointers. It is the responsibility of the caller to free this array when it is no longer needed.

Not Yet Implemented : this implementation always returns a single Accessible desktop.

desktop_list :

 a pointer to an array of Accessible references.

Returns :

 an integer indicating how many virtual desktops have been placed in the list pointed to by parameter list.

SPI_freeDesktopList ()

void                SPI_freeDesktopList                 (Accessible **desktop_list);

This routine frees the memory associated with the list.

desktop_list :

 a pointer to an array of Accessible objects as returned from SPI_getDesktopList

AccessibleKeystrokeListenerCB ()

SPIBoolean          (*AccessibleKeystrokeListenerCB)    (const AccessibleKeystroke *stroke,
                                                         void *user_data);

A function prototype for a callback function called when a key event notification takes place.

This is a function which is specified when creating a KeystrokeListener. It is called when an event being listened for occurs. If it returns TRUE, this indicates that the event should be consumed rather than passed through; only callbacks whose listeners are registered with the SPI_KEYLISTENER_ALL_WINDOWS or SPI_KEYLISTENER_CANCONSUME flags can be consumed.

stroke :

 the AccessibleKeystroke event for which notification is taking place.

user_data :

 data passed to the callback each time it is notified, according to the data which was passed in when the listener/callback was registered.

Returns :

 TRUE if the client wishes to consume the event and prevent its dispatch to other listeners or the currently focussed application, if the relevant callback was registered with the SPI_KEYLISTENER_CANCONSUME flag.

AccessibleKeyEventMask

typedef unsigned long AccessibleKeyEventMask;

AccessibleKeyEventMask is a set of types of key events. It is used in SPI_registerAccessibleKeystroketListener to specify the events to be listener for.

AccessibleModifierMaskType

typedef unsigned long AccessibleModifierMaskType;

AccessibleModifierMaskType is a synonym for AccessibleKeymaskType. The defined values for AccessibleModifierMaskType can be found in libspi/keymasks.h.

AccessibleKeyMaskType

typedef AccessibleModifierMaskType AccessibleKeyMaskType;

AccessibleKeyMaskType is a mask which is a set of key event modifiers which is specified in SPI_registerAccessibleKeystrokeListener.

AccessibleKeyEventType

typedef AccessibleDeviceEventType AccessibleKeyEventType;

This is a synonym for AccessibleDeviceEventType

enum AccessibleKeyListenerSyncType

typedef enum {
  SPI_KEYLISTENER_NOSYNC = 0,
  SPI_KEYLISTENER_SYNCHRONOUS = 1,
  SPI_KEYLISTENER_CANCONSUME = 2,
  SPI_KEYLISTENER_ALL_WINDOWS = 4
} AccessibleKeyListenerSyncType;

Specified the tyupe of a key listener event. Certain of the values above can and should be bitwise-'OR'ed together, observing the compatibility limitations specified in the description of each value. For instance, SPI_KEYLISTENER_ALL_WINDOWS | SPI_KEYLISTENER_CANCONSUME is a commonly used combination which gives the AT complete control over the delivery of matching events. However, such filters should be used sparingly as they may have a negative impact on system performance.

SPI_KEYLISTENER_NOSYNC

 Events may be delivered asynchronously, which means in some cases they may already have been delivered to the application before the AT client receives the notification.

SPI_KEYLISTENER_SYNCHRONOUS

 Events are delivered synchronously, before the currently focussed application sees them.

SPI_KEYLISTENER_CANCONSUME

 Events may be consumed by the AT client. Presumes and requires SPI_KEYLISTENER_SYNCHRONOUS, incompatible with SPI_KEYLISTENER_NOSYNC.

SPI_KEYLISTENER_ALL_WINDOWS

 Events are received not from the application toolkit layer, but from the device driver or windowing system subsystem; such notifications are 'global' in the sense that they are not broken or defeated by applications that participate poorly in the accessibility APIs, or not at all; however because of the intrusive nature of such snooping, it can have side-effects on certain older platforms. If unconditional event notifications, even when inaccessible or "broken" applications have focus, are not required, it may be best to avoid this enum value/flag.

AccessibleKeystroke

typedef AccessibleDeviceEvent AccessibleKeystroke;

This is a synonym for AccessibleDeviceEvent.

SPI_createAccessibleKeySet ()

AccessibleKeySet *  SPI_createAccessibleKeySet          (int len,
                                                         const char *keysyms,
                                                         short *keycodes,
                                                         const char **keystrings);

Create a new AccessibleKeySet of a specified length. A KeySet is used typically to match key event values, and a matches are made using the following criteria: a match exists with a key event if all non-null i-th members of the keyset match the key event. If both keystring and keysym values are NULL, a keycode value match is forced, thus the match for keysym=0, keycode=0, keystring=NULL is keycode 0.

len :

 the number of key values in the key set.

keysyms :

 a UTF-8 string containing symbolic key values to be matched, or NULL if matching is performed against other key values instead.

keycodes :

 an array of unsigned short values which are the hardware keycodes to be matched, or NULL if the keyset is specified solely by keysyms and/or keystrings.

keystrings :

 an array of null-terminated character strings which specify key name values to match, or NULL if the keyset is specified solely by keycodes and/or keysyms.

Returns :

 a pointer to a newly-created AccessibleKeySet.

SPI_freeAccessibleKeySet ()

void                SPI_freeAccessibleKeySet            (AccessibleKeySet *keyset);

Release the memory used by an AccessibleKeySet.

keyset :

 An AccessibleKeyset to free.

SPI_createAccessibleKeystrokeListener ()

AccessibleKeystrokeListener * SPI_createAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListenerCB callback,
                                                         void *user_data);

Create a new AccessibleKeystrokeListener with a specified callback function.

callback :

 an AccessibleKeystrokeListenerCB callback function, or NULL.

user_data :

 a pointer to data which will be passed to the callback when invoked.

Returns :

 a pointer to a newly-created AccessibleKeystrokeListener.

SPI_registerGlobalEventListener ()

SPIBoolean          SPI_registerGlobalEventListener     (AccessibleEventListener *listener,
                                                         const char *eventType);

Legal object event types:

(property change events)

object:property-change object:property-change:accessible-name object:property-change:accessible-description object:property-change:accessible-parent object:property-change:accessible-value object:property-change:accessible-role object:property-change:accessible-table-caption object:property-change:accessible-table-column-description object:property-change:accessible-table-column-header object:property-change:accessible-table-row-description object:property-change:accessible-table-row-header object:property-change:accessible-table-summary

(other object events)

object:state-changed object:children-changed object:visible-data-changed object:selection-changed object:text-selection-changed object:text-changed object:text-caret-moved object:row-inserted object:row-reordered object:row-deleted object:column-inserted object:column-reordered object:column-deleted object:model-changed object:active-descendant-changed

(window events)

window:minimize window:maximize window:restore window:close window:create window:reparent window:desktop-create window:desktop-destroy window:activate window:deactivate window:raise window:lower window:move window:resize window:shade window:unshade window:restyle

(other events)

focus: mouse:abs mouse:rel mouse:b1p mouse:b1r mouse:b2p mouse:b2r mouse:b3p mouse:b3r

NOTE: this string may be UTF-8, but should not contain byte value 56 (ascii ':'), except as a delimiter, since non-UTF-8 string delimiting functions are used internally. In general, listening to toolkit-specific events is not recommended.

Add an in-process callback function to an existing AccessibleEventListener.

listener :

 the AccessibleEventListener to be registered against an event type.

eventType :

 a character string indicating the type of events for which notification is requested. Format is EventClass:major_type:minor_type:detail where all subfields other than EventClass are optional. EventClasses include "object", "window", "mouse", and toolkit events (e.g. "Gtk", "AWT"). Examples: "focus:", "Gtk:GtkWidget:button-press-event".

Returns :

 TRUE if successful, otherwise FALSE.

SPI_deregisterGlobalEventListener ()

SPIBoolean          SPI_deregisterGlobalEventListener   (AccessibleEventListener *listener,
                                                         const char *eventType);

deregisters an AccessibleEventListener from the registry, for a specific event type.

listener :

 the AccessibleEventListener registered against an event type.

eventType :

 a string specifying the event type for which this listener is to be deregistered.

Returns :

 TRUE if successful, otherwise FALSE.

SPI_deregisterGlobalEventListenerAll ()

SPIBoolean          SPI_deregisterGlobalEventListenerAll
                                                        (AccessibleEventListener *listener);

deregisters an AccessibleEventListener from the registry, for all event types it may be listening to. Use AccessibleEventListener_unref to release the listener reference.

listener :

 the AccessibleEventListener to be registered against an event type.

Returns :

 TRUE if successful, otherwise FALSE.

SPI_registerAccessibleKeystrokeListener ()

SPIBoolean          SPI_registerAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeySet *keys,
                                                         AccessibleKeyMaskType modmask,
                                                         AccessibleKeyEventMask eventmask,
                                                         AccessibleKeyListenerSyncType sync_type);

Register a listener for keystroke events, either pre-emptively for all windows (SPI_KEYLISTENER_ALL_WINDOWS), non-preemptively (SPI_KEYLISTENER_NOSYNC), or pre-emptively at the toolkit level (SPI_KEYLISTENER_CANCONSUME). If ALL_WINDOWS or CANCONSUME are used, the event is consumed upon receipt if one of listener's callbacks returns TRUE. ( Other sync_type values may be available in the future )

listener :

 a pointer to the AccessibleKeystrokeListener for which keystroke events are requested.

keys :

 a pointer to the AccessibleKeySet indicating which keystroke events are requested, or SPI_KEYSET_ALL_KEYS to indicate that all keycodes and keyvals for the specified modifier set are to be included.

modmask :

 an AccessibleKeyMaskType mask indicating which key event modifiers must be set in combination with keys, events will only be reported for key events for which all modifiers in modmask are set. If you wish to listen for events with multiple modifier combinations you must call registerAccessibleKeystrokeListener() once for each combination.

eventmask :

 an AccessibleKeyMaskType mask indicating which types of key events are requested (SPI_KEY_PRESSED, etc.).

sync_type :

 a AccessibleKeyListenerSyncType parameter indicating the behavior of the notification/listener transaction.

Returns :

 TRUE if successful, otherwise FALSE.

SPI_deregisterAccessibleKeystrokeListener ()

SPIBoolean          SPI_deregisterAccessibleKeystrokeListener
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeyMaskType modmask);

Removes a keystroke event listener from the registry's listener queue, ceasing notification of events with modifiers matching modmask.

listener :

 a pointer to the AccessibleKeystrokeListener for which keystroke events are requested.

modmask :

 the key modifier mask for which this listener is to be 'deregistered' (of type AccessibleeyMaskType).

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleKeystrokeListener_unref ()

void                AccessibleKeystrokeListener_unref   (AccessibleKeystrokeListener *listener);

Decrements an AccessibleKeystrokeListener's reference count.

listener :

 a pointer to the AccessibleKeystrokeListener being operated on.

AccessibleKeystrokeListener_removeCallback ()

SPIBoolean          AccessibleKeystrokeListener_removeCallback
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeystrokeListenerCB callback);

Remove an in-process callback function from an existing AccessibleKeystrokeListener.

listener :

 the AccessibleKeystrokeListener instance to modify.

callback :

 an AccessibleKeystrokeListenerCB function pointer.

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleKeystrokeListener_addCallback ()

SPIBoolean          AccessibleKeystrokeListener_addCallback
                                                        (AccessibleKeystrokeListener *listener,
                                                         AccessibleKeystrokeListenerCB callback,
                                                         void *user_data);

Add an in-process callback function to an existing AccessibleKeystrokeListener.

listener :

 the AccessibleKeystrokeListener instance to modify.

callback :

 an AccessibleKeystrokeListenerCB function pointer.

user_data :

 a pointer to data which will be passed to the callback when invoked.

Returns :

 TRUE if successful, otherwise FALSE.

SPI_generateKeyboardEvent ()

SPIBoolean          SPI_generateKeyboardEvent           (long int keyval,
                                                         char *keystring,
                                                         AccessibleKeySynthType synth_type);

Synthesize a keyboard event (as if a hardware keyboard event occurred in the current UI context).

keyval :

 a long integer indicating the keycode or keysym of the key event being synthesized.

keystring :

 an (optional) UTF-8 string which, if keyval is NULL, indicates a 'composed' keyboard input string which is being synthesized; this type of keyboard event synthesis does not emulate hardware keypresses but injects the string as though a composing input method (such as XIM) were used.

synth_type :

 a AccessibleKeySynthType flag indicating whether keyval is to be interpreted as a keysym rather than a keycode (CSPI_KEYSYM), or whether to synthesize SPI_KEY_PRESS, SPI_KEY_RELEASE, or both (SPI_KEY_PRESSRELEASE).

Returns :

 TRUE if successful, otherwise FALSE.

SPI_generateMouseEvent ()

SPIBoolean          SPI_generateMouseEvent              (long int x,
                                                         long int y,
                                                         char *name);

Synthesize a mouse event at a specific screen coordinate. Most AT clients should use the AccessibleAction interface when tempted to generate mouse events, rather than this method. Event names: b1p = button 1 press; b2r = button 2 release; b3c = button 3 click; b2d = button 2 double-click; abs = absolute motion; rel = relative motion.

x :

 a long indicating the screen x coordinate of the mouse event.

y :

 a long indicating the screen y coordinate of the mouse event.

name :

 a string indicating which mouse event to be synthesized (e.g. "b1p", "b1c", "b2r", "rel", "abs").

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleDeviceEvent

typedef struct {
  long                   keyID;
  short                  keycode;
  char *                 keystring;
  long                   timestamp;
  AccessibleDeviceEventType type;
  unsigned short         modifiers;
  SPIBoolean             is_text;	
} AccessibleDeviceEvent;

A structure encapsulating information relevant to a device event notification.

AccessibleDeviceEvent is a struct which encapsulates a device event.

char *keystring;

 A symbolic name for the key or switch, or, if is_text is true, a string approximating the inserted text characters which would result from this event, if a text entry field has keyboard focus.

AccessibleDeviceEventType type;

 The AccessibleDeviceEventType identifying the specific type of event.

unsigned short modifiers;

SPIBoolean is_text;

 A boolean value indicating whether the event represents 'printable' text (i.e. whether it changes the current insertion buffer of a focussed text entry component or not). Whitespace is considered "printable" in this context, since it typically inserts characters into the buffer.

AccessibleDeviceEventMask

typedef unsigned long AccessibleDeviceEventMask;

AccessibleDeviceEventMask is a set of types of key events. It is used in SPI_registerDeviceEventListener to specify the events to be listener for.

enum AccessibleDeviceEventType

typedef enum {
  SPI_KEY_PRESSED  = 1<<0,
  SPI_KEY_RELEASED = 1<<1,
  SPI_BUTTON_PRESSED = 1<<2,
  SPI_BUTTON_RELEASED = 1<<3
} AccessibleDeviceEventType;

The type of an AccessibleDeviceEvent.

SPI_KEY_PRESSED

 A device key has been pressed.

SPI_KEY_RELEASED

 A device key has been released.

SPI_BUTTON_PRESSED

 A device button or switch (other than a keyboard key) has been pressed.

SPI_BUTTON_RELEASED

 A device button or switch has been released.

AccessibleDeviceListenerCB ()

SPIBoolean          (*AccessibleDeviceListenerCB)       (const AccessibleDeviceEvent *stroke,
                                                         void *user_data);

A callback function prototype via which clients receive device event notifications.

This is a function which is specified when creating a DeviceListener. It is called when an event being listened for occurs.

stroke :

 The AccessibleDeviceEvent for which notification is being received.

user_data :

 Data which is passed to the client each time this callback is notified.

Returns :

 TRUE if the client wishes to consume/preempt the event, preventing it from being relayed to the currently focussed application, FALSE if the event delivery should proceed as normal.

SPI_createAccessibleDeviceListener ()

AccessibleDeviceListener * SPI_createAccessibleDeviceListener
                                                        (AccessibleDeviceListenerCB callback,
                                                         void *user_data);

Create a new AccessibleDeviceListener with a specified callback function.

callback :

 an AccessibleDeviceListenerCB callback function, or NULL.

user_data :

 a pointer to data which will be passed to the callback when invoked.

Returns :

 a pointer to a newly-created AccessibleDeviceListener.

SPI_registerDeviceEventListener ()

SPIBoolean          SPI_registerDeviceEventListener     (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceEventMask eventmask,
                                                         void *filter);

Register a listener for device events, for instance button events.

listener :

 a pointer to the AccessibleDeviceListener which requests the events.

eventmask :

 an AccessibleDeviceEventMask mask indicating which types of key events are requested (SPI_KEY_PRESSED, etc.).

filter :

 Unused parameter.

Returns :

 TRUE if successful, otherwise FALSE.

SPI_deregisterDeviceEventListener ()

SPIBoolean          SPI_deregisterDeviceEventListener   (AccessibleDeviceListener *listener,
                                                         void *filter);

Removes a device event listener from the registry's listener queue, ceasing notification of events of the specified type.

listener :

 a pointer to the AccessibleDeviceListener for which device events are requested.

filter :

 Unused parameter.

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleDeviceListener_addCallback ()

SPIBoolean          AccessibleDeviceListener_addCallback
                                                        (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceListenerCB callback,
                                                         void *user_data);

Add an in-process callback function to an existing AccessibleDeviceListener.

listener :

 the AccessibleDeviceListener instance to modify.

callback :

 an AccessibleDeviceListenerCB function pointer.

user_data :

 a pointer to data which will be passed to the callback when invoked.

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleDeviceListener_removeCallback ()

SPIBoolean          AccessibleDeviceListener_removeCallback
                                                        (AccessibleDeviceListener *listener,
                                                         AccessibleDeviceListenerCB callback);

Remove an in-process callback function from an existing AccessibleDeviceListener.

listener :

 the AccessibleDeviceListener instance to modify.

callback :

 an AccessibleDeviceListenerCB function pointer.

Returns :

 TRUE if successful, otherwise FALSE.

AccessibleDeviceListener_unref ()

void                AccessibleDeviceListener_unref      (AccessibleDeviceListener *listener);

Decrements an AccessibleDeviceListener's reference count.

listener :

 a pointer to the AccessibleDeviceListener being operated on.