Difference between revisions of "Development/Tutorials/Accessibility/Checklist"

(Created page with "= Introduction = == Fonts and Colors == There are some general points that I'll rehash without thinking about it too much, these should be known: - The usual HIG apply: make su...")

There are some general points that I'll rehash without thinking about it too

+

Many users have some deficiencies when it comes to seeing. This doesn't always mean that they are blind. For some people it is enough when fonts are clear and the color scheme can be adjusted.

−

much, these should be known:

+

This is something every application should do in any case, so here is the list:

−

- The usual HIG apply: make sure that the application is keyboard accessible

+

* Follow the user interface guidelines! This will get you quite far.

−

(try seeing if the tab key gets you through all widgets in a sensible order)

+

* Check that '''color scheme''' changes apply

−

is quite important.

+

** Try switching to a dark color scheme and see that your application is still usable

−

(Using a mouse is more troublesome when you can't see where you're pointing

+

* Test changing the '''font''' size

−

than moving a focus for example, different kinds of motorical issues etc...)

+

** Switch to different fonts and see that they apply

+

** Increase the font size and make sure that the application layout still works

−

- Check for color scheme compliance and font settings taking effect.

+

== Keyboard ==

+

When you have problems seeing, the mouse is quite hard to use. The keyboard is a lot more reliable. Therefor it is important that applications can be used with the keyboard. For some users, using a mouse is difficult because of motor skill issues.

+

Making applications keyboard accessible benefits everyone, since it allows us to use shortcuts to use the applications more efficiently.

+

+

* Try to operate your application with the TAB key

+

** Make sure that the tab order is correct (or fix it in Qt Designer or the code)

+

* Start your application and do a common task without using the mouse

+

** Note where you had trouble and think about possible improvements in the UI or keyboard shortcuts that are missing

== Screen Reader ==

== Screen Reader ==

−

More advanced would be the usage of assistive technology. I think we need to

−

learn from people with actual need of these technologies in order to get a

−

good grasp of the issues. I can try to write down some issues I know about.

−

1 Get Orca to work in general - just grab the gnome-orca package that should

+

As a sighted person you will probably never fully understand how users use screen readers. You will most likely not become proficient and efficient in their use. Nonetheless there is a lot you can help to make applications accessible to screen reader users. We refer to screen readers and other assistive technology often as AT.

−

be in pretty much any distro and try it with some gtk app. Test that it reacts

2 Make sure it's using dbus. That means having libatspi 2.0 (package name may

+

:Gives detailed setup instructions for screen readers.

−

vary, see also the settings here:

+

−

http://labs.qt.nokia.com/2011/08/23/accessibility-on-linux/)

+

=== Testing ===

−

3 Have Qt 4.8 and the qt-at-spi bridge.

+

This section gives a quick intro what to look for when testing an application with a screen reader.

−

4 export QT_ACCESSIBILITY=1 (this is needed for Qt 4, fixed in Qt 5)

+

−

5 Run the KDE/Qt application you want to test with the Qt version for which

+

−

you have the bridge installed. (This works even with Qt built separately in

+

−

the home directory and the bridge installed there.)

+

Once you have an application running with the screen reader:

Once you have an application running with the screen reader:

Line 38:

Line 40:

bridge still.

bridge still.

−

Apart from the bridge probably still lacking features and having a few bugs, I

+

=== Fixing missing information ===

−

think now it's mostly time to fix up the small missing bits.

+

Once you found a bug it's usually quite easy to fix. This section explains how to go about improving applications.

−

Fixing stuff: the good news is that it's really easy usually, no heavy C++

+

For many things there are usually easy fixes involving no advanced programming skills but just fixing some details.

−

skills required.

+

−

There are two important properties that every QWidget has: AccessibleName and

+

For this tutorial we assume that you are dealing with a QWidget that is seen by the AT but does for example give not enough information.

−

AccessibleDescription.

+

−

The name is a short label, for example the label on a button. It should always

+

There are two important properties that every QWidget has: an "Accessible Name" and an "Accessible Description".

+

The name is short, for example the label on a button. It should always

be short. The description on the other hand is the more verbose "this button

be short. The description on the other hand is the more verbose "this button

−

does foo and then bar".

+

does foo and then bar". Qt will try hard to return something for the name. In case of a button, usually the text on the button is returned. But if your button has text that makes only sense when seeing the arrangement of buttons, or only has an image as label, you need to help the AT read the button.

−

Fire up Qt designer if the app uses .ui files, you'll find the properties and

+

If you don't, it will only say the type of the widget, "Button" is not a very helpful information.

−

can type the name/description right in.

+

−

If the widget is managed in code, just find the right place and set them:

+

==== Fixing Accessible Name and Description ====

−

button->setAccessibleName(i18n("Open"));

+

Fire up Qt designer if the app uses .ui files. You'll find the properties and

−

button->setAccessibleDescription(i18n("Opens a file dialog to select a new

+

can type the name/description right in. After saving the file, rebuild and install the application. You are done, submit a patch to fix the ui file.

−

foo"));

+

+

If the widget is created in the code, just need to find where.

+

Once you found the widget, usually where it's created, add some code to it:

+

button->setAccessibleName(i18n("Open"));

+

button->setAccessibleDescription(i18n("Opens a file dialog to select a new foo"));

+

Send your patch.

+

+

Sometimes you also want to override the label for a different reason. One of my test apps was the calculator example from Qt. It has a memory recall button labelled "MR". Orca will insist on this being the "Mister" button, unless told otherwise.

−

Sometimes you also want to override the label for a different reason. One of my

+

==== Complex Widgets ====

−

test apps was the calculator example from Qt. It has a memory recall button

+

For some widgets the above is not enough. You will have to create QAccessibleInterfaces for widgets that you create yourself.

−

labelled "MR". Orca will insist on this being the "Mister" button, unless told

+

For example Kate has an interface for its text editing area.

−

otherwise. Of course I couldn't fix that one since it made me smile every

+

Sometimes you need to inherit QAccessibleTextInterface or QAccessibleValueInterface in order to make the widgets properly accessible.

−

single time ;)

+

Refer to the Qt documentation how to do this.

−

I bet there's more, but this is a beginning. In the end it would be great to

+

==== QGraphicsView ====

−

build up a bit of a community that starts using these applications on a

+

Currently there is no support for accessibility in QGraphicsView.

−

regular basis.

+

−

Should we gather these and extend them on some wiki? I'd love to have some

+

==== Qt Quick (QML) ====

−

accessibility testing going on some time in the future.

+

For Qt Quick with Qt 4.x there is no solution for accessibility.

+

For Qt 5, refer to the documentation on how to create accessible QML applications. The concepts are generally the same as for QWidget based applications.

Introduction

Fonts and Colors

Many users have some deficiencies when it comes to seeing. This doesn't always mean that they are blind. For some people it is enough when fonts are clear and the color scheme can be adjusted.
This is something every application should do in any case, so here is the list:

Follow the user interface guidelines! This will get you quite far.

Check that color scheme changes apply

Try switching to a dark color scheme and see that your application is still usable

Test changing the font size

Switch to different fonts and see that they apply

Increase the font size and make sure that the application layout still works

Keyboard

When you have problems seeing, the mouse is quite hard to use. The keyboard is a lot more reliable. Therefor it is important that applications can be used with the keyboard. For some users, using a mouse is difficult because of motor skill issues.
Making applications keyboard accessible benefits everyone, since it allows us to use shortcuts to use the applications more efficiently.

Try to operate your application with the TAB key

Make sure that the tab order is correct (or fix it in Qt Designer or the code)

Start your application and do a common task without using the mouse

Note where you had trouble and think about possible improvements in the UI or keyboard shortcuts that are missing

Screen Reader

As a sighted person you will probably never fully understand how users use screen readers. You will most likely not become proficient and efficient in their use. Nonetheless there is a lot you can help to make applications accessible to screen reader users. We refer to screen readers and other assistive technology often as AT.

Testing

This section gives a quick intro what to look for when testing an application with a screen reader.

Once you have an application running with the screen reader:
Make sure Orca says something intelligible for all elements. When it reads a
gui element it should say the label and type, eg: "File, Menu" or "OK,
Button".
When you have a button that does not have a label, maybe because it shows a
picture only, that's something to fix. Try navigating the more troublesome
elements - comboboxes and lists and such. Trees need a bit of love in the
bridge still.

Fixing missing information

Once you found a bug it's usually quite easy to fix. This section explains how to go about improving applications.

For many things there are usually easy fixes involving no advanced programming skills but just fixing some details.

For this tutorial we assume that you are dealing with a QWidget that is seen by the AT but does for example give not enough information.

There are two important properties that every QWidget has: an "Accessible Name" and an "Accessible Description".
The name is short, for example the label on a button. It should always
be short. The description on the other hand is the more verbose "this button
does foo and then bar". Qt will try hard to return something for the name. In case of a button, usually the text on the button is returned. But if your button has text that makes only sense when seeing the arrangement of buttons, or only has an image as label, you need to help the AT read the button.
If you don't, it will only say the type of the widget, "Button" is not a very helpful information.

Fixing Accessible Name and Description

Fire up Qt designer if the app uses .ui files. You'll find the properties and
can type the name/description right in. After saving the file, rebuild and install the application. You are done, submit a patch to fix the ui file.

If the widget is created in the code, just need to find where.
Once you found the widget, usually where it's created, add some code to it:

button->setAccessibleName(i18n("Open"));
button->setAccessibleDescription(i18n("Opens a file dialog to select a new foo"));

Send your patch.

Sometimes you also want to override the label for a different reason. One of my test apps was the calculator example from Qt. It has a memory recall button labelled "MR". Orca will insist on this being the "Mister" button, unless told otherwise.

Complex Widgets

For some widgets the above is not enough. You will have to create QAccessibleInterfaces for widgets that you create yourself.
For example Kate has an interface for its text editing area.
Sometimes you need to inherit QAccessibleTextInterface or QAccessibleValueInterface in order to make the widgets properly accessible.
Refer to the Qt documentation how to do this.

QGraphicsView

Currently there is no support for accessibility in QGraphicsView.

Qt Quick (QML)

For Qt Quick with Qt 4.x there is no solution for accessibility.
For Qt 5, refer to the documentation on how to create accessible QML applications. The concepts are generally the same as for QWidget based applications.