Qt Accessibility

From Qt Wiki
Jump to navigation Jump to search

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.)


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)


  • 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))


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.


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