
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.

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:
