Skip to content

Commit 7c18a85

Browse files
[linux] Read heading text through the AtkText interface (flutter#188005)
Fixes flutter#187925 ## 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/`): 1. **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.) 2. **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 flutter#187925, Orca now announces **"Section One, heading"** instead of just **"header"**. ## Test plan - [x] Added `ExposesTextViaAtkText` test verifying `atk_text_get_character_count` / `atk_text_get_text` / `atk_text_get_character_at_offset` return the node's label. - [x] 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. --------- Co-authored-by: Robert Ancell <[email protected]>
1 parent 6807bd9 commit 7c18a85

2 files changed

Lines changed: 224 additions & 2 deletions

File tree

‎engine/src/flutter/shell/platform/linux/fl_accessible_node.cc‎

Lines changed: 166 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ enum { PROP_0, PROP_ENGINE, PROP_VIEW_ID, PROP_ID, PROP_LAST };
7272
static void fl_accessible_node_component_interface_init(
7373
AtkComponentIface* iface);
7474
static void fl_accessible_node_action_interface_init(AtkActionIface* iface);
75+
static void fl_accessible_node_text_interface_init(AtkTextIface* iface);
7576

7677
G_DEFINE_TYPE_WITH_CODE(
7778
FlAccessibleNode,
@@ -81,7 +82,9 @@ G_DEFINE_TYPE_WITH_CODE(
8182
G_IMPLEMENT_INTERFACE(ATK_TYPE_COMPONENT,
8283
fl_accessible_node_component_interface_init)
8384
G_IMPLEMENT_INTERFACE(ATK_TYPE_ACTION,
84-
fl_accessible_node_action_interface_init))
85+
fl_accessible_node_action_interface_init)
86+
G_IMPLEMENT_INTERFACE(ATK_TYPE_TEXT,
87+
fl_accessible_node_text_interface_init))
8588

8689
// Returns TRUE if [flags] indicate this element is checkable.
8790
static gboolean is_checkable(FlutterSemanticsFlags flags) {
@@ -240,7 +243,7 @@ static AtkRole fl_accessible_node_get_role(AtkObject* accessible) {
240243
return ATK_ROLE_TEXT;
241244
}
242245
if (priv->flags.is_header) {
243-
return ATK_ROLE_HEADER;
246+
return ATK_ROLE_HEADING;
244247
}
245248
if (priv->flags.is_link) {
246249
return ATK_ROLE_LINK;
@@ -547,6 +550,167 @@ static void fl_accessible_node_action_interface_init(AtkActionIface* iface) {
547550
iface->get_name = fl_accessible_node_get_name;
548551
}
549552

553+
// Returns the number of UTF-8 characters in this node's text content. A
554+
// Flutter semantics node's text content is its accessibility name.
555+
static gint fl_accessible_node_get_text_length(FlAccessibleNodePrivate* priv) {
556+
return priv->name != nullptr
557+
? static_cast<gint>(g_utf8_strlen(priv->name, -1))
558+
: 0;
559+
}
560+
561+
// Implements AtkText::get_character_count.
562+
static gint fl_accessible_node_get_character_count(AtkText* text) {
563+
FlAccessibleNodePrivate* priv = FL_ACCESSIBLE_NODE_GET_PRIVATE(text);
564+
return fl_accessible_node_get_text_length(priv);
565+
}
566+
567+
// Implements AtkText::get_text.
568+
static gchar* fl_accessible_node_get_text(AtkText* text,
569+
gint start_offset,
570+
gint end_offset) {
571+
FlAccessibleNodePrivate* priv = FL_ACCESSIBLE_NODE_GET_PRIVATE(text);
572+
if (priv->name == nullptr) {
573+
return g_strdup("");
574+
}
575+
576+
gint count = fl_accessible_node_get_text_length(priv);
577+
start_offset = CLAMP(start_offset, 0, count);
578+
if (end_offset < 0) {
579+
end_offset = count;
580+
}
581+
end_offset = CLAMP(end_offset, start_offset, count);
582+
583+
return g_utf8_substring(priv->name, start_offset, end_offset);
584+
}
585+
586+
// Implements AtkText::get_character_at_offset.
587+
static gunichar fl_accessible_node_get_character_at_offset(AtkText* text,
588+
gint offset) {
589+
FlAccessibleNodePrivate* priv = FL_ACCESSIBLE_NODE_GET_PRIVATE(text);
590+
if (priv->name == nullptr || offset < 0 ||
591+
offset >= fl_accessible_node_get_text_length(priv)) {
592+
return 0;
593+
}
594+
595+
return g_utf8_get_char(g_utf8_offset_to_pointer(priv->name, offset));
596+
}
597+
598+
// Implements AtkText::get_caret_offset.
599+
// Static text such as a heading has no caret.
600+
static gint fl_accessible_node_get_caret_offset(AtkText* text) {
601+
(void)text;
602+
return -1;
603+
}
604+
605+
// Implements AtkText::get_n_selections.
606+
// Static text such as a heading cannot be selected, so report no selections.
607+
static gint fl_accessible_node_get_n_selections(AtkText* text) {
608+
(void)text;
609+
return 0;
610+
}
611+
612+
// Implements AtkText::get_selection.
613+
static gchar* fl_accessible_node_get_selection(AtkText* text,
614+
gint selection_num,
615+
gint* start_offset,
616+
gint* end_offset) {
617+
(void)text;
618+
(void)selection_num;
619+
if (start_offset != nullptr) {
620+
*start_offset = 0;
621+
}
622+
if (end_offset != nullptr) {
623+
*end_offset = 0;
624+
}
625+
return nullptr;
626+
}
627+
628+
// Implements AtkText::get_string_at_offset.
629+
static gchar* fl_accessible_node_get_string_at_offset(
630+
AtkText* text,
631+
gint offset,
632+
AtkTextGranularity granularity,
633+
gint* start_offset,
634+
gint* end_offset) {
635+
FlAccessibleNodePrivate* priv = FL_ACCESSIBLE_NODE_GET_PRIVATE(text);
636+
gint count = fl_accessible_node_get_text_length(priv);
637+
if (offset < 0 || offset >= count) {
638+
if (start_offset != nullptr) {
639+
*start_offset = 0;
640+
}
641+
if (end_offset != nullptr) {
642+
*end_offset = 0;
643+
}
644+
return nullptr;
645+
}
646+
647+
switch (granularity) {
648+
case ATK_TEXT_GRANULARITY_CHAR:
649+
if (start_offset != nullptr) {
650+
*start_offset = offset;
651+
}
652+
if (end_offset != nullptr) {
653+
*end_offset = offset + 1;
654+
}
655+
return g_utf8_substring(priv->name, offset, offset + 1);
656+
case ATK_TEXT_GRANULARITY_WORD:
657+
case ATK_TEXT_GRANULARITY_SENTENCE:
658+
case ATK_TEXT_GRANULARITY_LINE:
659+
case ATK_TEXT_GRANULARITY_PARAGRAPH:
660+
if (start_offset != nullptr) {
661+
*start_offset = 0;
662+
}
663+
if (end_offset != nullptr) {
664+
*end_offset = count;
665+
}
666+
return g_strdup(priv->name != nullptr ? priv->name : "");
667+
default:
668+
return nullptr;
669+
}
670+
}
671+
672+
// Implements AtkText::get_text_at_offset (deprecated, but still used by some
673+
// ATK clients to read the text content of non-editable objects such as
674+
// headings).
675+
static gchar* fl_accessible_node_get_text_at_offset(
676+
AtkText* text,
677+
gint offset,
678+
AtkTextBoundary boundary_type,
679+
gint* start_offset,
680+
gint* end_offset) {
681+
switch (boundary_type) {
682+
case ATK_TEXT_BOUNDARY_CHAR:
683+
return fl_accessible_node_get_string_at_offset(
684+
text, offset, ATK_TEXT_GRANULARITY_CHAR, start_offset, end_offset);
685+
case ATK_TEXT_BOUNDARY_WORD_START:
686+
case ATK_TEXT_BOUNDARY_WORD_END:
687+
return fl_accessible_node_get_string_at_offset(
688+
text, offset, ATK_TEXT_GRANULARITY_WORD, start_offset, end_offset);
689+
case ATK_TEXT_BOUNDARY_SENTENCE_START:
690+
case ATK_TEXT_BOUNDARY_SENTENCE_END:
691+
return fl_accessible_node_get_string_at_offset(
692+
text, offset, ATK_TEXT_GRANULARITY_SENTENCE, start_offset,
693+
end_offset);
694+
case ATK_TEXT_BOUNDARY_LINE_START:
695+
case ATK_TEXT_BOUNDARY_LINE_END:
696+
return fl_accessible_node_get_string_at_offset(
697+
text, offset, ATK_TEXT_GRANULARITY_LINE, start_offset, end_offset);
698+
default:
699+
return nullptr;
700+
}
701+
}
702+
703+
static void fl_accessible_node_text_interface_init(AtkTextIface* iface) {
704+
iface->get_character_count = fl_accessible_node_get_character_count;
705+
iface->get_text = fl_accessible_node_get_text;
706+
iface->get_character_at_offset = fl_accessible_node_get_character_at_offset;
707+
iface->get_caret_offset = fl_accessible_node_get_caret_offset;
708+
iface->get_n_selections = fl_accessible_node_get_n_selections;
709+
iface->get_selection = fl_accessible_node_get_selection;
710+
iface->get_text_at_offset = fl_accessible_node_get_text_at_offset;
711+
iface->get_string_at_offset = fl_accessible_node_get_string_at_offset;
712+
}
713+
550714
static void fl_accessible_node_init(FlAccessibleNode* self) {
551715
FlAccessibleNodePrivate* priv = FL_ACCESSIBLE_NODE_GET_PRIVATE(self);
552716
g_weak_ref_init(&priv->engine, nullptr);

‎engine/src/flutter/shell/platform/linux/fl_accessible_node_test.cc‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,64 @@ TEST_F(FlAccessibleNodeTest, GetRole) {
336336
flags6.is_obscured = true;
337337
fl_accessible_node_set_flags(node, &flags6);
338338
EXPECT_EQ(atk_object_get_role(ATK_OBJECT(node)), ATK_ROLE_PASSWORD_TEXT);
339+
340+
FlutterSemanticsFlags flags7 = {};
341+
flags7.is_header = true;
342+
fl_accessible_node_set_flags(node, &flags7);
343+
EXPECT_EQ(atk_object_get_role(ATK_OBJECT(node)), ATK_ROLE_HEADING);
344+
}
345+
346+
// Checks the node's name is exposed through the AtkText interface so that
347+
// screen readers can read the text content of objects such as headings.
348+
TEST_F(FlAccessibleNodeTest, ExposesTextViaAtkText) {
349+
g_autoptr(FlAccessibleNode) node = fl_accessible_node_new(engine, 123, 0);
350+
fl_accessible_node_set_name(node, "Section One");
351+
352+
EXPECT_EQ(atk_text_get_character_count(ATK_TEXT(node)), 11);
353+
354+
g_autofree gchar* text = atk_text_get_text(ATK_TEXT(node), 0, -1);
355+
EXPECT_STREQ(text, "Section One");
356+
357+
g_autofree gchar* substring = atk_text_get_text(ATK_TEXT(node), 0, 7);
358+
EXPECT_STREQ(substring, "Section");
359+
360+
EXPECT_EQ(atk_text_get_character_at_offset(ATK_TEXT(node), 0), gunichar('S'));
361+
362+
EXPECT_EQ(atk_text_get_caret_offset(ATK_TEXT(node)), -1);
363+
EXPECT_EQ(atk_text_get_n_selections(ATK_TEXT(node)), 0);
364+
365+
gint start_offset = -1;
366+
gint end_offset = -1;
367+
g_autofree gchar* selection =
368+
atk_text_get_selection(ATK_TEXT(node), 0, &start_offset, &end_offset);
369+
EXPECT_EQ(selection, nullptr);
370+
EXPECT_EQ(start_offset, 0);
371+
EXPECT_EQ(end_offset, 0);
372+
373+
start_offset = -1;
374+
end_offset = -1;
375+
g_autofree gchar* text_at_offset = atk_text_get_string_at_offset(
376+
ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_CHAR, &start_offset, &end_offset);
377+
EXPECT_STREQ(text_at_offset, "S");
378+
EXPECT_EQ(start_offset, 0);
379+
EXPECT_EQ(end_offset, 1);
380+
381+
start_offset = -1;
382+
end_offset = -1;
383+
g_autofree gchar* text_at_line_offset = atk_text_get_string_at_offset(
384+
ATK_TEXT(node), 0, ATK_TEXT_GRANULARITY_LINE, &start_offset, &end_offset);
385+
EXPECT_STREQ(text_at_line_offset, "Section One");
386+
EXPECT_EQ(start_offset, 0);
387+
EXPECT_EQ(end_offset, 11);
388+
389+
start_offset = -1;
390+
end_offset = -1;
391+
g_autofree gchar* text_out_of_bounds = atk_text_get_string_at_offset(
392+
ATK_TEXT(node), 100, ATK_TEXT_GRANULARITY_CHAR, &start_offset,
393+
&end_offset);
394+
EXPECT_EQ(text_out_of_bounds, nullptr);
395+
EXPECT_EQ(start_offset, 0);
396+
EXPECT_EQ(end_offset, 0);
339397
}
340398

341399
// Checks Flutter actions are mapped to the appropriate ATK actions.

0 commit comments

Comments
 (0)