Qt Accessibility
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 | qml-team/qtquick2-accessibility | Outdated, will move to a branch in Qt5 soon |
| Qt (fixes for 4.8) | https://qt.gitorious.org/+qt-developers/qt/accessibility | 4.8-a11y | Will not be further developed, here for reference while porting to Qt5 |
| Components (desktop) | http://qt.gitorious.org/qt-components/desktop | scenegraph-accessibility |
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