Tk Source Code

View Ticket
Login
Ticket UUID: 48b39019bd5535ab262dd409146fef4d8cbf6357
Title: X11 accessibility: Tk speaks typed keys and state changes itself, synchronously, on top of the screen reader
Type: Bug Version: 9.1
Submitter: anonymous Created on: 2026-10-03 17:37:28
Subsystem: (unused) Assigned To: kevin_walzer
Priority: 5 Medium Severity: Minor
Status: Closed Last Modified: 2026-10-11 01:31:10
Resolution: Fixed Closed By: kevin_walzer
    Closed on: 2026-10-11 01:31:10
Description:
On X11, when a screen reader is running, library/accessibility.tcl calls
::tk::accessible::speak, which runs "exec spd-say $text" (falling back to
"exec espeak $text") synchronously from the event loop:

- for every printable key typed into an entry or text widget
  (_handle_keypress),
- for the word before each space (_get_prev_word),
- "entry blank" when an empty entry gets the focus,
- the state of a checkbutton, radiobutton or toggleswitch when it changes,
- a listbox selection, and the current notebook tab.

Each call first runs ::tk::accessible::check_screenreader, which on X11 is
popen("pgrep -x orca").

To see exactly what Tk sends, we ran "repro.tcl -tour" on stock 9.1.0 with
stand-ins for spd-say and espeak that only log their arguments and take
0.5 s:

    focus .f.name took 536 ms
    typing 2 keys took 1070 ms
    toggling took 539 ms
    sent to spd-say: "General", "Advanced", "entry blank", "a", "b",
                     "Enable selected"

Two problems:

1. Duplicate speech. Orca already echoes typed characters by default (its
   own log shows every key), and it announces focus changes. Tk's spd-say
   calls are a second speech-dispatcher client, so the user hears the same
   thing twice, from two clients that can overlap.

2. The event loop blocks. exec waits for spd-say to exit, so each key,
   word and state change holds the application for as long as spd-say
   runs. With the real spd-say in our test sessions, the first call in an
   entry stalled the application for more than three seconds. Every call
   also forks a shell and pgrep first.

Suggestion: on X11, drop the automatic speak calls for typed keys, words,
focus and state, which the ATK events already carry to the reader. Keep
::tk::accessible::speak as an explicit command for application
announcements (ATK has no announcement API), run it in the background
("exec ... &"), and check for the reader once rather than on every call.
User Comments: kevin_walzer added on 2026-10-11 01:31:10:
Merging fixes to trunk.

kevin_walzer added on 2026-10-07 09:46:51:
Since this appears to work correctly in the various scenarios you tested, I will merge this to trunk in its present form soon. Thank you for testing.

serhiy.storchaka added on 2026-10-07 04:52:05:

Thanks. I tested [30d3e9a7b7] on Linux in six configurations: without options, with --enable-accessibility and with --disable-accessibility, each with or without ATK or libspeechd. All of them configure and build, and wish starts. When ATK and libspeechd are found, Tk is linked with both; otherwise accessibility is disabled with a warning.

But --enable-accessibility given explicitly also falls back with a warning instead of failing. It could default to "auto", and fail only for an explicit "yes":

  [enable_accessibility=$enableval], [enable_accessibility=auto])
  ...
  if test "$enable_accessibility" = "yes"; then
    AC_MSG_ERROR([ATK and/or Atk-bridge were not found.])
  fi

Also, "checking whether to enable accessibility support... yes" is printed even when it is disabled later.


kevin_walzer added on 2026-10-07 00:46:24:
I have updated configure.ac with these changes. Please test the build. If it works for you, I plan to merge this branch to trunk.

serhiy.storchaka added on 2026-10-06 11:10:08:

That is fine with me: an error if --enable-accessibility is explicitly specified and ATK or libspeechd is not found, and falling back to --disable-accessibility if it is not specified and they are not found. This solves the build failure, and the attached patch is then not needed.


kevin_walzer added on 2026-10-06 10:38:02:
Solution:  libspeechd will be an entire requirement at build time for —enable-accessibility to work, and will fall back to —disable-accessibility if not found.

kevin_walzer added on 2026-10-06 10:32:46:
The more fundamental point is that Unix users are accustomed to installing a complex chain of dependencies, their ports/packaging systems will help, and the entire accessibility stack needs to be installed for accessibility to work correctly. I am unwilling to make libspeechd optional. How do we address this? I am inclined to go back to making it all a hard dependency again, but I am open to suggestions.

kevin_walzer added on 2026-10-06 10:21:47:
But Tk’s own speech is a significant part of the design. It is not an optional feature. Why is silent failure of this feature at runtime preferable to noisy failure at build time, with a message to install the required components?

serhiy.storchaka added on 2026-10-06 10:13:30:

ATK comes with GTK, so it is installed almost everywhere. The libspeechd development files are usually not, unless installed on purpose. Without libspeechd, accessibility still works: Orca gets roles, names, states and focus through AT-SPI and speaks them itself. Only Tk's own announcements are lost. A missing optional library should not make the build fail. If that is a concern, configure can report that speech is disabled.


kevin_walzer added on 2026-10-06 10:07:17:
What systems would have ATK installed and not libspeechd? Without speech, the screen reader experience is seriously degraded, and Tk would erroneously report that accessibility was enabled, leading to all kinds of bug reports. What is the use case for this patch?

serhiy.storchaka added on 2026-10-06 07:27:36:

Thanks, configure works now. But if ATK is found and libspeechd is not, the build fails: tkUnixAccessibility.c includes libspeechd.h and calls spd_*() without checking HAVE_SPEECHD. The attached patch adds the missing #ifdef HAVE_SPEECHD; without it Tk just does not speak. With it, the branch builds with ATK and without libspeechd on Linux, FreeBSD, NetBSD, OpenBSD and DragonFly, and still builds with libspeechd.


kevin_walzer added on 2026-10-06 01:51:33:
I have made accessibility a configure switch via --enable-accessibility, which will be the default. Please review.

serhiy.storchaka added on 2026-10-05 15:13:13:

Bidi can be disabled, and since [1dfc71ae4a] it is disabled if not detected. I think the same should be for ATK and libspeechd.


kevin_walzer added on 2026-10-05 14:32:59:
Bidi must be explicitly disabled - it is the default. I am willing to do the same with Atk and libspeechd. Would that work?

serhiy.storchaka added on 2026-10-05 14:10:24:

Most of Tk's dependencies are optional, including Xft and bidi. Accessibility is important, but not critical: Tk was without it for decades. I am afraid that making it required will harm portability and slow down adoption of Tk 9.1.


kevin_walzer added on 2026-10-05 12:33:50:
Accessibility is critical and has been omitted from Tk for too long. We wouldn’t make Xlib an optional dependency. Why should accessibility be optional?

serhiy.storchaka added on 2026-10-05 12:28:20:

In alt_x11_accessibility_fixes, configure on X11 now stops with an error if the development files of ATK/Atk-bridge or of Speech Dispatcher are not installed. Both were optional before. This breaks building Tk on FreeBSD, NetBSD, OpenBSD and DragonFly, where they are not installed by default (configure stops at the ATK check). Please keep both optional: build without accessibility if ATK is not found, and without libspeechd if it is not found (or load it at run time with dlopen()).


kevin_walzer added on 2026-10-05 00:55:35:
The update committed to the alt_x11_accessibility_fixes branch replaces the shelling out to spd-say with directing invocation through libspeechd, which runs in the same process and should improve performance. This will also mean that the call to [tk accessible check_screenreader] only runs on Tk startup, as it is designed to do.

kevin_walzer added on 2026-10-04 14:35:17:
Implementing a full text interface was considered but rejected. The accessibility API is tightly connected to the Tk_Window design, and non-window data like the text widget contents or listbox rows adds too much complexity at the C level because there is no natural mapping. Using Tk’s normal event process to dispatch this data to custom announcements is cleaner. Perhaps we can look at moving these calls to libspeechd to reduce the overhead.

0xjnml added on 2026-10-04 14:13:05:
Orca has two kinds of echo, both on its Echo preferences page:

- Key echo ("Enable key echo", on by default) speaks each key as it is
  pressed. Orca gets the key events from AT-SPI itself, not from the
  widget, so it works in Tk windows as in any other. In our session with
  Orca 48.1 and its default settings, it said "tab" on every Tab press in a
  Tk 9.1.0 window, before announcing the newly focused control.

- Echo by character, word and sentence speaks the text that was inserted,
  and reading the current line, word or character while moving the cursor
  works the same way. For these Orca asks the focused widget for its text,
  through the AT-SPI text interface and the text-changed events. That is
  where Tk falls short: in unix/tkUnixAccessibility.c, tk_text_get_text
  returns NULL, tk_text_get_caret_offset -1 and
  tk_text_get_character_count 0, and the other AtkText functions are not
  set. The text-changed events Tk emits carry no text either
  (EmitSelectionChanged sends "text-changed::insert" with offset 0 and
  length 0). For a ttk::entry containing "hello world", an AT-SPI client
  reads an empty text.

A terminal, or a GTK entry or text view, implements the text interface, so
there character and word echo work, and the cursor keys read text. That is
probably the difference you saw: with key echo off and echo by character
on, Orca would say nothing while you type into a Tk widget.

So ATK does not need an announcement API for this. The usual way is the text
interface: if Tk's entry and text widgets implemented AtkText (get_text from
the widget's contents, get_character_count, get_caret_offset from the insert
mark, and the text-changed::insert / text-changed::delete events with
offset, length and the text, plus text-caret-moved), Orca would echo
characters and words and read lines and words under the cursor itself, as it
does for GTK. The spd-say calls for typed keys, words and entry contents
could then go.

Until then, the spd-say fallback is the only way the reader hears entry and
text contents, and listbox, treeview, notebook, menu, spinbox and scale
values, since those items are not exposed. In our application on Tk 9.1.0 we
now keep those calls but run spd-say in the background (exec ... &), check
for the reader at most every two seconds instead of on every call, and drop
the typed-key calls (Orca's key echo already speaks keys) and the
check/radio state calls (the bridge's state-changed event already makes
Orca announce "checked"). With that, typing into an entry no longer holds
the event loop for each key.

kevin_walzer added on 2026-10-03 19:11:26:
In developing the accessibility module, I never saw any direct narration of the keypress by Orca in Tk's widgets; that is why we are manually calling spd-say. Is there a setting in Orca that can allow it to narrate the keys as they are pressed in, say, Tk's text widget as opposed as into the console/terminal?  On macOS and Windows, these keypresses and words are narrated by the custom announcement/event change API's of NSAccessibility and MSAA. ATK has no such functionality. Before I consider such as fundamental change to the design, I need to understand better how this works. I would prefer not to shell out to spd-say, but I am not aware of any alternative here, even if it does impact performance.

Attachments: