Skip to content

README-APPLICATION-DEVELOPERS.md

Latest commit

 

History

History
125 lines (90 loc) · 5.89 KB

README-APPLICATION-DEVELOPERS.md

File metadata and controls

125 lines (90 loc) · 5.89 KB

Tips for application developers

Introduction

Please note: This document is a work in progress and will be expanded over time to include details about how to make accessible applications using AccessKit.

Other Resources

Many accessible technologies have their own tips for application developers. See:

Using screen readers

The best way to test applications for accessibility is with a screen reader. Here are some key commands to know:

macOS

  • Turn VoiceOver on or off with Command + F5 (Some Macs require Command + Function + F5. If your Mac or Magic Keyboard has Touch ID, press and hold the Command key while you quickly press Touch ID three times.)
  • Move the VoiceOver cursor with Control + Option + Arrow keys, or by clicking with the mouse.
  • Perform the default action with Control + Option + Space.
  • Access a menu with Control + Option + H + H (pressing the H key twice). This provides a menu of all commands including developer ones.
  • More commands here.

Linux

orca can be enabled from the settings screen in many desktop environments, as well as by running orca on the command line. orca --setup will open a configuration pane, and orca --debug-file=file.log will log debug information to a file which can be useful for debugging applications.

orca's keyboard configurations come in two flavors, the 'Desktop' (default) and 'Laptop' configurations. This document discusses the Desktop flavor.

  • 'Where am I?' is Keypad Enter (press twice for more info)
  • Move focus with Insert + Ctrl + Arrow key
  • Speak current item with Insert + Shift + Up Arrow
  • Present object actions with Insert-Shift-a
  • Speak entire window with Flat Review with Keypad Add + Keypad Add (pressing the plus key twice)
  • To get a menu of all shortcuts on your system, use Insert + H to enter learn mode, and then F2.
  • More information about Orca is available here.

Problems with orca can sometimes be resolved by removing user settings at ~/.local/share/orca and relaunching orca.

Using accessibility inspectors

Accessibility inspectors provide a convenient way to inspect your accessibility tree. However, they can be very misleading in terms of how screen reader users experience an application.

macOS

on macOS you can use the Accessibility Inspector, which is part of Xcode. See the documentation at Apple's developer site.

Accessibilty Inspector provides GUI buttons for navigation through the application and visually displays properties. It includes some auditing tools to look for common issues in your application.

The macOS tooling is of reasonably high quality for common tasks but does not always surface issues that are important for screen reader users.

Linux

The GNOME project provides the accerciser inspector. It provides a basic tree view of the accessibility tree and can be used to inspect properties of nodes and run some simple audits.

accerciser has many limitations. It often fails to show node properties in complex trees and cannot display the tree for the orca setup window for example. It often hangs and crashes on complex trees, it does not provide a facility to focus or navigate nodes in the tree or send most events to applications. And it will not display trees created by accesskit on its own because it does not enable the ATSPI bus. (To do this, turn on a screenreader or run this command: busctl --user set-property org.a11y.Bus /org/a11y/bus org.a11y.Status IsEnabled b true

The KDE project provides the Accessibility Inspector application. In general it is superior to accerciser, it can display the tree for orca's setup window, it provides a checkbox to enable the ATSPI bus, and it supports focusing and navigating nodes in the tree to some extent. However it still frequently crashes and hangs and provides no audit functionality.

Both inspectors often display information that is totally inaccessible to screen reader users and so relying on them to test accessibility can be misleading.

About virtualization

Many developers use virtualization to test their software on other platforms. However, using virtualization to test accessibility has some unique challenges.

Sound

Linux often has choppy audio under virtualization due to its small audio buffers, and this may make it difficult to hear if a screen reader is reading or to understand its speech. Placing the following in ~/.config/wireplumber/wireplumber.conf.d/50-alsa-config.conf can help:

monitor.alsa.rules = [
  {
    matches = [
      # This matches the value of the 'node.name' property of the node.
      {
        node.name = "~alsa_output.*"
      }
    ]
    actions = {
      # Apply all the desired node specific settings here.
      update-props = {
        api.alsa.period-size   = 1024
        api.alsa.headroom      = 8192
      }
    }
  }
]

Input

Popular virtualization software interferes with the keyboard shortcuts used with screen readers. This can cause screen readers to seemingly not respond, or respond incorrectly or inconsistently to keyboard commands.

One workaround is to mount a keyboard for the exclusive use of the guest. (A full-size keyboard is recommended since screen readers use many keys.) This feature is disabled by default in VMWare; to enable it, append the following to the vmx file:

usb.generic.allowHID = "TRUE"
usb.generic.allowLastHID = "TRUE"