[Android] VoiceOver on Toolbar Item

[kubaflo]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Issues Fixed

Fixes #29573
Fixes #23623

[Copilot]

Pull Request Overview

This PR enhances the accessibility support for Android Toolbar items by configuring VoiceOver semantics.

• Introduces a new helper method, SetSemanticProperties, to update accessibility information on Toolbar items.
• Implements the AccessibilityDelegateCompatImpl to correctly set ContentDescription and HintText based on semantic properties.
• Adds necessary AndroidX Core API references needed for the enhancements.

Comments suppressed due to low confidence (1)

src/Controls/src/Core/Platform/Android/Extensions/ToolbarExtensions.cs:354

• Ensure that automated tests are added in TestCases.HostApp and TestCases.Shared.Tests to verify that the new accessibility delegate correctly applies the semantic properties (ContentDescription and HintText) on Toolbar items.

SetSemanticProperties(item, toolbar.FindViewById(menuitem.ItemId));

[dotnet-policy-service]

Hey there @@kubaflo! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 29596

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 29596"

[kubaflo]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — [Android] VoiceOver on Toolbar Item · 4be0720

---

PR: #29596 - [Android] VoiceOver on Toolbar Item
Author: kubaflo (Jakub Florkowski)
Issues Fixed: #29573 (VoiceOver on Toolbar Item), #23623 (SemanticProperties do not work on ToolbarItems)
Platforms Affected: Android (primary focus)
Labels: platform/android, area-controls-toolbar, t/a11y

Issue Summary

Both issues report that SemanticProperties.Description and SemanticProperties.Hint do not work on ToolbarItem controls on Android. The deprecated AutomationProperties.Name worked as a workaround, but the documented approach (SemanticProperties) does not. The bug affects Android (confirmed reproducible across .NET 8.0.100, 9.0.0, and 9.0.70).

Files Changed

Fix files (implementation):

• src/Controls/src/Core/Platform/Android/Extensions/ToolbarExtensions.cs (+52/-0)

Test files (device tests):

• src/Controls/tests/DeviceTests/Elements/Toolbar/ToolbarTests.Android.cs (+129/-0) — new file

Test Type: Device Tests (Xunit-based, runs on Android device/emulator)

PR Approach

The PR adds a SetSemanticProperties method that:

1. Calls SemanticProperties.UpdateSemantics on the ToolbarItem
2. If description or hint is set, applies ImportantForAccessibility.Yes and sets a custom AccessibilityDelegateCompat via ViewCompat.SetAccessibilityDelegate
3. The delegate's OnInitializeAccessibilityNodeInfo sets ContentDescription and HintText on the AccessibilityNodeInfoCompat
4. If no accessibility info is present, clears any previously set delegate

The method is called at the end of UpdateMenuItem, after the menu item view is available via toolbar.FindViewById(menuitem.ItemId).

PR Discussion

• Copilot code review suggested adding automated tests in TestCases.HostApp (UI tests), but the PR author added device tests instead which test the accessibility delegate directly.
• No human reviewer has approved yet.

Key Findings

• The fix only covers Android - iOS issue may still exist
• Tests directly verify the AccessibilityDelegateCompat properties, which is the correct approach for device tests
• GetPlatformToolbar helper is available in ControlsHandlerTestBase.Android.cs

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #29596	Add AccessibilityDelegateCompat via ViewCompat.SetAccessibilityDelegate in UpdateMenuItem; sets ContentDescription and HintText from SemanticProperties	⏳ PENDING (Gate)	ToolbarExtensions.cs (+52), ToolbarTests.Android.cs (+129)	Original PR

---

🚦 Gate — Test Verification

---

📝 Review Session — [Android] VoiceOver on Toolbar Item · 4be0720

---

Result: ❌ FAILED
Platform: android
Mode: Full Verification Attempted

Gate Failure: Test Compilation Errors

The PR adds device tests (ToolbarTests.Android.cs) that fail to compile with 3 errors:

Line	Error	Details
40	CS0234	The type or namespace name 'Views' does not exist in the namespace 'Microsoft.Android' — Missing using Android.Views; import
53	CS0618	AccessibilityNodeInfoCompat.Recycle() is obsolete/deprecated
93	CS0618	AccessibilityNodeInfoCompat.Recycle() is obsolete/deprecated

Root Cause

1. Missing using Android.Views; — Test file uses Android.Views.ImportantForAccessibility.Yes at line 40, but without the using Android.Views; directive, the compiler resolves Android as Microsoft.Android (the .NET 10 rebinding), causing CS0234.

2. Deprecated API usage — AccessibilityNodeInfoCompat.Recycle() is deprecated in the AndroidX library. The test calls it in finally blocks at lines 53 and 93.

Additional Notes

• The verify-tests-fail-without-fix skill was unable to run (mismatch: skill targets UI tests via TestCases.HostApp; these are Device Tests via Controls.DeviceTests.csproj)
• Direct device test build confirmed the compilation errors independently
• The fix in ToolbarExtensions.cs itself appears valid — the test issues are isolated to ToolbarTests.Android.cs

Verification Status

• Tests WITHOUT fix: Could not confirm (tests don't compile)
• Tests WITH fix: Could not confirm (tests don't compile)

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — [Android] VoiceOver on Toolbar Item · 4be0720

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #29596	Add AccessibilityDelegateCompat via ViewCompat.SetAccessibilityDelegate in UpdateMenuItem; sets ContentDescription and HintText from SemanticProperties	⏳ PENDING (Gate blocked)	ToolbarExtensions.cs (+52), ToolbarTests.Android.cs (+129)	Original PR

Exhausted: N/A — try-fix skipped (environment blocker)

Selected Fix: PR's fix — The implementation approach in ToolbarExtensions.cs is correct; test compilation errors are the only blocking issue

Why try-fix was skipped

The device tests added by the PR fail to compile due to 3 errors in ToolbarTests.Android.cs:

1. CS0234 — Missing using Android.Views; (or equivalent alias)
2. CS0618 × 2 — Deprecated AccessibilityNodeInfoCompat.Recycle() calls

Running try-fix alternatives would fail at the build stage before any test could execute. Since Gate already identified the real issues, try-fix exploration was skipped per autonomous execution rules.

---

📋 Report — Final Recommendation

---

📝 Review Session — [Android] VoiceOver on Toolbar Item · 4be0720

---

⚠️ Final Recommendation: REQUEST CHANGES

Summary

PR #29596 fixes a real, confirmed bug: SemanticProperties.Description and SemanticProperties.Hint are ignored on Android ToolbarItem controls. The implementation approach in ToolbarExtensions.cs is correct and follows proper Android accessibility patterns. However, the device tests added by the PR fail to compile with 3 errors, blocking merge.

---

Root Cause (of the Bug)

UpdateMenuItem in ToolbarExtensions.cs never propagated SemanticProperties to the native menu item view. Android menu items rendered via toolbar.FindViewById(menuitem.ItemId) had no AccessibilityDelegateCompat set, so TalkBack/VoiceOver ignored any MAUI semantic metadata.

Fix Quality Assessment

The implementation in ToolbarExtensions.cs is correct:

• SemanticProperties.UpdateSemantics(menuItem, null) properly reads the MAUI semantic data
• ViewCompat.SetAccessibilityDelegate + AccessibilityDelegateCompat is the correct Android pattern for injecting accessibility info
• OnInitializeAccessibilityNodeInfo override correctly sets both ContentDescription (Description) and HintText (Hint)
• Delegate removal when no semantics are present is properly handled
• ImportantForAccessibility.Yes correctly marks the view as accessibility-relevant

---

Gate Result

❌ BLOCKED — Device tests fail to compile (3 errors):

Line	Error Code	Issue	Fix Required
40	CS0234	Android.Views.ImportantForAccessibility not resolvable (missing using Android.Views;)	Add using ImportantForAccessibility = Android.Views.ImportantForAccessibility;
53	CS0618	AccessibilityNodeInfoCompat.Recycle() is deprecated	Remove Recycle() call or add #pragma warning disable CS0618
93	CS0618	AccessibilityNodeInfoCompat.Recycle() is deprecated	Remove Recycle() call or add #pragma warning disable CS0618

---

Code Review Findings

🔴 Critical: Test Compilation Failures

File: src/Controls/tests/DeviceTests/Elements/Toolbar/ToolbarTests.Android.cs

Problem 1 (Line 40): Uses Android.Views.ImportantForAccessibility.Yes without using Android.Views;.
The codebase pattern (see ControlsHandlerTestBase.Android.cs:22) is to use a type alias:

// Add at top of file:
using ImportantForAccessibility = Android.Views.ImportantForAccessibility;

// Then at line 40:
Assert.Equal(ImportantForAccessibility.Yes, view.ImportantForAccessibility);

Problem 2 (Lines 53 & 93): AccessibilityNodeInfoCompat.Recycle() is deprecated. Remove the Recycle() calls entirely — the object is GC-managed in modern AndroidX:

// Before:
var nodeInfo = AccessibilityNodeInfoCompat.Obtain();
try
{
    accessibilityDelegate.OnInitializeAccessibilityNodeInfo(view, nodeInfo);
    Assert.Equal("Save document", nodeInfo.ContentDescription);
}
finally
{
    nodeInfo.Recycle();  // ← Remove this
}

// After:
var nodeInfo = AccessibilityNodeInfoCompat.Obtain();
accessibilityDelegate.OnInitializeAccessibilityNodeInfo(view, nodeInfo);
Assert.Equal("Save document", nodeInfo.ContentDescription);

🟡 Minor Suggestions

Duplicate FindViewById call:
In UpdateMenuItem, toolbar.FindViewById(menuitem.ItemId) is called twice — once for the text color check and again for SetSemanticProperties. Consider caching the view:

var view = toolbar.FindViewById(menuitem.ItemId);
if (item.Order != ToolbarItemOrder.Secondary && !OperatingSystem.IsAndroidVersionAtLeast(26) && tintColor != null)
{
    if (view is ATextView textView)
    {
        // ...
    }
}
SetSemanticProperties(item, view);

Property change handling:
SetSemanticProperties is only called during the initial UpdateMenuItem. If the user changes SemanticProperties.Description after render, the accessibility delegate won't update. Consider whether this needs to be wired to a PropertyChanged listener on the ToolbarItem.

✅ Looks Good

• Implementation correctly uses ViewCompat.SetAccessibilityDelegate (not deprecated setAccessibilityDelegate)
• AccessibilityDelegateCompat subclass is cleanly implemented as a nested class
• Null checking (if (view == null) return;) is handled
• Both Description (→ ContentDescription) and Hint (→ HintText) are mapped correctly
• The base.OnInitializeAccessibilityNodeInfo(host, info) call is preserved, ensuring default behavior is not lost
• Test covers 3 cases: Description only, Hint only, and no semantics (no delegate)
• Issue VoiceOver on Toolbar Item #29573 and SemanticProperties do not work on ToolbarItems #23623 are both addressed
• PR has the required NOTE block

---

Title & Description Review

Current title: [Android] VoiceOver on Toolbar Item
Recommended: [Android] ToolbarItem: Support SemanticProperties.Description and Hint via AccessibilityDelegateCompat

The current title uses "VoiceOver" (iOS term) rather than "TalkBack" (Android term), and doesn't capture the technical approach.

Description quality: Minimal — only has the NOTE block and issue links. For future agents, should add:

• Root cause (SemanticProperties never propagated to native menu item view)
• Fix approach (AccessibilityDelegateCompat set in UpdateMenuItem)
• Platform scope (Android only; iOS may still need work per issue SemanticProperties do not work on ToolbarItems #23623)

---

Changes Needed Before Merge

1. Fix CS0234 — Add using ImportantForAccessibility = Android.Views.ImportantForAccessibility; to ToolbarTests.Android.cs
2. Fix CS0618 — Remove Recycle() calls at lines 53 and 93
3. Optional: Improve PR title and description
4. Optional: Cache the FindViewById result to avoid double call

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: [Android] VoiceOver on Toolbar Item

Description: ⚠️ Needs Update

• Uses "VoiceOver" (Apple/iOS term) — the correct Android term is "TalkBack"
• Does not describe what was technically fixed or how
  Missing Elements:

**

• Root cause (why the bug occurred)
• Description of change (what the fix does)
• Technical approach (AccessibilityDelegateCompat pattern)
• Platform scope note (Android only; iOS may still need a fix)

Action: See recommended-description.md for a full suggested description.

---

Phase 2: Implementation Summary

The fix adds accessibility support to ToolbarItem on Android by:

1. Calling SetSemanticProperties(item, toolbar.FindViewById(menuitem.ItemId)) at the end of UpdateMenuItem
2. SetSemanticProperties reads SemanticProperties.Description and SemanticProperties.Hint via SemanticProperties.UpdateSemantics(menuItem, null)
3. If either is set: marks view ImportantForAccessibility.Yes and attaches a custom AccessibilityDelegateCompat
4. The delegate's OnInitializeAccessibilityNodeInfo sets ContentDescription and HintText on the node info
5. If no semantic info is present: clears any previously-set delegate

The implementation approach in ToolbarExtensions.cs is correct and follows proper Android accessibility patterns.

Device tests in ToolbarTests.Android.cs cover three scenarios:

• Description set → ContentDescription is set on node info
• Hint set → HintText is set on node info
• No semantics → no custom delegate attached

However, the test file has 3 compilation errors that block merge. See code-review.md for details.

---

Changes Required Before Merge

Priority	File	Issue
🔴 Critical	ToolbarTests.Android.cs:40	CS0234 — Missing using Android.Views; or alias
🔴 Critical	ToolbarTests.Android.cs:53	CS0618 — AccessibilityNodeInfoCompat.Recycle() deprecated
🔴 Critical	ToolbarTests.Android.cs:93	CS0618 — AccessibilityNodeInfoCompat.Recycle() deprecated
🟡 Suggestion	ToolbarExtensions.cs	Duplicate FindViewById call
🟡 Suggestion	ToolbarExtensions.cs	No PropertyChanged wiring for runtime updates

✨ Suggested PR Description

[!NOTE]
Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Root Cause

UpdateMenuItem in ToolbarExtensions.cs never propagated MAUI SemanticProperties (Description/Hint) to the native Android menu item view. Android TalkBack had no AccessibilityDelegateCompat to read from, so semantic metadata set via SemanticProperties.SetDescription() and SemanticProperties.SetHint() was silently ignored on ToolbarItem controls. The deprecated AutomationProperties.Name still worked because it takes a different code path.

Description of Change

Adds SetSemanticProperties method to ToolbarExtensions.cs, called at the end of UpdateMenuItem. The method:

1. Reads semantic properties via SemanticProperties.UpdateSemantics(menuItem, null)
2. If Description or Hint is set, marks the view as ImportantForAccessibility.Yes and attaches a custom AccessibilityDelegateCompat via ViewCompat.SetAccessibilityDelegate
3. The delegate's OnInitializeAccessibilityNodeInfo override sets ContentDescription (from Description) and HintText (from Hint) on the AccessibilityNodeInfoCompat
4. If no semantic info is present, any previously set delegate is cleared

Platform scope: Android only. iOS behavior (per issue #23623 which also reports iOS as affected) may need a separate fix in the iOS toolbar path.

Issues Fixed

Fixes #29573
Fixes #23623

Code Review: ⚠️ Issues Found

Code Review — PR #29596

🔴 Critical Issues (Block Merge)

1. CS0234 — Missing namespace for ImportantForAccessibility

File: src/Controls/tests/DeviceTests/Elements/Toolbar/ToolbarTests.Android.cs (line 40)

Problem: Uses Android.Views.ImportantForAccessibility.Yes without a using Android.Views; directive. In .NET 10, the compiler resolves the Android prefix as Microsoft.Android, causing:

CS0234: The type or namespace name 'Views' does not exist in the namespace 'Microsoft.Android'

Fix: Add a type alias at the top of the file, consistent with patterns used elsewhere in the codebase (e.g., ControlsHandlerTestBase.Android.cs:22):

using ImportantForAccessibility = Android.Views.ImportantForAccessibility;

Then at line 40:

Assert.Equal(ImportantForAccessibility.Yes, view.ImportantForAccessibility);

---

2. CS0618 — AccessibilityNodeInfoCompat.Recycle() is deprecated (×2)

File: src/Controls/tests/DeviceTests/Elements/Toolbar/ToolbarTests.Android.cs (lines 53, 93)

Problem: AccessibilityNodeInfoCompat.Recycle() is marked [Obsolete] in modern AndroidX. Calling it in finally blocks produces build errors (warnings-as-errors in CI):

CS0618: 'AccessibilityNodeInfoCompat.Recycle()' is obsolete

Fix: Remove both Recycle() calls; the object is GC-managed in modern AndroidX. Before:

var nodeInfo = AccessibilityNodeInfoCompat.Obtain();
try
{
    accessibilityDelegate.OnInitializeAccessibilityNodeInfo(view, nodeInfo);
    Assert.Equal("Save document", nodeInfo.ContentDescription);
}
finally
{
    nodeInfo.Recycle(); // ← Remove this
}

After:

var nodeInfo = AccessibilityNodeInfoCompat.Obtain();
accessibilityDelegate.OnInitializeAccessibilityNodeInfo(view, nodeInfo);
Assert.Equal("Save document", nodeInfo.ContentDescription);

---

🟡 Suggestions

3. Duplicate FindViewById call

File: src/Controls/src/Core/Platform/Android/Extensions/ToolbarExtensions.cs

toolbar.FindViewById(menuitem.ItemId) is called twice in UpdateMenuItem — once for the secondary toolbar text color tint check, and again when calling SetSemanticProperties. Consider caching the result to avoid the redundant view lookup:

var view = toolbar.FindViewById(menuitem.ItemId);
if (item.Order != ToolbarItemOrder.Secondary && !OperatingSystem.IsAndroidVersionAtLeast(26) && tintColor != null)
{
    if (view is ATextView textView)
    {
        // existing tint logic
    }
}
SetSemanticProperties(item, view);

4. No runtime property-change handling

File: src/Controls/src/Core/Platform/Android/Extensions/ToolbarExtensions.cs

SetSemanticProperties is only called during the initial UpdateMenuItem. If a user changes SemanticProperties.Description after the toolbar has been rendered, the accessibility delegate will not update. Consider whether this scenario needs to be handled via a PropertyChanged listener on ToolbarItem.

---

✅ Looks Good

• ViewCompat.SetAccessibilityDelegate (not the deprecated View.setAccessibilityDelegate) is used correctly
• base.OnInitializeAccessibilityNodeInfo(host, info) is preserved — default accessibility behavior is not lost
• null check for the view (if (view == null) return;) is properly handled
• Delegate is cleared when no semantic info is present (avoids stale data)
• ImportantForAccessibility.Yes correctly marks the view as accessibility-relevant
• Both Description → ContentDescription and Hint → HintText mappings are correct
• Three distinct test cases: Description-only, Hint-only, and no-semantics (no delegate)
• Issues VoiceOver on Toolbar Item #29573 and SemanticProperties do not work on ToolbarItems #23623 are both addressed
• Required NOTE block is present in the PR description

---

[kubaflo]

Code Review

🔴 Missing Tests

The commit message claims "Add Android device tests verifying..." but the PR contains only one file (ToolbarExtensions.cs). No test files are included — either they weren't pushed or the commit message is inaccurate.

🟡 Suggestions

1. Duplicate FindViewById call (lines 375 & 385)
Line 375 calls toolbar.FindViewById(menuitem.ItemId) inside a conditional, and line 385 calls it again unconditionally. When both conditions match, the same view is looked up twice. Consider hoisting:

var actionView = toolbar.FindViewById(menuitem.ItemId);
if (item.Order != ToolbarItemOrder.Secondary && ... && actionView is ATextView textView)
{ ... }
SetSemanticProperties(item, actionView);

2. Interaction with SetTitleOrContentDescription
SetTitleOrContentDescription (line 359) sets ContentDescription on the IMenuItem via the deprecated AutomationProperties.Name/HelpText. The new delegate sets ContentDescription on the view's accessibility node info via SemanticProperties.Description. If both are set, the delegate wins — probably correct (modern API takes precedence), but worth a code comment documenting this.

3. Overflow items silently ignored
Secondary (ToolbarItemOrder.Secondary) items live in the overflow popup and FindViewById returns null for them. The null guard handles this, but SemanticProperties will silently have no effect on overflow items. Worth a comment.

4. iOS still affected
Both #29573 and #23623 report iOS too. Fine to scope this PR to Android, but please note it in the description so a follow-up iOS fix isn't lost.

5. PR description missing "Description of Change"
Please add what the code does and why — e.g. that SetTitleOrContentDescription only reads the deprecated AutomationProperties and this bridges the modern SemanticProperties API to Android via AccessibilityDelegateCompat.

✅ What Looks Good

• AccessibilityDelegateCompat is the correct modern Android pattern, consistent with ControlsAccessibilityDelegate and ViewHandler.Android.cs.
• Correctly resets delegate to null when no semantic properties are set.
• Good null safety on view, host, and info.
• ImportantForAccessibility.Yes correctly ensures TalkBack visits the view.
• Uses SemanticProperties.UpdateSemantics consistently with the rest of the codebase.