Skip to content

start:

UNO Accessibility API

The UNO Accessibility API (also called UAA in the following) is modeled closely after Java Accessibility API in version 1.4 and the the Gnome Accessibility API. The UAA is part of the offapi project. You can browse the CVS archive at com/sun/star/accessibility or have a look at the documentation here.

Representation of GUI and documents

The UAA represents both structure and content of the GUI. Here GUI included the views of documents that are embedded therein.

Structure

Each top-level window of the GUI is represented as a tree of accessibility objects. Each accessibility object stands for one GUI element or one object of a document view:

  • Leaves
    Some GUI elements are represented by leaves in the tree. Such elements are for example labels and buttons
  • Internal nodes
    Other GUI elements are represented by internal nodes and thus have a sub-tree of their own. An example for this are frames, menus and tool-bars. Menu items can be both depending of whether they have a sub-menu.
  • Root
    The root of every tree represents a top level window. This means that the accessibility representation of a running OpenOffice.org is actually a forest of accessibility trees.

This tree structure is realized by implementing the XAccessibleContext interface. To go up towards the root of a tree you can get an object's parent. To go down towards the leaves of a tree you can retrieve all the children of an object.

Relations
Relations introduce a secondary structure that is independent of the tree hierarchy created by the parent/child relationship provided by the XAccessibleContext interface. Relation sets as returned by the XAccessibleContext::getAccessibleRelationSet() are defined by the XAccessibleRelationSet interface.

Content

Each node of the tree that implements XAccessibleContext gives access to different facets of the represented GUI element or document part. These are

name
The name is a localized string and acts as short, one word description, this is e.g. the text displayed on a button.
role
The kind of control or document part. E.g. the role of a button is "button". With the AccessibleRole collection of constants there is a set of predefined roles that is suitable for the elements of the GUI whereas there are no (not yet) roles for the direct support of the document.
description
A localized string description that is longer and more specific than the name.
state
States of GUI elements as described by the AccessibleStateType constants collection can be for example "active", "hidden", or "checked". Again there is a predefined set of states suitable for GUI elements but maybe not sufficient to represent states of document parts.
actions
This active part of a node content can for instance open a pop up window with a context sensitive menu. Another example are additional navigational commands. Actions are represented by the AccessibleRole service. In general there should be as few actions as possible. It is better to offer additional functionality through the clasical means of the GUI.
graphical representation
The graphical representation of an accessible object is exposed by the XAccessibleComponent interface. It can be queried for instance for its bounding-box or for the child node at a given point on the screen.
content
The actual content of a node of the accessibility tree can have different forms:

Events

The tree modeled by the UAA is not a static data structure. Because of scrolling the document window, changing its content, or modifying the contents of GUI controls, the structure and content of single nodes and sub-trees is constantly changing. These changes are notified to the AT by sending events to registered listeners (among them the AT). The kind of event that is sent for a specific change depends on the UAA interfaces that the node that represents the modified object does support and on the actual implementation of these interfaces. Listeners to accessibility events implement the XAccessibleEventListener interface while broadcasters implement the XAccessibleEventBroadcaster interface. Events are AccessibleEventObject structures, their types are described in the AccessibleEventId constants group.

Independent implementation of the UAA

The XAccessible interface allows the decoupling of the implementation of the UAA from the implementation of the rest of the UNO API. Its only method, getAccessibleContext(), returns an object that implements the AccessibleContext service. This may or may not be done by a class other than the one that implements the XAccessible interface. This has the big advantage, that the existing API implementation needs only minimal modifications.

Differences between the Accessibility APIs of UNO and Java

Here is a list of major differences between the UNO and the Java Accessibility APIs:

Documentation of the UNO Accessibility API

More details of the UAA can be found in the API reference.

The services that expose application specific details of the UAA can be found here for the GUI, Writer, Calc, Draw/Impress, and Chart.