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:

• Text is represented by the interfaces XAccessibleText (read only) and XAccessibleEditableText. There is also the interface XAccessibleHypertext for texts that contain hyperlinks.
• Tables are represented by the interface XAccessibleTable.
• Images are represented by the interface XAccessibleImage.
• Simple numerical values, like the position of a slider or the value of a spin box are represented by the XAccessibleValue interface.

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:

• Java interfaces AccessibleComponent and AccessibleExtendedComponent have been rearranged into the UAA interfaces XAccessibleComponent and XAccessibleExtendedComponent.

• Java interfaces AccessibleTable and AccessibleExtendedTable have been merged into the single UNO interface XAccessibleTable.

• Java interfaces AccessibleText and AccessibleEditableText have been rearranged into the UAA interfaces XAccessibleText and XAccessibleEditableText to better reflect the read only and read/write access to text.

• The Java class AccessibleBundle is not supported, because it is not necessary in the UNO environment.

• The Java class AccessibleResourceBundle is not supported, because it is deprecated in the Java API.

• The Java classes AccessibleRelation, AccessibleRole, and AccessibleState are realized by UNO constants collections AccessibleRelationType, AccessibleRole, and AccessibleStateType due to different API designs.

• The Java interface AccessibleIcon has been renamed into the UNO interface XAccessibleImage to represent its more general approach.

• The methods of the Java class AccessibleHyperlink regarding actions have been removed. Instead the UNO service AccessibleHyperlink supports in addition to the interface XAccessibleHyperlink also the XAccessibleAction interface.

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.