Accessibility (4.6.3)

Introduction
Accessibility in computer software is making applications usable for people with disabilities.

An application does not usually communicate directly with assistive tools but through an assistive technology, which is a bridge for exchange of information between the applications and the tools.

Qt supports
Windows : Microsoft Active Accessibility (MSAA)
Mac OS X: Mac OS X Accessibility
Unix/X11: Support is preliminary

The individual technologies are abstracted from Qt, and there is only a single interface to consider.

================================================================================
Architecture
Providing accessibility is a collaboration between accessibility compliant applications, the assistive technology, and the assistive tools.

Accessibility compliant applications are called AT-Servers while assistive tools are called AT-Clients.
AT-Server <----> "Assistive Technology" <----> AT-Clients

================================================================================
Accessibility in Qt

These classes provide support for accessible applications.

QAccessible                   Enums and static functions relating to accessibility
QAccessibleBridge              The base class for accessibility back-ends
QAccessibleBridgePlugin       Abstract base for accessibility bridge plugins
QAccessibleEvent              Used to query addition accessibility information about complex widgets
QAccessibleInterface          Defines an interface that exposes information about accessible objects
QAccessibleObject              Implements parts of the QAccessibleInterface for QObjects
QAccessiblePlugin              Abstract base for accessibility plugins
QAccessibleWidget              Implements the QAccessibleInterface for QWidgets

Qt applications use QAccessibleInterface to expose information about the individual UI elements.
Currently, Qt provides support for its widgets and widget parts, e.g., slider handles, but the interface could also be implemented for any QObject if necessary.

The structure of the UI is represented as a tree of QAccessibleInterface subclasses.

Servers notify clients through QAccessible::updateAccessibility(QObject * object, int child, Event reason) about changes in objects by sending events, and the clients register to receive the events.
The clients may then query for the object that generated the event through QAccessible::queryAccessibleInterface(QObject * object), return QAccessibleInterface * .

Three of the enums in QAccessible help clients query and alter accessible objects:
Role    : Describes the role the object fills in the user interface, e.g., if it is a main window, a text caret, or a cell in an item view.
Action  : The actions that the clients can perform on the objects, e.g., pushing a button.
Relation: Describes the relationship between objects in the object tree. This is used for navigation.

The clients also have some possibilities to get the content of objects, e.g., a button's text; the object provides strings defined by the QAccessible::Text enum, that give information about content.

The objects can be in a number of different states as defined by the State enum. Examples of states are whether the object is disabled, if it has focus, or if it provides a pop-up menu.

================================================================================
The Accessible Object Tree

A tree structure is built from the accessible objects of an application. By navigating through the tree, the clients can access all elements in the UI.

There are no direct mapping between the Qt QObject tree and the accessible object tree.

AT-Clients have access to the accessibility object tree through the root object in the tree, which is the QApplication. They can query other objects through QAccessible::navigate(), which fetches objects based on Relations.

The children of any node is 1-based numbered. The child numbered 0 is the object itself.

Qt provides accessible interfaces for its widgets. Interfaces for any QObject subclass can be requested through QAccessible::queryInterface().

An AT-Client cannot acquire an interface for accessible objects that do not have an equivalent QObject, but they appear as normal objects through interfaces of parent accessible objects, e.g., you can query their relationships with QAccessible::relationTo().

================================================================================
The Static QAccessible Functions

QAccessible's static functions:
1)produce QAccessible interfaces
2)build the object tree
3)initiate the connection with MSAA or the other platform specific technologies

The communication between clients and the server is initiated when QAccessible::setRootObject(QObject * object) is called.

When a QObject calls QAccessible::updateAccessibilit(QObject * object, int child, Event reason ), clients that are listening to events are notified of the change.

The function is used to post events to the assistive technology.

QAccessible::queryAccessibleInterface(QObject * object) returns accessible interfaces for QObjects. All widgets in Qt provide interfaces; if you need interfaces to control the behavior of other QObject subclasses, you must implement the interfaces yourself, although the QAccessibleObject convenience class implements parts of the functionality for you.

The factory that produces accessibility interfaces for QObjects is a function of type QAccessible::InterfaceFactory.

================================================================================
Enabling Accessibility Support

By default, Qt applications are run with accessibility support enabled on Windows and Mac OS X.
On Unix/X11 platforms, applications must be launched in an environment with the QT_ACCESSIBILITY variable set to 1.
export QT_ACCESSIBILITY=1

Accessibility features are built into Qt by default when the libraries are configured and built.

================================================================================
Implementing Accessibility

Implement the QAccessibleInterface and distribute it in a QAccessiblePlugin.
1)Qt already implements accessibility for its own widgets. We therefore recommend that you use Qt widgets where possible.
2)A QAccessibleInterface needs to be implemented for each element that you want to make available to accessibility clients.
3)You need to send accessibility events from the custom user interface elements that you implement.

It is possible to implement interfaces by inheriting QAccessibleInterface and implementing its pure virtual functions.
In practice, however, it is usually preferable to inherit QAccessibleObject or QAccessibleWidget, which implement part of the functionality for you.

================================================================================
The QAccessibleObject and QAccessibleWidget Convenience Classes

QAccessibleObject implements part of the interface for QObjects.
QAccessibleWidget is a convenience class for widgets.

The QAccessibleWidget provides the following functionality:
1)It handles the navigation of the tree and hit testing of the objects.
2)It handles events, roles, and actions that are common for all QWidgets.
3)It handles action and methods that can be performed on all widgets.
4)It calculates bounding rectangles with rect().
5)It gives text() strings that are appropriate for a generic widget.
6)It sets the states that are common for all widgets.

================================================================================
QAccessibleWidget Example

Relation QAccessibleInterface::relationTo ( int child, const QAccessibleInterface * other, int otherChild ) const;
int QAccessibleInterface::navigate ( RelationFlag relation, int entry, QAccessibleInterface ** target ) const;
void QAccessibleWidget::addControllingSignal(const QString & signal);
We use QLatin1String to ensure that the signal name is correctly specified.
void QAccessible::updateAccessibility(this, 0, QAccessible::ValueChanged);

Note that the call is made after the value of the slider has changed because clients may query the new value immediately after receiving the event.

The interface must be able to calculate bounding rectangles of itself and any children that do not provide an interface of their own.

QPoint QWidget::mapToGlobal(const QPoint & pos) const;
int QAccessibleInterface::childCount() const;
QString QAccessibleInterface::text(Text t, int child) const;
Role QAccessibleInterface::role ( int child ) const;
State QAccessibleWidget::state(int child) const;

================================================================================
Handling Action Requests from Clients
QString QAccessibleInterface::actionText ( int action, Text t, int child ) const;
    Returns strings that describe each action. The descriptions to be made available are one for each Text enum value.
bool QAccessibleInterface::doAction(int action, int child, const QVariantList & params = QVariantList());
    doAction() executes requests from clients to perform actions.
int QAccessibleInterface::userActionCount(int child) const;

QAccessibleInterface gives another technique for clients to handle accessible objects. It works basically the same way, but uses the concept of methods in place of actions.

QAccessible::Method
    QAccessible::ListSupportedMethods
    QAccessible::SetCursorPosition
    QAccessible::GetCursorPosition

QSet<Method> QAccessibleInterface::supportedMethods() : returns a QSet of Method values that are supported by the object.
QVariant QAccessibleInterface::invokeMethod(Method method, int child = 0, const QVariantList & params =
QVariantList()) : executes methods requested by clients.

================================================================================
Implementing Accessible Plugins

QStringList QAccessiblePlugin::keys() const;
QAccessibleInterface * QAccessiblePlugin::create(const QString & key, QObject * object);

Q_EXPORT_STATIC_PLUGIN(SliderPlugin) : You can omit this unless you want the plugin to be statically linked with the application.
Q_EXPORT_PLUGIN2(acc_sliderplugin, SliderPlugin) : Exports the plugin in the SliderPlugin class into the acc_sliderplugin library.

================================================================================
Implementing Interface Factories

If you do not want to provide plugins for your accessibility interfaces, you can use an interface factory (QAccessible::InterfaceFactory), which is the recommended way to provide accessible interfaces in a statically-linked application.

A factory is a function pointer for a function that takes the same parameters as QAccessiblePlugin's create() - a QString and a QObject.

void QAccessible::installFactory(InterfaceFactory factory);