
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
<https://github.com/illinois-dres-aitg/pyia2>`__. To use this with Chrome,
you may also need to register an additional 64-bit IAccessible2 DLL which
can be obtained `here
<https://github.com/ThePacielloGroup/aviewer/blob/Develop/package/IAccessible2Proxy64bit.dll>`__.

Linux
----------------------------------------------------------------------------

To use this on Linux, you will need to install the Python library
`pyatspi <https://github.com/GNOME/pyatspi2>`__.
You can typically get this from your distribution's package manager. See
this `stack overflow question
<https://stackoverflow.com/questions/40799953/how-to-install-pyatspi>`__ 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 <https://www.freedesktop.org/wiki/Accessibility/AT-SPI2/>`__ has
some useful information on testing / troubleshooting accessibility support.
The ``troubleshoot`` script from
`check-a11y <https://git.debian.org/git/pkg-a11y/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
----------------------------------------------------------------------------
.. automodule:: dragonfly.accessibility
   :members:

Controller class
----------------------------------------------------------------------------
.. autoclass:: dragonfly.accessibility.controller.AccessibilityController
   :members:

TextQuery class
----------------------------------------------------------------------------
.. autoclass:: dragonfly.accessibility.utils.TextQuery
   :members:

CursorPosition class
----------------------------------------------------------------------------
.. autoclass:: dragonfly.accessibility.utils.CursorPosition
   :members:
