Atspi – 2.0
Description: Reference for Atspi-2.0

### Namespace

# Atspi – 2.0

The Assistive Technology Service Provider Interface, version 2

Version | 2.48.0
Authors | The AT-SPI2 maintainers
License | LGPL-2.1-or-later
Website | https://wiki.gnome.org/Accessibility
Source | https://gitlab.gnome.org/GNOME/at-spi2-core/

#### Build

C headers | `atspi/atspi.h`
pkg-config files | `atspi-2`

#### Dependencies

GObject—2.0 | The base type system library
| Browse documentation

#### Related libraries

Atk | The Accessibility toolkite
| Browse documentation

#### Additional documentation

- Classes Hierarchy

#### Classes

Accessible | The base interface which is implemented by all accessible objects.
Application | An interface identifying the root object associated with a running application.
Device |
DeviceLegacy |
DeviceListener |
DeviceX11 |
EventListener | A generic interface implemented by objects for the receipt of event notifications.
Hyperlink | Instances of atspi-hyperlink are the means by which end users and clients interact with linked content.
MatchRule | An interface that allows the definition of match rules for accessible objects.
Object |
Relation | An interface via which non-hierarchical relationships are indicated.
StateSet | The atspi-stateset objects implement wrappers around a bitmap of accessible states.

#### Interfaces

Action |
Collection | An interface designed to allow accessibles which satisfy a set of criteria to be returned.
Component | An interface implemented by objects which have onscreen visual representations.
Document |
EditableText |
Hypertext | An interface used for objects which implement linking between multiple resource locations.
Image |
Selection | An interface which indicates that an object exposes a ‘selection’ model, allowing the selection of one or more of its children.
Table | An interface used by containers whose data is arranged in a tabular form.
TableCell |
Text | An interface implemented by objects which place textual information onscreen.
Value | An interface supporting a one-dimensional scalar to be modified, or which reflects its value.

#### Structs

DeviceEvent |
Event |
EventListenerMode |
KeyDefinition |
KeySet | Structure containing identifying information about a set of keycode or keysyms.
Point |
Range |
Rect |
TextRange |

#### Aliases

ControllerEventMask |
DeviceEventMask |
KeyEventMask |
KeyMaskType |
KeystrokeListener |

#### Enumerations

CollectionMatchType | Enumeration used by `AtspiMatchRule` to specify how to interpret `AtspiAccessible` objects.
CollectionSortOrder | Enumeration used by interface `AtspiCollection` to specify the way `AtspiAccesible` objects should be sorted.
CollectionTreeTraversalType | Enumeration used by interface `AtspiCollection` to specify restrictions on `AtspiAccesible` objects to be traversed.
ComponentLayer | The `AtspiComponentLayer` of an `AtspiComponent` instance indicates its relative stacking order with respect to the onscreen visual representation of the UI. `AtspiComponentLayer`, in combination with `AtspiComponent` bounds information, can be used to compute the visibility of all or part of a component. This is important in programmatic determination of region-of-interest for magnification, and in flat screen review models of the screen, as well as for other uses. Objects residing in two of the `AtspiComponentLayer` categories support further z-ordering information, with respect to their peers in the same layer: namely, `ATSPI_LAYER_WINDOW` and `ATSPI_LAYER_MDI`. Relative stacking order for other objects within the same layer is not available; the recommended heuristic is first child paints first. In other words, assume that the first siblings in the child list are subject to being overpainted by later siblings if their bounds intersect. The order of layers, from bottom to top, is: `ATSPI_LAYER_BACKGROUND`, `ATSPI_LAYER_WINDOW`, `ATSPI_LAYER_MDI`, `ATSPI_LAYER_CANVAS`, `ATSPI_LAYER_WIDGET`, `ATSPI_LAYER_POPUP`, and `ATSPI_LAYER_OVERLAY`.
CoordType | Enumeration used by `AtspiComponent`, `AtspiImage`, and `AtspiText` interfaces to specify whether coordinates are relative to the window or the screen.
EventType | Enumeration used to specify the event types of interest to an `AtspiEventListener`, or to identify the type of an event for which notification has been sent.
KeyEventType | Deprecated. Should not be used.
KeySynthType | Enumeration used when synthesizing keyboard input via # atspi_generate_keyboard_event.
LocaleType | Used by interfaces `AtspiText` and `AtspiDocument`, this enumeration corresponds to the POSIX ‘setlocale’ enum values.
ModifierType |
RelationType | `AtspiRelationType` specifies a relationship between objects (possibly one-to-many or many-to-one) outside of the normal parent/child hierarchical relationship. It allows better semantic identification of how objects are associated with one another. For instance the `ATSPI_RELATION_LABELLED_BY` relationship may be used to identify labelling information that should accompany the accessible name property when presenting an object’s content or identity to the end user. Similarly, `ATSPI_RELATION_CONTROLLER_FOR` can be used to further specify the context in which a valuator is useful, and/or the other UI components which are directly effected by user interactions with the valuator. Common examples include association of scrollbars with the viewport or panel which they control.
Role | Enumeration used by interface `AtspiAccessible` to specify the role of an `AtspiAccessible` object.
ScrollType | Enumeration used by interface `AtspiAccessible` to specify where an `AtspiAccessible` object should be placed on the screen when using scroll_to.
StateType | Enumeration used by various interfaces indicating every possible state an `AtspiAccesible` object can assume.
TextBoundaryType | Specifies the boundary conditions determining a run of text as returned from # atspi_text_get_text_at_offset, #atspi_text_get_text_after_offset, and # atspi_text_get_text_before_offset.
TextClipType | Enumeration used by interface `AtspiText` to indicate how to treat characters intersecting bounding boxes.
TextGranularity | Text granularity types used for specifying the granularity of the region of text we are interested in.

#### Bitfields

Cache |
KeyListenerSyncType | Specifies the type of a key listener event. The values above can and should be bitwise-‘OR’-ed together, observing the compatibility limitations specified in the description of each value. For instance, #ATSPI_KEYLISTENER_ALL_WINDOWS | #ATSPI_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.

#### Callbacks

DeviceListenerCB | A callback function prototype via which clients receive device event notifications.
DeviceListenerSimpleCB | Similar to `AtspiDeviceListenerCB`, but with no user data.
EventListenerCB | A function prototype for callbacks via which clients are notified of AT-SPI events.
EventListenerSimpleCB | Like `AtspiEventlistenerCB`, but with no user_data.
KeyCallback | A callback that will be invoked when a key is pressed.

#### Functions

dbus_connection_setup_with_g_main | Sets the watch and timeout functions of a `DBusConnection` to integrate the connection with the GLib main loop. Pass in `NULL` for the `GMainContext` unless you’re doing something specialized.
dbus_server_setup_with_g_main | Sets the watch and timeout functions of a `DBusServer` to integrate the server with the GLib main loop. In most cases the context argument should be `NULL`.
deregister_device_event_listener | Removes a device event listener from the registry’s listener queue, ceasing notification of events of the specified type.
deregister_keystroke_listener | Removes a keystroke event listener from the registry’s listener queue, ceasing notification of events with modifiers matching `modmask`.
exit | Disconnects from `AtspiRegistry` instances and releases any floating resources. Call only once at exit.
generate_keyboard_event | Synthesizes a keyboard event (as if a hardware keyboard event occurred in the current UI context).
generate_mouse_event | 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.
get_a11y_bus |
get_desktop | 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.
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.
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.
init | Connects to the accessibility registry and initializes the SPI.
is_initialized | Indicates whether AT-SPI has been initialized.
register_device_event_listener | This function does nothing and should not be called.
register_keystroke_listener | 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).
set_main_context | Sets the main loop context that AT-SPI should assume is in use when setting an idle callback. This function should be called by application-side implementors (ie, at-spi2-atk) when it is desirable to re-enter the main loop.
set_reference_window | 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.
set_timeout | Set the timeout used for method calls. If this is not set explicitly, a default of 800 ms is used. Note that at-spi2-registryd currently uses a timeout of 3 seconds when sending a keyboard event notification. This means that, if an AT makes a call in response to the keyboard notification and the application being called does not respond before the timeout is reached, at-spi2-registryd will time out on the keyboard event notification and pass the key onto the application (ie, reply to indicate that the key was not consumed), so this may make it undesirable to set a timeout larger than 3 seconds.

#### Constants

COMPONENTLAYER_COUNT | One higher than the highest valid value of `AtspiComponentLayer`.
COORD_TYPE_COUNT | One higher than the highest valid value of `AtspiCoordType`.
DBUS_INTERFACE_ACCESSIBLE |
DBUS_INTERFACE_ACTION |
DBUS_INTERFACE_APPLICATION |
DBUS_INTERFACE_CACHE |
DBUS_INTERFACE_COLLECTION |
DBUS_INTERFACE_COMPONENT |
DBUS_INTERFACE_DEC |
DBUS_INTERFACE_DEVICE_EVENT_LISTENER |
DBUS_INTERFACE_DOCUMENT |
DBUS_INTERFACE_EDITABLE_TEXT |
DBUS_INTERFACE_EVENT_KEYBOARD |
DBUS_INTERFACE_EVENT_MOUSE |
DBUS_INTERFACE_EVENT_OBJECT |
DBUS_INTERFACE_EVENT_SCREEN_READER |
DBUS_INTERFACE_HYPERLINK |
DBUS_INTERFACE_HYPERTEXT |
DBUS_INTERFACE_IMAGE |
DBUS_INTERFACE_REGISTRY |
DBUS_INTERFACE_SELECTION |
DBUS_INTERFACE_SOCKET |
DBUS_INTERFACE_TABLE |
DBUS_INTERFACE_TABLE_CELL |
DBUS_INTERFACE_TEXT |
DBUS_INTERFACE_VALUE |
DBUS_NAME_REGISTRY |
DBUS_PATH_DEC |
DBUS_PATH_NULL |
DBUS_PATH_REGISTRY |
DBUS_PATH_ROOT |
DBUS_PATH_SCREEN_READER |
EVENTTYPE_COUNT | One higher than the highest valid value of `AtspiEventType`.
KEYEVENTTYPE_COUNT | One higher than the highest valid value of `AtspiKeyEventType`.
KEYSYNTHTYPE_COUNT | One higher than the highest valid value of `AtspiKeySynthType`.
LOCALE_TYPE_COUNT | One higher than the highest valid value of `AtspiLocaleType`.
MATCHTYPES_COUNT |
MODIFIERTYPE_COUNT | One higher than the highest valid value of `AtspiModifierType`.
RELATIONTYPE_COUNT | One higher than the highest valid value of `AtspiRelationType`.
ROLE_COUNT | One higher than the highest valid value of `AtspiRole`.
SCROLLTYPE_COUNT | One higher than the highest valid value of `AtspiScrollType`.
SORTORDER_COUNT | One higher than the highest valid value of `AtspiCollectionSortOrder`.
STATETYPE_COUNT | One higher than the highest valid value of `AtspiStateType`.
TEXT_BOUNDARY_TYPE_COUNT | One higher than the highest valid value of `AtspiTextBoundaryType`.
TEXT_CLIP_TYPE_COUNT | One higher than the highest valid value of `AtspiTextClipType`.
TREETRAVERSALTYPE_COUNT | One higher than the highest valid value of # AtspiCollection_TreeTraversalType.