Qt Accessibility: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(removed from needless category)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Developing_with_Qt::Qt Quick]]<br />[[Category:Developing Qt::Qt Quick]]<br />[[Category:HowTo]]<br />[toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;]
 
 
[[Category:Developing_with_Qt::Qt Quick]]
[[Category:HowTo]]
 


= Accessibility for Qt Quick =
= Accessibility for Qt Quick =
Line 11: Line 15:
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.
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 />|What|Where|Branch|Notes|<br />|Qt (scene graph)|http://qt.gitorious.org/+qt-developers/qt/staging|qml-team/qtquick2-accessibility|Outdated, will move to a branch in Qt5 soon|<br />|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|<br />|Components (desktop)|http://qt.gitorious.org/qt-components/desktop|scenegraph-accessibility||
Source Code:
 
{| class="wikitable"
!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 ==
== QML and Qt Component Users ==
Line 19: 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 &quot;self-contained&amp;quot; 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 &quot;visible&amp;quot; property to false when hiding items.
* Set the "visible" property to false when hiding items.


== QML Item and Qt Component Developers ==
== QML Item and Qt Component Developers ==
Line 29: Line 55:
=== Accessibility Properties ===
=== Accessibility Properties ===


QML 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="wikitable"
|'''Role'''
|'''Role'''
|'''Description'''
|'''Description'''
Line 44: Line 71:
|Accessible.StaticText
|Accessible.StaticText
|One-line read-only text label
|One-line read-only text label
|Implemented (&quot;Text&amp;quot; items)
|Implemented ("Text" items)
|-
|-
|Accessible.PushButton
|Accessible.PushButton
Line 77: Line 104:
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="wikitable"
|'''Role'''
|'''Role'''
|'''Properties'''
|'''Properties'''
Line 105: Line 132:
Actions are delivered through the ''accessibleAction'' function:
Actions are delivered through the ''accessibleAction'' function:


<code>function accessibleAction(action) { }<code>
<code>function accessibleAction(action) { }</code>


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


Notes:<br />* Child components: &quot;Pane&amp;quot; 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.
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 ==
== Accessibility Platform Backend Developers ==
Line 118: Line 146:


* We are zeroing in on a subset of the API that makes sense for QML accessibility
* We are zeroing in on a subset of the API that makes sense for QML accessibility
* The &quot;self-contained&amp;quot; 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: ===
Line 124: Line 152:
The QML 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="wikitable"
|'''Name'''
! Name
|'''Description'''
!Description
|'''Status'''
!Status
|-
|-
|LocationChanged
|LocationChanged
Line 154: Line 182:
|}
|}


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


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

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

Retrieved from "https://wiki.qt.io/index.php?title=Qt_Accessibility&oldid=17227"