atspi-registry: libatspi Reference Manual

## atspi-registry atspi-registry |

## Functions

GType | atspi_key_definition_get_type ()
gint | atspi_get_desktop_count ()
AtspiAccessible * | atspi_get_desktop ()
GArray * | atspi_get_desktop_list ()
gboolean | atspi_register_keystroke_listener ()
gboolean | atspi_deregister_keystroke_listener ()
gboolean | atspi_register_device_event_listener ()
gboolean | atspi_deregister_device_event_listener ()
gboolean | atspi_generate_keyboard_event ()
gboolean | atspi_generate_mouse_event ()
void | atspi_set_reference_window ()

## Description

## Functions

### 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.

#### Parameters

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.

[element-type AtspiAccessible*][transfer full]

### atspi_register_keystroke_listener ()

    gboolean
    atspi_register_keystroke_listener (AtspiDeviceListener *listener,
                                       GArray *key_set,
                                       AtspiKeyMaskType modmask,
                                       AtspiKeyEventMask event_types,
                                       AtspiKeyListenerSyncType 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).

#### Parameters

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. |
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### 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` .

#### Parameters

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.). |
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### 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.

#### Parameters

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. | [allow-none]
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### 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.

#### Parameters

listener | a pointer to the AtspiDeviceListener for which device events are requested. |
filter | Unused parameter. | [allow-none]
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### 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).

#### Parameters

keyval | a gint indicating the keycode or keysym or modifier mask of the key event being synthesized. |
keystring | an (optional) UTF-8 string which, if `synth_type` is `ATSPI_KEY_STRING`, 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. | [allow-none]
synth_type | an AtspiKeySynthType flag indicating whether `keyval` is to be interpreted as a keysym rather than a keycode (`ATSPI_KEY_SYM`) or a string (`ATSPI_KEY_STRING`) or a modifier mask (`ATSPI_KEY_LOCKMODIFIERS` and `ATSPI_KEY_UNLOCKMODIFIERS`), or whether to synthesize `ATSPI_KEY_PRESS`, `ATSPI_KEY_RELEASE`, or both (`ATSPI_KEY_PRESSRELEASE`). |
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### 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.

#### Parameters

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"). |
error | a pointer to a `NULL` GError pointer, or `NULL`. | [allow-none]

#### Returns

`TRUE` if successful, otherwise `FALSE`.

### atspi_set_reference_window ()

    void
    atspi_set_reference_window (AtspiAccessible *accessible);

Sets the reference window that will be used when atspi_generate_mouse_event is called. Coordinates will be assumed to be relative to this window. This is needed because, due to Wayland's security model, it is not currently possible to retrieve global coordinates. If NULL is passed, then AT-SPI will use the window that has focus at the time that atspi_generate_mouse_event is called.

#### Parameters

accessible | the AtspiAccessible corresponding to the window to select. should be a top-level window with a role of ATSPI_ROLE_APPLICATION. |