Author: Kevin Walzer
State: Final
Type: Project
Tcl-Version: 9.1
Vote: Done
Created: 2025-09-24
Tk-Branch: tka11y
Vote-Summary: Accepted 7/0/0
Votes-For: MC, AK, SL, AN, JN, HO, KW
Votes-Against: none
Votes-Present: none
Abstract
This TIP proposes to add the tk accessible command, which will enable screen reader support for core Tk and ttk widgets on Windows, X11 and macOS.
Rationale
Accessibility has been a requested feature of Tk for at least 20 years. Screen reader support, which allows visually-impaired users to access a computer program using keyboard navigation and verbalization of the application's graphical interface, is a standard component of modern GUI toolkits. Tk is conspicuous among these toolkits in not supporting accessibility. The design of tk accessible will provide transparent, out-of-the-box accessibility for the core Tk and ttk widgets, with an API for customization of individual widgets or non-core widgets if needed by the developer. Once this is added to Tk, Tk applications will be immediately accessible if a screen reader is activated. The accessibility API will have no impact on Tk if a screen reader is switched off.
Design Notes
The tk accessible implementation includes a core API that is exposed to the script level and which abstracts away the platform-specific API's. The platform-native implementations are as follows:
- X11: The Gnome Accessibility Toolkit (ATK). ATK provides a toolkit-neutral API for implementing accessibility. X11 accessibility has the following build and runtime dependencies: atk, atk-bridge-2.0, dbus-1.0 and glib-2.0. If these are not present when Tk is configured and built, accessibility will not be enabled.
- Windows: Microsoft Active Accessibility (MSAA). MSAA is the original accessibility API for Microsoft.
- MacOS: NSAccessibility. NSAccessibility is the standard accessibility API for maOS.
Both ATK and MSAA are considered legacy API's, and not much new development is occurring with them. However, both are stable, robust, and the best fit for Tk's widgets, which encompass a basic GUI but do not utilize the latest user interface design patterns. Additionally, both API's remain well-supported on X11 and Windows.
Alternative API's were considered on both platforms -- at-spi2 on X11, and UI Automation on Windows. Both are more recent and arguably modern accessibility API's, with active development and support for a richer widget set. Qt supports at-spi2, which is an accessibility API that interfaces directly with dbus. Additionally, Microsoft Narrator, the screen reader bundled with Windows, is based on UI Automation.
However, these APIs are not the best fit for Tk. at-spi2 requries directly managing a dbus connection as well as the accessibility details, and that is more overhead than is desirable; ATK only requries a focus on accessible widgets, and interfaces with dbus over the at-spi2 bridge. And UI Automation, while a richer API, is considerably more complex, and offers no special benefit to Tk that MSAA cannot address. A thin bridge layer to UI Automation driven by MSAA has been included in tka11y, but it is not robust.
Because the accessibility environment on Windows is fragmented, choosing to support MSAA primarily means that not all screen readers are equally well-supported. NVDA is the screen reader that was used for development and testing of the Windows interface, and as NVDA is based primarily on MSAA, it works very well. JAWS, a commercial screen reader also based mainly on MSAA, is also likely to work well. Narrator will not provide as good of an experience because it is primarily based on UIA.
NSAccessibility is the only supported API on macOS and fits well with Tk.
Specification
The core command of tk accessible is:
tk accessible add_acc_object window
This command activates a Tk window as an accessible object, and visible to screen readers.
Additional commands get and set the following accessible attributes:
- role
- name
- description
- value
- state
- action
- help string
Tk provides reasonable default values for most of these traits, but they can be customized by the developer as needed.
Other commands alert the accessibility system to changes in focus or selection, and query the system to determine if a screen reader is running.
All commands are all outlined in detail in the accessible man page.
Internally, accessibility is tightly bound to Tk windows. Certain widget elements, such as listbox rows, are not Tk windows but are made visible to the accessibility system through selection events, custom accessibility notifications, and creation of "virtual" accessible objects, depending on widget and platform.
Some widgets are not made accessible. For instance, the canvas widget is not exposed as an accessible object except by name; here we are following the example of HTML5, which does not support canvas accessibility because the canvas is a purely visual object. Developers may choose to provide alternative data to provide information on the canvas widget, such as labels or help text. Images are also not accessible. Other widgets, such as frames and panedwindows, are not included in the accessibility API because they are just containers and do not handle actions or data.
Menus and dialogs are native on Windows and macOS and thus already support accessibility and are not included here; the X11 menu and dialogs do have a custom accessibility implementation as part of this command.
Testing
Because accessibility is an immersive experience, the best way to test the tk accessible command is to launch the Tk widget demo while a screen reader is running; a subset of the widget demo, which is easily navigable by keyboard, will be presented. It may be necessary to read the screen reader documentation to understand how navigation via keyboard may differ from Tk's standard keyboard shortcuts.
tk accessible was developed with the following screen readers:
Other screen readers are also available, such as JAWS and Microsoft Narrator on Windows, but these three are actively developed and have large user bases.
Reference Implementation
This TIP is implemented in the tka11y branch of the Tk fossil repository.
Copyright
This document has been placed in the public domain.