.. _RefAccessibility:

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 X11). It is currently
in Beta and the API may change at any time.

The base requirements for the API may be installed by running the following
command::

  pip install 'dragonfly[accessibility]'

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>`__.

X11 (Linux)
----------------------------------------------------------------------------

To use this on X11, 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 X11, except for a few known issues:

* Text selection occasionally requires use of the Mouse action due to
  limitations of the text selection API.

* 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: