Skip to content

Added LandmarkType to automation properties#20134

Merged
MrJul merged 4 commits intoAvaloniaUI:masterfrom
codecat:feature/automation-landmark
Nov 26, 2025
Merged

Added LandmarkType to automation properties#20134
MrJul merged 4 commits intoAvaloniaUI:masterfrom
codecat:feature/automation-landmark

Conversation

@codecat
Copy link
Contributor

@codecat codecat commented Nov 24, 2025 •
edited
Loading

What does the pull request do?

This implements LandmarkType in AutomationProperties, and can be used to indicate big "landmark" points within the app that the user can navigate between quickly.

What is the updated/expected behavior with this PR?

Add AutomationProperty.LandmarkType="Main" to some main content. This element will now get the Main landmark type on Windows UIA and Mac AX.

Something that I haven't quite figured out yet is how Mac VoiceOver finds landmarks. It's not able to navigate between or find the landmarks (despite having the properties set correctly). I'll investigate a bit more, but this PR should at least be a good first step.

How was the solution implemented (if it's not obvious)?

I implemented this as an enum, because implementation is not straight forward between Windows and Mac. To be precise:

UIA LandmarkType Mac AXSubrole Mac AXRoleDescription Avalonia
Custom: "banner" AXLandmarkBanner banner Banner
Custom: "complementary" AXLandmarkComplementary complementary Complementary
Custom: "content information" AXLandmarkContentInfo content ContentInfo
Custom: "region" AXLandmarkRegion region Region
Form AXLandmarkForm form Form
Main AXLandmarkMain main Main
Navigation AXLandmarkNavigation navigation Navigation
Search AXLandmarkSearch search Search

This follows the mapping role table from w3c.

Checklist

Fixed issues

@MrJul MrJul added feature area-accessibility needs-api-review The PR adds new public APIs that should be reviewed. labels Nov 24, 2025
@avaloniaui-bot
Copy link

avaloniaui-bot commented Nov 24, 2025

You can test this PR using the following package version. 12.0.999-cibuild0060315-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

@MrJul MrJul added api-approved The new public APIs have been approved. and removed needs-api-review The PR adds new public APIs that should be reviewed. labels Nov 26, 2025
@MrJul
Copy link
Member

MrJul commented Nov 26, 2025

Notes from the API review meeting: the changes are accepted as proposed.

@codecat
Set AutomationProperties.AccessibilityView on Main landmark in Integr…
20f1ecf 
…ationTestApp, which is required for Narrator to find the landmark
@avaloniaui-bot
Copy link

avaloniaui-bot commented Nov 26, 2025

You can test this PR using the following package version. 12.0.999-cibuild0060357-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

@codecat
Copy link
Contributor Author

codecat commented Nov 26, 2025 •
edited
Loading

I found that AccessibilityView must be set to at least Control for Windows Narrator to see the landmark in the landmark list, as well as shortcuts like Narrator+N (navigate to Main) to work. So this works perfectly on Windows now.

Still having trouble getting VoiceOver to detect landmarks though; they're not showing up in the VoiceOver rotor, even with AccessibilityView set or with the suggested AXRoleDescription by w3c. I also tried forcing AXRole to AXGroup for any elements that have a landmark set, and that didn't do anything special either. Any further advice I can try with this is welcome.

Nevertheless, I'm happy for this to be reviewed now. 👍

First message in the PR has been updated to match the latest fix commits.

@avaloniaui-bot
Copy link

avaloniaui-bot commented Nov 26, 2025

You can test this PR using the following package version. 12.0.999-cibuild0060361-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

MrJul
MrJul approved these changes Nov 26, 2025
View reviewed changes
Copy link
Member

@MrJul MrJul left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thank you!

@MrJul MrJul added this pull request to the merge queue Nov 26, 2025
Merged via the queue into AvaloniaUI:master with commit d281720 Nov 26, 2025
11 checks passed
@codecat codecat deleted the feature/automation-landmark branch November 26, 2025 18:46
@codecat
Copy link
Contributor Author

codecat commented Dec 31, 2025

@MrJul Could this potentially be backported to 11.x? Is there anything I can do to help with that process?

@codecat
Copy link
Contributor Author

codecat commented Jan 28, 2026

@MrJul Apologies for the additional ping about this PR (I'll refrain from pinging again).

Is there any possibility this can still be backported to 11.3.x? This isn't a breaking change as far as I'm concerned. I'd be happy to help in any way I can to make this happen if needed, as this is quite important for our app to have.

@MrJul MrJul added the backport-candidate-11.3.x Consider this PR for backporting to 11.3 branch label Jan 28, 2026
@MrJul
Copy link
Member

MrJul commented Jan 28, 2026 •
edited
Loading

@MrJul Apologies for the additional ping about this PR (I'll refrain from pinging again).

No worries, I somehow completely missed the first one, sorry about that!

Is there any possibility this can still be backported to 11.3.x? This isn't a breaking change as far as I'm concerned. I'd be happy to help in any way I can to make this happen if needed, as this is quite important for our app to have.

Yes, this can definitely be backported. This is a nice self-contained enhancement; there should be no issue.

MrJul pushed a commit that referenced this pull request Feb 12, 2026
@codecat @MrJul
Added LandmarkType to automation properties (#20134)
4094bae 
* Added LandmarkType to automation properties

* Set AutomationProperties.AccessibilityView on Main landmark in IntegrationTestApp, which is required for Narrator to find the landmark

* Implement AXRoleDescription as suggested by W3C

* Fixed wrong role descriptions
@MrJul MrJul added backported-11.3.x and removed backport-candidate-11.3.x Consider this PR for backporting to 11.3 branch labels Feb 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@MrJul MrJul MrJul approved these changes

Assignees

No one assigned

Labels

api-approved The new public APIs have been approved. area-accessibility backported-11.3.x feature

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@codecat @avaloniaui-bot @MrJul