[Proposal] Add support for fluently applying SemanticProperties

[bijington]

Add support for fluently applying SemanticProperties

• [x] Proposed
• [x] Prototype
• [x] Implementation
  • [x] iOS Support
  • [x] Android Support
  • [x] macOS Support
  • [x] Windows Support
• [ ] Unit Tests
• [ ] Sample
• [ ] Documentation

Link to Discussion

Summary

To make it easier for us all to build accessible applications when using the markup toolkit.

Motivation

To make it easier for us all to build accessible applications when using the markup toolkit.

Detailed Design

Propose that we add 2 sets of extension method classes:

SemanticExtensions

public static class SemanticExtensions
{
    public BindableObject SemanticDescription(this BindableObject bindableObject, string description)
    {
        SemanticProperties.SetDescription(bindableObject, description);
        return bindableObject;
    }

    public BindableObject SemanticHeadingLevel(this BindableObject bindableObject, SemanticHeadingLevel headingLevel)
    {
        SemanticProperties.SetHeadingLevel(bindableObject, headingLevel);
        return bindableObject;
    }

    public BindableObject SemanticHint(this BindableObject bindableObject, string hint)
    {
        SemanticProperties.SetHint(bindableObject, hint);
        return bindableObject;
    }
}

AutomationExtensions

I propose that we do not add all AutomationProperties as some have been superseded by the SemanticProperties above as detailed at: https://docs.microsoft.com/dotnet/maui/fundamentals/accessibility#automation-properties

AutomationProperties.Name -> SemanticProperties.Description

AutomationProperties.HelpText -> SemanticProperties.Hint

AutomationProperties.LabeledBy -> SemanticProperties.Description with a controls value e.g.

Content = 
    new VerticalStackLayout
    {
        Children = 
        {
            new Label().Text("Enter name:").Assign(out var label),

            new Entry().SemanticDescription(label.Text)
        }
    };

public static class AutomationExtensions
{
    public BindableObject AutomationExcludedWithChildren(this BindableObject bindableObject, bool? isExcludedWithChildren)
    {
        AutomationProperties.SetExcludedWithChildren(bindableObject, isExcludedWithChildren);
        return bindableObject;
    }

    public BindableObject AutomationIsInAccessibleTree(this BindableObject bindableObject, bool? isInAccessibleTree)
    {
        AutomationProperties.SetIsInAccessibleTree(bindableObject, isInAccessibleTree);
        return bindableObject;
    }
}

Usage Syntax

C# Usage

Content = new Image().SemanticHint("Like this post.");

Drawbacks

Alternatives

Unresolved Questions

Do we need to include the other AutomationProperties that have been superseded by SemanticProperties?