# Accessibility

Accessibility is important for a lot of users, without it they just can not use their computer.

<a href="http://www.insee.fr/fr/themes/document.asp?ref_id=ip1254#sommaire">“15% of the world's population lives with some form of disability”</a>

<a href="https://wiki.gnome.org/Accessibility/Laws">Laws require accessibility.</a>

## About this page

Accessibility documentation is scattered on different projet documentation, blog posts, etc. it's hard to find your way when you start from scratch. This wiki page, hosted by freedesktop for stability, collects links and documentation, to act as a central place for documentation.

If something is missing on these pages, don't hesitate to mail samuel.thibault@ens-lyon.org ; or better : [[get a freedesktop wiki account by mailing wiki-requests|https://wiki.freedesktop.org/sitewranglers/wiki/401/]] to do additions yourself. You can send the "Generation" part result to Samuel Thibault for him to create your account.

## Principles

A few important principles are to be kept in mind

* We want to make existing software accessible, and avoid dedicated software, both to avoid having to maintain them, and to make accessibility mainstream so that users don't get ghettoed
* We need synchronization: accessibility is just another way for input and output
* It should be easily available, ready to be enabled.

See also <a href="http://sonify.psych.gatech.edu/~walkerb/classes/assisttech/pdf/Mynatt(1994).pdf">Nonvisual Presentation of Graphical User Interfaces: Contrasting Two Approaches</a> which discusses a lot of ground design principles.

***

## TODO-list for Wayland

This is collected on [[Accessibility/Wayland/]]

***

## Revamping GTK accessibility stack?

This is collected on [[Accessibility/GTK-a11y-revamp/]]

It is maintained on the gnome gitlab pages: [[https://gnome.pages.gitlab.gnome.org/at-spi2-core/devel-docs/index.html]]

***

## Input

Accessibility support is needed in [[Accessibility/Input/]]

***

## Output

Accessibility support is needed in [[Accessibility/Output/]]

***

## Toolkits

Accessibility support is needed in applications, through [[Accessibility/AT-SPI2/]]

[[!img at-spi.png align="center" alt="at-spi stack overview"]]
([[source|Accessibility/at-spi.fig]]) ([[description|Accessibility/at-spi]])  

The reason why ATK and atk-bridge are separate is because previously the at-spi stack could be running either on top of dbus or corba. There used to be an atk-adaptor for CORBA, while the current atk-bridge is only for dbus.

Toolkits can either implement the at-spi dbus protocol themselves (as is done by qt5), or use Atk to do the at-spi marshalling for them. 

In such a case, a tree of objects with base class AtkObject can either

* be built along the toolkit widget tree (as is done externally and even lazily by java-atk-wrapper),
* or within the toolkit widget tree itself: for instance gtk's base GtkWindow object contains an AtkObject *accessible field, subclass initialization functions specify with gtk_widget_class_set_accessible_type which precise accessible type should be used, and gtk will eventually create the right AtkObject subclass in gtk_widget_real_get_accessible. For instance, GtkLabel's gtk_label_class_init calls gtk_widget_class_set_accessible_type (widget_class, GTK_TYPE_LABEL_ACCESSIBLE); to specify that it will use the GtkLabelAccessible class to implement accessibility.

In both case, atk glib interfaces (AtkComponent, AtkText, AtkSelection, etc.) are added to the AtkObject subclasses, to specify which at-spi interfaces are implemented. See for instance GtkAccessibleLabel's G_DEFINE_TYPE_WITH_CODE call.

A [[Accessibility/Walkthrough/]] documents the RPC and function calls details.

[[Accessibility/MakingWidgetAccessible]] documents a brief summary how to add accessibility support

* GTK2/GTK3: good support, through [[atk|https://gitlab.gnome.org/GNOME/at-spi2-core/-/tree/main/atk]] ([[documentation|https://gnome.pages.gitlab.gnome.org/at-spi2-core/atk/]]), and [[atk-bridge|https://gitlab.gnome.org/GNOME/at-spi2-core/-/tree/main/atk-adaptor]].
* GTK4: drops the use of atk, to directly talk at-spi, see [[Accessibility/Gtk4atspi]] for an instance, or the [[GTK4 documentation on accessibility|https://docs.gtk.org/gtk4/section-accessibility.html]].
* Qt5: improving, [[integrated in Qt5|http://doc.qt.io/qt-5/accessible.html]]
* Qt4: only preliminary support, through [[qt-at-spi|https://community.kde.org/Accessibility/qt-atspi]]
* wxWidgets: gtk-based widgets inherit gtk accessibility, wxWidgets-specific widgets have accessibility support on Windows, but missing a bridge on Linux, see [[https://www.wxwidgets.org/docs/tutorials/accessibility/]]
* Java: Basics, through [[java-atk-wrapper|https://wiki.gnome.org/Accessibility/JavaAtkWrapper]]
* Python Tkinter: Unmaintained [[https://pypi.org/project/Tka11y/]]
* WebKitGTK+: [[https://mariospr.org/2013/02/03/accessibility-in-webkitgtk/]]
* [[https://github.com/AccessKit/accesskit]]

A [[glimpse into atspi using python|https://en.trycht.cz/2023/12/15/down-and-down-exploring-the-implementation-of-the-accessibility-subsystem/]] is available.

When an application is composed of several processes (e.g. applets, separate web rendering, etc.), one can use AtkPlug and AtkSocket to make the applet accessibility tree magically appear in the accessibility tree of the application. See an instance on [[https://github.com/mariospr/atksocket-atkplug-example]]

Gnome provides an [[Accessibility development guide|https://developer.gnome.org/documentation/guidelines/accessibility.html]] and its [[Accessibility wiki|https://wiki.gnome.org/Accessibility]]

For ATK, there is [[a best ATK practices guide|https://wiki.gnome.org/Accessibility/ATK/BestPractices]] , and a minimal example of extending a base atk implementation is the GtkScaleAccessible class, based on GtkRangeAccessible, see gtk/gtk/a11y/gtkscaleaccessible.[ch]

For adding accessibility support to a custom-made widget, the [[evince implementation|https://gitlab.gnome.org/GNOME/evince/-/blob/main/libview/ev-view-accessible.c#n71]] can be used as an example.

For Qt5, there is [[a guide for QWidget|http://doc.qt.io/qt-5/accessible-qwidget.html]] and [[a guide for Qt Quick|http://doc.qt.io/qt-5/accessible-qtquick.html]]

KDE provides an [[Accessibility development guide in the Human Interface Guidelines|https://hig.kde.org/accessibility/index.html]] , a [[Plasma Accessibility documentation|https://userbase.kde.org/Accessibility/Plasma]]

[[Plans for wayland|https://wiki.gnome.org/Projects/GTK%2B/Accessibility]]

To check the content exposed by application, use [[accerciser|https://wiki.gnome.org/Apps/Accerciser]]

LinuxJournal proposes a [[HOW-TO|https://www.linuxjournal.com/magazine/make-your-application-accessible-accerciser]]

## Screen reader side

For the screen reader side, one can read the [[libatspi documentation|https://www.manpagez.com/html/libatspi/]] or the pyatspi2 documentation available with `pydoc3 pyatspi`, there is also a [[small pyatspi2 example available|https://www.freedesktop.org/wiki/Accessibility/PyAtSpi2Example/]]

The main screen reader used on the desktop is [[Orca|https://wiki.gnome.org/Projects/Orca]], there is also an initial project called [[Odilia|https://odilia.app]]

Screen magnification is provided by gnome-shell or compiz' ezoom plugin.

## Lists

There are so many accessibility mailing lists, notably for each distribution:

* Debian [[https://lists.debian.org/debian-accessibility/]]
* Gentoo [[https://archives.gentoo.org/gentoo-accessibility/]], [[mailto:gentoo-accessibility@gentoo.org]]
* Slint [[https://www.freelists.org/list/slint]]
* Ubuntu [[https://lists.ubuntu.com/mailman/listinfo/ubuntu-accessibility]]

* Accessible Coconut [[https://groups.google.com/forum/#!forum/accessible-coconut]]
* Adriane [[http://www.blindzeln.net/mailman/listinfo/adriane-de]] , [[http://www.blindzeln.net/mailman/listinfo/adriane-de-dev]]
* F123e [[https://groups.io/g/F123e]]
* Perkify [[http://pa.cfcl.com/item?key=Areas/Content/Overviews/Perkify_Intro/main.toml]]
* Raspberry VI [[https://www.freelists.org/list/raspberry-vi]]
* Stormux [[https://groups.io/g/stormux]]
* Vinux [[http://groups.google.com/group/vinux-development]]

and for each toolkit or desktop:

* Gnome [[https://discourse.gnome.org/tag/a11y]]
  * [[Application accessibility|https://discourse.gnome.org/tags/c/applications/7/a11y]]
  * [[Desktop accessibility|https://discourse.gnome.org/tags/c/desktop/6/a11y]]
  * [[Accessibility API|https://discourse.gnome.org/tags/c/platform/5/a11y]]
  * (and formerly [[https://mail.gnome.org/mailman/listinfo/gnome-accessibility-devel]])
* KDE [[https://mail.kde.org/mailman/listinfo/kde-accessibility]]
* MATE [[https://groups.io/g/mate-accessibility]]

and for each screen reader:

* BRLTTY [[http://brltty.com/mailman/listinfo/brltty]]
* emacspeak [[https://www.cs.vassar.edu/~priestdo/emacspeak/]]
* fenrir [[https://www.freelists.org/list/fenrir-screenreader]]
* NVDA [[https://nvda.groups.io/g/nvda]] (for Windows, shares a few components with other screen readers)
* Orca [[https://mail.gnome.org/mailman/listinfo/orca-list]], [[https://discourse.gnome.org/tag/orca]]
* speakup [[http://linux-speakup.org/cgi-bin/mailman/listinfo]]
* speech-dispatcher [[https://lists.nongnu.org/mailman/listinfo/speechd-discuss]]

and cross-software lists:

* blinux [[https://www.redhat.com/mailman/listinfo/blinux-list]]
* Freedesktop [[https://lists.freedesktop.org/mailman/listinfo/accessibility]]
* GNU [[https://lists.gnu.org/mailman/listinfo/accessibility]]
* Pinguin [[http://www.blindzeln.net/mailman/listinfo/pinguin]] (German)
* Carrefourblinux [[http://listengine.tuxfamily.org/lists.tuxfamily.org/carrefourblinux]] (french)
* ALLOS [[http://fr.groups.yahoo.com/group/ALLOS/]] (french)
* April accessibilite [[http://www.april.org/wws/arc/accessibilite]] (french)