Tk Source Code

View Ticket
Login
Ticket UUID: 74d973b49d12c344479b0ca7ead18d60339bf991
Title: X11 accessibility: widgets are named by their class ("Button, button, Save"); X11 reads the attributes differently from Windows and macOS
Type: Bug Version: 9.1
Submitter: anonymous Created on: 2026-10-03 17:33:59
Subsystem: (unused) Assigned To: kevin_walzer
Priority: 5 Medium Severity: Minor
Status: Closed Last Modified: 2026-10-11 01:29:29
Resolution: Fixed Closed By: kevin_walzer
    Closed on: 2026-10-11 01:29:29
Description:
The class bindings in library/accessibility.tcl store the role word in the
"name" attribute and the widget's text in "description". For a
"ttk::button -text Save": name "Button", description "Save"; for an empty
ttk::entry: name "Entry", description "Entry".

The Windows bridge answers accName from "description"
(TkRootAccessible_get_accName -> TkAccDescription) and accHelp from "help".
The macOS bridge answers accessibilityLabel from "description" and its help
from "help". The X11 bridge alone answers the ATK name from "name"
(GetAtkNameForWidget) and the ATK description from "description"
(tk_get_description). So on X11 every widget is named by its class word and
its text is read afterwards as a description. Orca 48.1, from its
--debug-file log, for widgets whose accessible tree is the same as below:

    ttk::button -text Save   ->  "Button button."  "Save."
    empty ttk::entry         ->  "Entry entry."

Accessible tree of the attached repro.tcl, stock 9.1.0 (AT-SPI):

    application 'Tk Application'
      [window] name=''
        [unknown] name=''
          [button] name='Button'  description='Save'
          [entry] name='Entry'  description='Entry'
          [unknown] name='Checkbutton'  description='Enable'
          [label] name='Ready.'

It also means an application cannot label a widget portably: Windows and
macOS read set_acc_description as the name, X11 reads set_acc_name.

Proposed fix (02.patch), making X11 agree with the other two bridges:

1. GetAtkNameForWidget: a non-empty "description" first; then, as now, a
   label's value; then "name", unless it is just the role word that the
   class binding put there.
2. tk_get_description: the "help" attribute.
3. accessibility.tcl: the class bindings that pass the role word as the
   description (Canvas, Toggleswitch, TCombobox, Entry, TEntry, Listbox,
   TProgressbar, Scale, TScale, Scrollbar, TScrollbar, Spinbox, TSpinbox,
   Text) pass {} instead. The reader announces the role itself, and on
   Windows these defaults are the accessible name too ("Entry" for every
   entry).
4. accessibility.tcl: the navigation help texts ("To navigate, click the
   mouse or trackpad and then use standard keyboard navigation. ...") are
   set only when the windowing system is not x11. With 2. they would become
   the ATK description, which Orca reads on every focus change, and they
   describe mouse and trackpad use. The patch does not change them on
   Windows and macOS.
5. The application object is named by [tk appname] instead of the fixed
   "Tk Application", so a reader can say which application a window belongs
   to. The atk-util-get-root branch (ticket b9d85fc100) reworks the same
   root object; the two will need merging.

Tree with the patch (the check box role comes from the separate ticket
about the role table):

    application 'repro.tcl'
      [window] name=''
        [unknown] name=''
          [button] name='Save'
          [entry] name=''
          [check box] name='Enable'
          [label] name='Ready.'

Behaviour change to note: on X11 a name set only with set_acc_name is now
used only when no description is set. On Windows it is never used for a
child widget; accName comes from the description alone.

Not addressed by the patch: the main window "." has no accessible name
(window name='' above). The Toplevel <Map> binding does not apply to "."
(its class is the application's), and a later [wm title] is not followed
for any toplevel. The Windows bridge reads the title from the window itself
(GetWindowText); the X11 bridge could answer a toplevel's name from
[wm title] in the same way.
User Comments: kevin_walzer added on 2026-10-11 01:29:29:
As OP has not responded, merging updates to trunk and calling this ticket fixed.

kevin_walzer added on 2026-10-08 18:54:26:
Can this branch be merged?

kevin_walzer added on 2026-10-08 00:59:02:
I found Serhiy's patch - it was just one line - and applied it, and now the toplevel title is narrated only once. To me, narrating the toplevel name is sufficient - I chose "Tk Application" because "tk appname" most often defaults to "wish.$majorversion.$minorversion," and I was not fond of that. So my inclination is to leave that as is.

kevin_walzer added on 2026-10-07 21:00:17:
I thought I merged the branch with the toplevel parent patch. I can’t tell from your report if that is working or not? In my testing toplevel window titles are narrated once. 

I did not accept every suggestion you made. I am leaving the widget naming as is. Have you tried deferring your custom names until after the widgets are mapped? That should override the default values.

0xjnml added on 2026-10-07 20:36:27:
You are right about the regression, and it was my mistake. I reproduced
it with Orca 48.1 on a MATE desktop (Debian 13): wish built from the 9.1.0
tarball plus x11-accessibility-combined.patch, running the widget demo
through the attached demo-tour.tcl, which opens the entry1, check, radio
and ttkbut demos and moves the focus through them with tk_focusNext (23
focus changes). Orca said nothing at all. Its debug log gives the reason
for every window:

    AXUtilities: [window: 'Entry Demonstration (no scrollbars)'] from
        [application: ...] lacks active state

The combined patch includes Serhiy's fix that gives toplevels the
application as their parent. Once a window has a parent, Orca 48.1
ignores focus events from it unless it reports ATK_STATE_ACTIVE, which
Tk 9.1.0 never does. That state was in a separate patch,
active-window.patch on 595d72d0a6; with both applied, Orca read the demo.
I should have said that the two belong together. Sorry for the time this
cost you.

Then the same run with alt_x11_accessibility_fixes at [30d3e9a7b7], built
with ATK and libspeechd:

- No control is announced twice, and each is named by its text, with
  its role and state: "Dismiss button.", "Safety Check check box not
  checked.", "Point Size 10 not selected radio button.", "clam button.".
  Stock 9.1.0 said "Button button. Dismiss." twice for every button, and
  "Radiobutton selected radio button" for radio buttons none of which
  was selected.
- An entry without a name is read "entry." instead of "Entry entry.".
- When a window opens, Orca announces its title three times, for
  example "Entry Demonstration (no scrollbars) frame" three times within
  a second, for every demo window and for the main window.
- The window still has no parent: an AT-SPI client reads it as None, as
  in stock 9.1.0, so Serhiy's point on 3b2c972f29 stands. Since the
  branch reports ATK_STATE_ACTIVE, his one-line fix is now safe: with the
  attached alt-toplevel-parent.patch (that line, in
  RegisterToplevelWindow) the parent is the application, each window's
  title is announced once instead of three times, and the controls are
  read as before, once each.
- The application is still named "Tk Application" rather than by
  [tk appname].
- A name set by the application is still replaced when the widget is
  mapped (87bd2b899a): in the repro.tcl from that ticket, a button named
  "Open file" before mapping is named "Open" afterwards, and its
  description is cleared.

The checkbutton's role is now "check box" (324059e3d0).

I will test the branch on Windows with Narrator (25e7db2d87) and on macOS
with VoiceOver next, and report there and here.

kevin_walzer added on 2026-10-04 22:20:22:
I don't quite understand why, but this large patch winds up causing significant regressions with ATK - to the point where the only narration in Tk's widget demo comes from the manual speech from spd-say. So I don't think I can use this in its current form. To move the review forward, I have committed a separate branch, [alt_x11_accessibility_fixes], that does the following:

1. Tk now narrates toplevel windows.
2. Widgets are no longer narrated twice. 
3. Buttons with a text label of "Test" are now narrated "Test button," which I believe is cleaner. 
4. Manual spech is now routed through libspeechd, rather than shelling out to spd-say, which should improve performance. 

Because of these changes, libatk/at-spi and libspeechd are now hard build dependencies on X11. It was a mistake to make them optional. 

At present I am leaving labels as is in terms of focus and tabbing because I do not agree with the suggested change. Also, the patch for radiobutton / checkbutton state has not been reviewed, but I would like to take a closer look. 

Can you please review this branch and see if it accomplishes the above for you? Please also test it on macOS and Windows to ensure it does not cause any breakage on those platforms. If the X11 bits work, then we can look at the checkbutton patch next, and then the Windows patch. 

I greatly appreciate your input on the accessibility - it is exciting to see this new feature moving into a production application so quickly. I want this  to work as well as possible. The updates to X11 accessibility are going to be incorporated into Tk's upcoming native Wayland port - to my pleasant surprise, ATK works just fine on native Wayland with a few adjustments. (My prior efforts there included trying to implement a full at-spi interface via sd-bus, which overwhelmed Tk's event loop - and then to try a super-lightweight approach using manual speech for everything via libspeechd, which was not adequate for full accessibility.) 

Looking forward to your additional comments and review.

0xjnml added on 2026-10-04 14:06:34:
Thanks for looking at these. I can't create branches in the Fossil
repository, so the attached x11-accessibility-combined.patch has all of the
changes in one patch (patch -p1 from the Tk source root). It applies to
trunk, which has the same two files as 9.1.0, and also applies unchanged on
top of the atk-util-get-root branch. That branch is Serhiy's fix for ticket
b9d85fc100, two check-ins of 2026-09-25:
https://core.tcl-lang.org/tk/timeline?r=atk-util-get-root

The patch contains:

1. 3b2c972f29: "active-descendant-changed" is emitted only from item
   containers (list, tree, table, menu). It also includes Serhiy's one-line
   fix from that ticket, which gives toplevel accessibles the root as their
   parent; with it the window's parent is the application instead of none.
2. 74d973b49d (this ticket): the X11 name comes from the "description"
   attribute and the ATK description from "help", as on Windows and macOS.
   The class bindings no longer pass the role word ("Entry", "Scale") as
   the description, the mouse and trackpad help texts are set only off
   X11, and the application object is named by [tk appname].
3. 324059e3d0: "Checkbutton" is added to the X11 role table.
4. 87bd2b899a: _init no longer overwrites attributes set by the
   application, and still refreshes its own defaults (the notebook's
   current tab, for example).
5. Not filed separately: on X11 every radio button is reported as checked,
   and a check box stays checked after it is unchecked. tk_ref_state_set
   counts any "value" not starting with "0" as checked, while the bindings
   store a radio button's variable *name* at map time and "not selected"
   after a change; the state-changed event sent by EmitSelectionChanged
   uses the stricter test and is right. Orca said "Small, selected, radio
   button" for an unselected one. The patch makes the bindings store
   _getcheckdata / _getradiodata ("selected" / "not selected") and gives
   tk_ref_state_set the same test as EmitSelectionChanged. The attached
   check-radio-state-repro.tcl shows it; with stock 9.1.0 both radio
   buttons stay checked=True, with the patch:

       at start:  Small checked=True,  Large checked=False, Remember checked=False
       after:     Small checked=False, Large checked=True,  Remember checked=False

Checked with Tk 9.1.0 built from the release tarball with the ATK bridge,
under Xvfb with an AT-SPI client: the accessible trees, events and states
quoted in the tickets come out as described there, and Tk's test suite gives
the same result with and without the patch (9733 tests; the same 15
failures, send, unixWm and wm tests that need a window manager, on both;
the ttk tests 2042 run, 0 failed). By ear, with Orca 48.1 in an application
embedding Tk 9.1.0 with equivalent changes, each control is announced once
and named by its text or by the label the application gave it.

The patch leaves out 48b39019bd (Tk's own speech) and 595d72d0a6 (labels as
Tab stops); I'll answer your questions on those tickets.

kevin_walzer added on 2026-10-03 19:17:40:
You refer to a "atk-util-get-root branch" - I do not see any indication of that. Are you able to incorporate your suggested changes in your multiple tickets into a single branch that I can review?

Attachments: