[linux] Read heading text through the AtkText interface by sawirricardo · Pull Request #188005 · flutter/flutter

sawirricardo · 2026-06-15T05:10:43Z

Problem

On Linux, a node with Semantics(header: true) is announced by Orca as just "header" — the node's text is never read. With header: false the same text is read correctly.

Root cause

Two issues in the Linux embedder's accessibility code (engine/src/flutter/shell/platform/linux/):

The node's label is exposed only via the AtkObject name property, not the AtkText interface. Orca reads the text content of a heading exclusively through AtkText (see _generate_heading in Orca's speech_generator.py, which calls _generate_text_content → AXText.get_substring → atk_text_get_text). It never falls back to the name for the heading/header roles. So Orca finds no text and announces only the role.

This matches the ATK contract used by GTK: GtkLabel exposes its text through AtkText. Flutter's label is its text content, so it should be exposed the same way. (FlAccessibleTextField already does this for editable text.)
The wrong ATK role. is_header maps to ATK_ROLE_HEADER, which is the document masthead/banner role. ATK_ROLE_HEADING is the content-heading role (the HTML <h1>–<h6> analogue) and is what Semantics(header: true) means (matching iOS header trait and Android heading class).

Fix

Implement the AtkText interface on FlAccessibleNode, backed by the node's existing accessibility name (get_character_count, get_text, get_character_at_offset, get_caret_offset, get_n_selections, get_selection, get_text_at_offset). This is safe for other roles: Orca's default presentation for buttons/panels/images reads the AtkObject name via _generate_accessible_label_and_name, not AtkText, so their announcement is unchanged. FlAccessibleTextField already declares a richer AtkText and continues to override the base implementation.
Map the is_header flag to ATK_ROLE_HEADING.

Result

For the repro in #187925, Orca now announces "Section One, heading" instead of just "header".

Test plan

Added ExposesTextViaAtkText test verifying atk_text_get_character_count / atk_text_get_text / atk_text_get_character_at_offset return the node's label.
Extended the existing role-mapping test to assert is_header → ATK_ROLE_HEADING.
Linux linux_unit_tests (cannot run locally — Linux GTK/ATK build; developed/analyzed on macOS). Reviewers, please confirm CI is green.

gemini-code-assist

Code Review

This pull request implements the AtkText interface for FlAccessibleNode to expose accessibility names as text content to screen readers, and updates the header role to ATK_ROLE_HEADING. Feedback suggests aligning the AtkText implementation with ATK specifications by returning -1 when caret is unsupported, returning nullptr for invalid selections, and properly handling offset and boundary_type in fl_accessible_node_get_text_at_offset to support character-by-character navigation. Additionally, expanding test coverage to verify these behaviors is recommended.

Expose a semantics node's name as text content via the AtkText interface so screen readers announce the text of headings. Orca reads the text content of a heading exclusively through AtkText, not the AtkObject name, so a node with `Semantics(header: true)` was announced as just "header" while its text was skipped (flutter#187925). Also map the `is_header` flag to ATK_ROLE_HEADING (the content-heading role, matching HTML h1-h6 and `Semantics(header: true)`) instead of ATK_ROLE_HEADER (the document masthead/banner role). FlAccessibleTextField already implements a richer AtkText and continues to override the base implementation. Fixes flutter#187925

robert-ancell

Looks good, thanks!

mattkae

Looks good to me!

auto-submit · 2026-07-28T05:59:37Z

autosubmit label was removed for flutter/flutter/188005, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

auto-submit · 2026-07-28T22:20:08Z

autosubmit label was removed for flutter/flutter/188005, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

robert-ancell · 2026-07-29T23:39:16Z

This is failing in formatting:

diff --git a/engine/src/flutter/shell/platform/linux/fl_accessible_node_test.cc b/engine/src/flutter/shell/platform/linux/fl_accessible_node_test.cc
index 8ab8eabe5e3..00000000000 100644
--- a/engine/src/flutter/shell/platform/linux/fl_accessible_node_test.cc
+++ b/engine/src/flutter/shell/platform/linux/fl_accessible_node_test.cc
@@ -357,8 +357,7 @@ TEST_F(FlAccessibleNodeTest, ExposesTextViaAtkText) {
g_autofree gchar* substring = atk_text_get_text(ATK_TEXT(node), 0, 7);
EXPECT_STREQ(substring, "Section");
-  EXPECT_EQ(atk_text_get_character_at_offset(ATK_TEXT(node), 0),
-            gunichar('S'));
+  EXPECT_EQ(atk_text_get_character_at_offset(ATK_TEXT(node), 0), gunichar('S'));
EXPECT_EQ(atk_text_get_caret_offset(ATK_TEXT(node)), -1);
EXPECT_EQ(atk_text_get_n_selections(ATK_TEXT(node)), 0);
@@ -374,8 +373,7 @@ TEST_F(FlAccessibleNodeTest, ExposesTextViaAtkText) {
start_offset = -1;
end_offset = -1;
g_autofree gchar* text_at_offset = atk_text_get_string_at_offset(
-      ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_CHAR, &start_offset,
-      &end_offset);
+      ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_CHAR, &start_offset, &end_offset);
EXPECT_STREQ(text_at_offset, "S");
EXPECT_EQ(start_offset, 0);
EXPECT_EQ(end_offset, 1);
@@ -383,8 +381,7 @@ TEST_F(FlAccessibleNodeTest, ExposesTextViaAtkText) {
start_offset = -1;
end_offset = -1;
g_autofree gchar* text_at_line_offset = atk_text_get_string_at_offset(
-      ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_LINE, &start_offset,
-      &end_offset);
+      ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_LINE, &start_offset, &end_offset);
EXPECT_STREQ(text_at_line_offset, "Section One");
EXPECT_EQ(start_offset, 0);
EXPECT_EQ(end_offset, 11);
DONE

From https://logs.chromium.org/logs/flutter/buildbucket/cr-buildbucket/8675059841287260017/+/u/test:_test:_Check_formatting/stdout

@sawirricardo can you fix this in your branch?

sawirricardo requested a review from a team as a code owner June 15, 2026 05:10

github-actions Bot added engine flutter/engine related. See also e: labels. platform-linux Building on or for Linux specifically a: desktop Running on desktop team-linux Owned by the Linux platform team labels Jun 15, 2026

gemini-code-assist Bot reviewed Jun 15, 2026

View reviewed changes

sawirricardo force-pushed the fix-linux-heading-text-a11y branch from 25b4f44 to aae0d05 Compare June 15, 2026 08:56

robert-ancell added the CICD Run CI/CD label Jun 17, 2026

robert-ancell previously approved these changes Jun 17, 2026

View reviewed changes

robert-ancell enabled auto-merge June 17, 2026 03:35

Fix ATK text offset test deprecation

98d62c0

auto-merge was automatically disabled June 17, 2026 11:24
Head branch was pushed to by a user without write access

sawirricardo dismissed robert-ancell’s stale review via 98d62c0 June 17, 2026 11:24

github-actions Bot removed the CICD Run CI/CD label Jun 17, 2026

robert-ancell previously approved these changes Jul 1, 2026

View reviewed changes

robert-ancell enabled auto-merge July 1, 2026 20:32

robert-ancell requested a review from mattkae July 8, 2026 22:43

mattkae previously approved these changes Jul 9, 2026

View reviewed changes

Merge branch 'master' into fix-linux-heading-text-a11y

61e1d44

robert-ancell added the CICD Run CI/CD label Jul 14, 2026

Merge branch 'master' into fix-linux-heading-text-a11y

7868ac4

flutter-dashboard Bot removed the CICD Run CI/CD label Jul 28, 2026

robert-ancell added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Jul 28, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

robert-ancell added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 28, 2026

Merge branch 'master' into fix-linux-heading-text-a11y

1873dbc

flutter-dashboard Bot removed the CICD Run CI/CD label Jul 29, 2026

robert-ancell added the CICD Run CI/CD label Jul 29, 2026

linux: fix formatting in fl_accessible_node_test

05d2cfb

auto-merge was automatically disabled August 5, 2026 07:18
Head branch was pushed to by a user without write access

sawirricardo dismissed stale reviews from robert-ancell and mattkae via 05d2cfb August 5, 2026 07:18

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 5, 2026

mattkae added the CICD Run CI/CD label Aug 12, 2026

Merge branch 'master' into fix-linux-heading-text-a11y

9ba474a

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 19, 2026

robert-ancell approved these changes Aug 19, 2026

View reviewed changes

robert-ancell enabled auto-merge August 19, 2026 02:28

robert-ancell added the CICD Run CI/CD label Aug 19, 2026

mattkae approved these changes Aug 19, 2026

View reviewed changes

robert-ancell added this pull request to the merge queue Aug 19, 2026

Merged via the queue into flutter:master with commit 7c18a85 Aug 19, 2026
24 checks passed

This was referenced Aug 19, 2026

Roll Flutter from c2437523d308 to a539e0ed6058 (126 revisions) flutter/packages#12510

Closed

Roll Flutter from c2437523d308 to 7099814fba85 (127 revisions) flutter/packages#12511

Closed

robert-ancell added the cp: stable cherry pick this pull request to stable release candidate branch label Aug 20, 2026

justinmc mentioned this pull request Aug 21, 2026

Flutter Notable Commits - 2026 #181433

Open

Navigation Menu

Repository navigation

[linux] Read heading text through the AtkText interface - #188005

[linux] Read heading text through the AtkText interface#188005
robert-ancell merged 7 commits into
flutter:masterfrom
sawirricardo:fix-linux-heading-text-a11y

sawirricardo commented Jun 15, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

robert-ancell left a comment

Uh oh!

mattkae left a comment

Uh oh!

auto-submit Bot commented Jul 28, 2026

Uh oh!

auto-submit Bot commented Jul 28, 2026

Uh oh!

robert-ancell commented Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

sawirricardo commented Jun 15, 2026

Problem

Root cause

Fix

Result

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

robert-ancell left a comment

Choose a reason for hiding this comment

Uh oh!

mattkae left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Jul 28, 2026

Uh oh!

auto-submit Bot commented Jul 28, 2026

Uh oh!

robert-ancell commented Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants