Accessibility Code

This page is a torso and is likely to be enhanced.

The following page contains a brief guideline to improve the behaviour of the application in terms of accessibility.

The accessibility output is tested using NVDA on Windows.

See the following documents:

• Making Qt Applications Accessible
• Qt Designer's Tab Order

On Windows make sure to follow this description to set the envoronment properly.

Accessibility

View Models

The models data() method should implement the Qt::AccessibleTextRole on which a suitable QString containing the cell content description must be returned. Don't return null or empty strings or variants as then the used screen reader (NVDA) tends to generate a generic cell description.

The usage of Qt::AccessibleDescriptionRole is not encouraged at the moment. Data returned in this role are appended pas data obtained via Qt::AccessibleTextRole and can create confusion.

Edit Lines

All text edit lines should have a tool-tip string set as this is used by the screen reader.

Displayed Icons

All icons should be provided in multiple sizes for each action or control element. Qt should be able to choose the most appropriate size.

The Form Editor of the Qt Creator does not provide means how to assign multiple icon sizes for each defined action or control element. Different icon sizes must thus be set from C++ code.

Currently we don't recommend the direct usage of SVG icons/pictures directly in the application (e.g. they look blurry on macOS). When rescaling then the Qt SVG renderer causes artefacts to occur on edges. The recommended approach would be to generate PNG icons in desired sizes and use those images instead of the SVG originals. Currently we use square-shaped icons with the edge length of 16, 24 and 32 pixels.

When converting SVG to PNG don't use ImageMagick. The described procedure creates blurry unusable images. You may use Inkscape to generate PNG files of desired resolution, e.g.:

inkscape -z -e readcol.png -w 32 -h 32 readcol.svg

Window and Dialogue Size

Dialogue sizes should be derived from the size of the used font. The actual mechanism how to accomplish this is not yet tested.

Proper dialogue size should prevent collapsing of held control elements. E.g. too small dialogues cause edit lines to collapse or not to be shown at all.

Keyboard Navigation

All control elements should be navigable by using keyboard only. Forget about the mouse cursor for the moment. The selection sequence should follow a reasonable order.

Normally, the tab order is specified by the order of creation of the control elements. While it may be fine for small forms it becomes confusing for large forms or forms with more complicated functionality.

Qt creator provides when editing form files the 'Edit Tab Order' functionality. Here you can select the tab order of the common control elements. this may, however, not be sufficient, because some elements do not provide Qt::StrongFocus or Qt::TabFocus policy by default.

For more complicated forms such as when enabling focus on elements in a tool bar you have to call QWidget::setTabOrder() and setFocusPolicy() for each affected widget from a suitable place in the C++ code.

Table views and widgets by default tend to cycle between all cells when Tab is pressed. Install TableTabIgnoreFilter to such elements to prohibit such behaviour.