atspi-registry

## atspi-registry atspi-registry — A service through which applications providing accessibility services can rendezvous with consumers of those services. |

## Synopsis

    GType               atspi_key_definition_get_type       ();
    gint                atspi_get_desktop_count             ();
    AtspiAccessible *   atspi_get_desktop                   (gint i);
    GArray *            atspi_get_desktop_list              ();
    gboolean            atspi_register_keystroke_listener   (AtspiDeviceListener *listener,
                                                             GArray *key_set,
                                                             AtspiKeyMaskType modmask,
                                                             AtspiKeyEventMask event_types,
                                                             gint sync_type,
                                                             GError **error);
    gboolean            atspi_deregister_keystroke_listener (AtspiDeviceListener *listener,
                                                             GArray *key_set,
                                                             AtspiKeyMaskType modmask,
                                                             AtspiKeyEventMask event_types,
                                                             GError **error);
    gboolean            atspi_register_device_event_listener
                                                            (AtspiDeviceListener *listener,
                                                             AtspiDeviceEventMask event_types,
                                                             void *filter,
                                                             GError **error);
    gboolean            atspi_deregister_device_event_listener
                                                            (AtspiDeviceListener *listener,
                                                             void *filter,
                                                             GError **error);
    gboolean            atspi_generate_keyboard_event       (glong keyval,
                                                             const gchar *keystring,
                                                             AtspiKeySynthType synth_type,
                                                             GError **error);
    gboolean            atspi_generate_mouse_event          (glong x,
                                                             glong y,
                                                             const gchar *name,
                                                             GError **error);

## Description

A service through which applications providing accessibility services (servers) can rendezvous with consumers of those services (Assistive Technologies). The atspi-registry is the first "port of call" for accessible applications and for assistive technologies wishing to query and interact with those applications.

## Details

### atspi_key_definition_get_type ()

    GType               atspi_key_definition_get_type       ();

### atspi_get_desktop_count ()

    gint                atspi_get_desktop_count             ();

Gets the number of virtual desktops. NOTE: multiple virtual desktops are not implemented yet; as a consequence, this function always returns 1.

Returns : | a gint indicating the number of active virtual desktops.

### atspi_get_desktop ()

    AtspiAccessible *   atspi_get_desktop                   (gint i);

Gets the virtual desktop indicated by index `i`. NOTE: currently multiple virtual desktops are not implemented; as a consequence, any `i` value different from 0 will not return a virtual desktop - instead it will return NULL.

`i` : | a gint indicating which of the accessible desktops is to be returned.
Returns : | a pointer to the `i`-th virtual desktop's AtspiAccessible representation. [transfer full]

### atspi_get_desktop_list ()

    GArray *            atspi_get_desktop_list              ();

Gets 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. NOTE: currently multiple virtual desktops are not implemented; this implementation always returns a Garray with a single AtspiAccessible desktop.

Returns : | a GArray of desktops. [transfer full]

### atspi_register_keystroke_listener ()

    gboolean            atspi_register_keystroke_listener   (AtspiDeviceListener *listener,
                                                             GArray *key_set,
                                                             AtspiKeyMaskType modmask,
                                                             AtspiKeyEventMask event_types,
                                                             gint sync_type,
                                                             GError **error);

Registers a listener for keystroke events, either pre-emptively for all windows (ATSPI_KEYLISTENER_ALL_WINDOWS), non-preemptively (ATSPI_KEYLISTENER_NOSYNC), or pre-emptively at the toolkit level (ATSPI_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 AtspiDeviceListener for which keystroke events are requested.
`key_set` : | a pointer to the AtspiKeyDefinition array indicating which keystroke events are requested, or NULL to indicate that all keycodes and keyvals for the specified modifier set are to be included. [element-type AtspiKeyDefinition][allow-none]
`modmask` : | an AtspiKeyMaskType 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 atspi_register_keystroke_listener once for each combination.
`event_types` : | an AtspiKeyMaskType mask indicating which types of key events are requested (ATSPI_KEY_PRESSED etc.).
`sync_type` : | an AtspiKeyListenerSyncType parameter indicating the behavior of the notification/listener transaction.
Returns : | TRUE if successful, otherwise FALSE.

### atspi_deregister_keystroke_listener ()

    gboolean            atspi_deregister_keystroke_listener (AtspiDeviceListener *listener,
                                                             GArray *key_set,
                                                             AtspiKeyMaskType modmask,
                                                             AtspiKeyEventMask event_types,
                                                             GError **error);

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

`listener` : | a pointer to the AtspiDeviceListener for which keystroke events are requested.
`key_set` : | a pointer to the AtspiKeyDefinition array indicating which keystroke events are requested, or NULL to indicate that all keycodes and keyvals for the specified modifier set are to be included. [element-type AtspiKeyDefinition][allow-none]
`modmask` : | the key modifier mask for which this listener is to be 'deregistered' (of type AtspiKeyMaskType).
`event_types` : | an AtspiKeyMaskType mask indicating which types of key events were requested (ATSPI_KEY_PRESSED, etc.).
Returns : | TRUE if successful, otherwise FALSE.

### atspi_register_device_event_listener ()

    gboolean            atspi_register_device_event_listener
                                                            (AtspiDeviceListener *listener,
                                                             AtspiDeviceEventMask event_types,
                                                             void *filter,
                                                             GError **error);

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

`listener` : | a pointer to the AtspiDeviceListener which requests the events.
`event_types` : | an AtspiDeviceEventMask mask indicating which types of key events are requested (ATSPI_KEY_PRESSED, etc.).
`filter` : | Unused parameter.
Returns : | TRUE if successful, otherwise FALSE.

### atspi_deregister_device_event_listener ()

    gboolean            atspi_deregister_device_event_listener
                                                            (AtspiDeviceListener *listener,
                                                             void *filter,
                                                             GError **error);

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

`listener` : | a pointer to the AtspiDeviceListener for which device events are requested.
`filter` : | Unused parameter.
Returns : | TRUE if successful, otherwise FALSE.

### atspi_generate_keyboard_event ()

    gboolean            atspi_generate_keyboard_event       (glong keyval,
                                                             const gchar *keystring,
                                                             AtspiKeySynthType synth_type,
                                                             GError **error);

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

`keyval` : | a gint 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 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` : | an AtspiKeySynthType flag indicating whether `keyval` is to be interpreted as a keysym rather than a keycode (ATSPI_KEYSYM), or whether to synthesize ATSPI_KEY_PRESS, ATSPI_KEY_RELEASE, or both (ATSPI_KEY_PRESSRELEASE).
Returns : | TRUE if successful, otherwise FALSE.

### atspi_generate_mouse_event ()

    gboolean            atspi_generate_mouse_event          (glong x,
                                                             glong y,
                                                             const gchar *name,
                                                             GError **error);

Synthesizes 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 glong indicating the screen x coordinate of the mouse event.
`y` : | a glong 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.