Qt Accessibility: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(removed from needless category)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Accessibility for Qt Quick=
 
 
[[Category:Developing_with_Qt::Qt Quick]]
[[Category:HowTo]]
 
 
= 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.
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.
Line 5: Line 11:
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.)
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==
== Practical ==


Accessibility support is developed primarily for Qt Quick 2 (<span class="caps">QML</span> on scene graph). There is also some work to make it available for 4.8.
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:<br />
Source Code:


{| class="infotable line"
{| class="wikitable"
| What
!What
| Where
!Where
| Branch
!Branch
| Notes
!Notes
|-
|-
| Qt (scene graph)
|Qt (scene graph)
|
|http://qt.gitorious.org/+qt-developers/qt/staging
http://qt.gitorious.org/+qt-developers/qt/staging
|qml-team/qtquick2-accessibility
| qml-team/qtquick2-accessibility
|Outdated, will move to a branch in Qt5 soon
| Outdated, will move to a branch in Qt5 soon
|-
|-
| Qt (fixes for 4.8)
|Qt (fixes for 4.8)
|
|https://qt.gitorious.org/+qt-developers/qt/accessibility
https://qt.gitorious.org/+qt-developers/qt/accessibility
|4.8-a11y
| 4.8-a11y
|Will not be further developed, here for reference while porting to Qt5
| Will not be further developed, here for reference while porting to Qt5
|-
|-
| Components (desktop)
|Components (desktop)
|
|http://qt.gitorious.org/qt-components/desktop
http://qt.gitorious.org/qt-components/desktop
|scenegraph-accessibility
| scenegraph-accessibility
|
|
|}
|}


==<span class="caps">QML</span> and Qt Component Users==
== QML and Qt Component Users ==


The easiest way to create accessible applications is to use Qt Components, which will have built-in accessibility support.
The easiest way to create accessible applications is to use Qt Components, which will have built-in accessibility support.
Line 42: Line 45:
Some rules to be aware of (based on early implementation experience):
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.
* 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.
* Well-behaved items have correct geometry (height, width) at all times.
* Set the “visible” property to false when hiding items.
* Set the "visible" property to false when hiding items.


==<span class="caps">QML</span> Item and Qt Component Developers==
== QML Item and Qt Component Developers ==


If you are developing custom <span class="caps">QML</span> 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 <span class="caps">QML</span> items such as Text and Flickable. If you want or to develop custom components, here’s how:
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===
=== Accessibility Properties ===


<span class="caps">QML</span> Components are made accessible by setting accessibility properties. The property values are enum based, with the enum<br /> values defined in the Qt namespace.
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:
The main property is ''accessibleRole'', where the currently supported values are:


{| class="infotable line"
{| class="wikitable"
| '''Role'''
|'''Role'''
| '''Description'''
|'''Description'''
| '''Status'''
|'''Status'''
|-
|-
| Accessible.Pane
|Accessible.Pane
| Generic Container
|Generic Container
| Implemented (default role)
|Implemented (default role)
|-
|-
| Accessible.StaticText
|Accessible.StaticText
| One-line read-only text label
|One-line read-only text label
| Implemented (“Text” items)
|Implemented ("Text" items)
|-
|-
| Accessible.PushButton
|Accessible.PushButton
| A Button
|A Button
| Implemented
|Implemented
|-
|-
| Accessible.CheckBox
|Accessible.CheckBox
| toggle on/off button
|toggle on/off button
| Planned
|Planned
|-
|-
| Accessible.RadioButton
|Accessible.RadioButton
| toggle on/off button with exclusivity
|toggle on/off button with exclusivity
| Planned
|Planned
|-
|-
| Accessible.ProgressBar
|Accessible.ProgressBar
| Range Control
|Range Control
| Planned
|Planned
|-
|-
| Accessible.Slider
|Accessible.Slider
| Range Control
|Range Control
| Planned
|Planned
|-
|-
| Accessible.ScrollBar
|Accessible.ScrollBar
| Range Control
|Range Control
| Planned
|Planned
|-
|-
| Accessible.SpinBox
|Accessible.SpinBox
| Range Control
|Range Control
| Planned
|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.
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.


{| class="infotable line"
{| class="wikitable"
| '''Role'''
|'''Role'''
| '''Properties'''
|'''Properties'''
| '''Actions'''
|'''Actions'''
|-
|-
| Accessible.StaticText
|Accessible.StaticText
| text
|text
|
|
|-
|-
| Accessible.PushButton
|Accessible.PushButton
| text
|text
| Qt.Press
|Qt.Press
|-
|-
| Accessible.CheckBox
|Accessible.CheckBox
| enabled
|enabled
| Qt.Press
|Qt.Press
|-
|-
| Accessible.RadioButton
|Accessible.RadioButton
| enabled
|enabled
| Qt.Press
|Qt.Press
|-
|-
| Accessible.ProgressBar
|Accessible.ProgressBar
| value, minimumValue, maximumValue
|value, minimumValue, maximumValue
| Qt.Increase, Qt.Decrease
|Qt.Increase, Qt.Decrease
|}
|}


Actions are delivered through the ''accessibleAction'' function:
Actions are delivered through the ''accessibleAction'' function:
<code>function accessibleAction(action) { }</code>


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


Notes:
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.


* 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 ==
 
==Accessibility Platform Backend Developers==


For those that are implementing a Qt accessibility platform backend. This section will document how the <span class="caps">QML</span> QAccessibleInterfaces and related <span class="caps">API</span>s behaves.
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 <span class="caps">API</span> general notes===
=== Use of the QAccessible API general notes ===


* We are zeroing in on a subset of the <span class="caps">API</span> that makes sense for <span class="caps">QML</span> accessibility
* 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 "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:===
=== Events: ===


The <span class="caps">QML</span> accessibility implementation sends updates when there are changes on the scene. The following events are used:
The QML accessibility implementation sends updates when there are changes on the scene. The following events are used:


{| class="infotable line"
{| class="wikitable"
| '''Name'''
! Name
| '''Description'''
!Description
| '''Status'''
!Status
|-
|-
| LocationChanged
|LocationChanged
| Item position changed
|Item position changed
|
|
|-
|-
| ObjectCreated
|ObjectCreated
| A new item has been created
|A new item has been created
|
|
|-
|-
| ObjectDestroyed
|ObjectDestroyed
| An item is about to be destroyed
|An item is about to be destroyed
|
|
|-
|-
| ScrollingStart
|ScrollingStart
| Animation has stared
|Animation has stared
|
|
|-
|-
| ScrollingEnd
|ScrollingEnd
| Animation has ended
|Animation has ended
|
|
|-
|-
| FocusChanged
|FocusChanged
| Focus changed
|Focus changed
|
|
|}
|}


Each event is accompanied with a QObject pointer corresponding to the item. Several things are done to limit the number of events:
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 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.
* LocationChanged events are held back during animations (beween ScrollingStart and ScrollingEnd). One locationChanged is sent at animation end.


==Future==
== Future ==
 
Potential changes to improve the accessibility framework: [[Qt-Accessibility-Future-Improvements|Qt Accessibility Future Improvements]]
 
===Categories:===


* [[:Category:Developing Qt|Developing_Qt]]
Potential changes to improve the accessibility framework: [[Qt Accessibility Future Improvements]]
** [[:Category:Developing Qt::Qt Quick|Qt_Quick]]
* [[:Category:Developing with Qt|Developing_with_Qt]]
** [[:Category:Developing with Qt::Qt Quick|Qt_Quick]]
* [[:Category:HowTo|HowTo]]

Latest revision as of 23:47, 24 May 2015


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