Skip to content

Commit d2ab418

Browse files
[CP-stable][linux] Read heading text through the AtkText interface (#191397)
This pull request is created by [automatic cherry pick workflow](https://github.com/flutter/flutter/blob/main/docs/releases/Flutter-Cherrypick-Process.md#automatically-creates-a-cherry-pick-request) Please fill in the form below, and a flutter domain expert will evaluate this cherry pick request. ### Issue Link: What is the link to the issue this cherry-pick is addressing? #187925 ### Impact Description: What is the impact (ex. visual jank on Samsung phones, app crash, cannot ship an iOS app)? Does it impact development (ex. flutter doctor crashes when Android Studio is installed), or the shipping of production apps (the app crashes on launch). This information is for domain experts and release engineers to understand the consequences of saying yes or no to the cherry pick. Linux embedder was not correctly handling semantic nodes with `header` set to true, which meant screen readers would not announce these correctly. ### Changelog Description: Explain this cherry pick: * In one line that is accessible to most Flutter developers. * That describes the state prior to the fix. * That includes which platforms are impacted. See [best practices](https://github.com/flutter/flutter/blob/main/docs/releases/Hotfix-Documentation-Best-Practices.md) for examples. [flutter/187925] Fix header elements not being announced by screen reader on Linux ### Workaround: Is there a workaround for this issue? No workaround. ### Risk: What is the risk level of this cherry-pick? ### Test Coverage: Are you confident that your fix is well-tested by automated tests? ### Validation Steps: What are the steps to validate that this fix works? Run Flutter app in #187925 on Linux with screen reader enabled. Tab to heading and confirm it is correctly read out as "Section One" instead of "header".
1 parent a3eae14 commit d2ab418

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)