Qt Accessibility

[toc align_right="yes" depth="3"]

Accessibility for Qt Quick

This page is documenting the ongoing accessibility project in QtDF. The focus of the project is to implement cross-platform accessibility support for Qt Quick.

The document is organized in several sections according to the target audience, sorted by general relevance. (There will be relatively many Qt Component users compared to accessibility backend developers.)

Practical

Accessibility support is developed primarily for Qt Quick 2 (QML on scene graph). There is also some work to make it available for 4.8.

Source Code:
|What|Where|Branch|Notes|
|Qt (scene graph)|http://qt.gitorious.org/+qt-developers/qt/staging%7Cqml-team/qtquick2-accessibility%7COutdated, will move to a branch in Qt5 soon|
|Qt (fixes for 4.8)|https://qt.gitorious.org/+qt-developers/qt/accessibility%7C4.8-a11y%7CWill not be further developed, here for reference while porting to Qt5|
|Components (desktop)|http://qt.gitorious.org/qt-components/desktop%7Cscenegraph-accessibility%7C%7C

QML and Qt Component Users

The easiest way to create accessible applications is to use Qt Components, which will have built-in accessibility support.

Some rules to be aware of (based on early implementation experience):

• The accessibility system prefers "self-contained" item hierarchies, where child items are inside their parent geometry.
• Well-behaved items have correct geometry (height, width) at all times.
• Set the "visible" property to false when hiding items.

QML Item and Qt Component Developers

If you are developing custom QML items (such as Qt Components) it will probably be helpful to have a little bit more knowledge about how the accessibility system works. You will get a lot of accessibility functionality for free by using the built-in QML items such as Text and Flickable. If you want or to develop custom components, here's how:

Accessibility Properties

QML Components are made accessible by setting accessibility properties. The property values are enum based, with the enum
values defined in the Qt namespace.

The main property is accessibleRole, where the currently supported values are:

Role	Description	Status
Accessible.Pane	Generic Container	Implemented (default role)
Accessible.StaticText	One-line read-only text label	Implemented ("Text" items)
Accessible.PushButton	A Button	Implemented
Accessible.CheckBox	toggle on/off button	Planned
Accessible.RadioButton	toggle on/off button with exclusivity	Planned
Accessible.ProgressBar	Range Control	Planned
Accessible.Slider	Range Control	Planned
Accessible.ScrollBar	Range Control	Planned
Accessible.SpinBox	Range Control	Planned

Depending on the role, the accessibility system reads other properties to get further details. Here the qt-components properties are re-used as often as possible. Many roles also have associated actions.

Role	Properties	Actions
Accessible.StaticText	text
Accessible.PushButton	text	Qt.Press
Accessible.CheckBox	enabled	Qt.Press
Accessible.RadioButton	enabled	Qt.Press
Accessible.ProgressBar	value, minimumValue, maximumValue	Qt.Increase, Qt.Decrease

Actions are delivered through the accessibleAction function:

function accessibleAction(action) { }

(See tests/manual/accessibility/textandbuttons.qml for example)

Notes:
* Child components: "Pane" items are allowed (and expected to) have child items, but many others are not. If you create a child item of a PushButton it will not be visible to the accessibility system.

Accessibility Platform Backend Developers

For those that are implementing a Qt accessibility platform backend. This section will document how the QML QAccessibleInterfaces and related APIs behaves.

Use of the QAccessible API general notes

• We are zeroing in on a subset of the API that makes sense for QML accessibility
• The "self-contained" child functionality of QAccessibleInterface is not used. (When using navigate with Child you always get a real QAccessibleInterface for potential children, not the item itself with an integer denominating the child id, so you will always pass 0 as child into functions such as QAssessibleInterface::Text(TextType, 0))

Events:

The QML accessibility implementation sends updates when there are changes on the scene. The following events are used:

Name	Description	Status
LocationChanged	Item position changed
ObjectCreated	A new item has been created
ObjectDestroyed	An item is about to be destroyed
ScrollingStart	Animation has stared
ScrollingEnd	Animation has ended
FocusChanged	Focus changed

Each event is accompanied with a QObject pointer corresponding to the item. Several things are done to limit the number of events:
* LocationChanged are not propagated to child items. Generate them in the backend if the platform accessibility requires them.
* LocationChanged events are held back during animations (beween ScrollingStart and ScrollingEnd). One locationChanged is sent at animation end.

Future

Potential changes to improve the accessibility framework: Qt Accessibility Future Improvements