Accessibility API

The accessibility API enables text selection and editing more powerful than what Dragon provides natively, to a wider range of applications (e.g. Google Chrome on Windows and Mozilla Firefox on Windows and Linux). It is currently in Beta and the API may change at any time.

Windows

To use this API on Windows, install pyia2. To use this with Chrome, you may also need to register an additional 64-bit IAccessible2 DLL which can be obtained here.

Linux

To use this on Linux, you will need to install the Python library pyatspi. You can typically get this from your distribution’s package manager. See this stack overflow question for examples.

Next, add the following to your ~/.profile file:

export GTK_MODULES=gail:atk-bridge
export OOO_FORCE_DESKTOP=gnome
export GNOME_ACCESSIBILITY=1
export QT_ACCESSIBILITY=1
export QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1

Some applications will not support assistive technologies unless these settings are enabled. You may also need to enable GNOME accessibility with gsettings:

gsettings set org.gnome.desktop.interface toolkit-accessibility true

This page has some useful information on testing / troubleshooting accessibility support. The troubleshoot script from check-a11y can find problems with the accessibility stack:

git clone https://git.debian.org/git/pkg-a11y/check-a11y
cd check-a11y
./troubleshoot

Most functionality works properly on Linux, except for a few known issues:

  • Text selection occasionally requires use of the Mouse action due to limitations of the text selection API. The Mouse action is not yet implemented on Linux, so this will sometimes silently fail.
  • Firefox has been tested successfully on Ubuntu 18.04 and Debian 10 with default configuration.
  • LibreOffice treats each paragraph as a separate focusable element, so movement between paragraphs is not yet supported.

Entry points

get_accessibility_controller()[source]

Get the OS-independent accessibility controller which is the gateway to all accessibility functionality. Returns None if OS is not supported.

get_stopping_accessibility_controller(*args, **kwds)[source]

Same as get_accessibility_controller(), but automatically stops when used in a with context.

Controller class

class AccessibilityController(os_controller)[source]

OS-independent controller for accessing accessibility functionality.

is_editable_focused()[source]

True if an editable text field is focused.

move_cursor(text_query, position)[source]

Moves the cursor before or after text that matches the provided query.

replace_text(text_query, replacement)[source]

Replaces text which matches the provided query.

select_text(text_query)[source]

Selects text which matches the provided query.

stop()[source]

Stops the controller (otherwise process exit may be blocked).

TextQuery class

class TextQuery(start_phrase='', start_relative_position=None, start_relative_phrase='', through=False, end_phrase='', end_relative_position=None, end_relative_phrase='')[source]

A query to match a range of text.

end_phrase = None

The phrase at the end of the match (or the sole phrase).

end_relative_phrase = None

The phrase to match before or after at the end.

end_relative_position = None

Whether to match before or after the end_relative_phrase.

start_phrase = None

The phrase at the start of the match.

start_relative_phrase = None

The phrase to match before or after at the start.

start_relative_position = None

Whether to match before or after the start_relative_phrase.

through = None

True if matching from a start point to the end phrase.

CursorPosition class

class CursorPosition[source]

The cursor position relative to a range of text.

AFTER = 2

The position after the text.

BEFORE = 1

The position before the text.