Implement SetSemanticFocus and Announce APIs (#1727)

* Add SemanticExtensions SetFocus and Announce

* Add Windows Announce implementation

* Update based on feedback

Co-authored-by: Brandon Minnick <13558917+brminnick@users.noreply.github.com>
Co-authored-by: Javier Suárez <javiersuarezruiz@hotmail.com>

Author: 3 people

samples/XCT.Sample/Pages/Extensions/SemanticExtensionsPage.xaml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<pages:BasePage x:Name="Page"
+                x:Class="Xamarin.CommunityToolkit.Sample.Pages.Effects.SemanticExtensionsPage"
+                xmlns="http://xamarin.com/schemas/2014/forms"
+                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+                xmlns:xct="http://xamarin.com/schemas/2020/toolkit"
+                xmlns:pages="clr-namespace:Xamarin.CommunityToolkit.Sample.Pages">
+
+    <StackLayout Margin="30" Spacing="30">
+        <Label
+            Text="Turn on your screen reader and listen for what is read aloud. Explore the SemanticExtensions below!"
+            TextColor="RoyalBlue"
+            FontAttributes="Bold"
+            FontSize="16"
+            Margin="0,10"/>
+
+        <Button
+            Text="Click to set semantic focus to label below"
+            FontSize="14"
+            Clicked="SetSemanticFocusButton_Clicked"/>
+
+        <Label
+            x:Name="semanticFocusLabel"
+            Text="Label receiving semantic focus"
+            FontSize="14"/>
+
+        <Button
+            Text="Activate to hear announcement text"
+            HorizontalOptions="Center"
+            Clicked="Announce_Clicked"/>
+    </StackLayout>
+
+</pages:BasePage>
+
+

samples/XCT.Sample/Pages/Extensions/SemanticExtensionsPage.xaml.cs

@@ -0,0 +1,23 @@
+using System;
+using Xamarin.CommunityToolkit.Extensions;
+
+namespace Xamarin.CommunityToolkit.Sample.Pages.Effects
+{
+	public partial class SemanticExtensionsPage
+	{
+		public SemanticExtensionsPage()
+		{
+			InitializeComponent();
+		}
+
+		void SetSemanticFocusButton_Clicked(object sender, System.EventArgs e)
+		{
+			SemanticExtensions.SetSemanticFocus(semanticFocusLabel);
+		}
+
+		void Announce_Clicked(object sender, EventArgs e)
+		{
+			SemanticExtensions.Announce("This is the announcement text");
+		}
+	}
+}

samples/XCT.Sample/ViewModels/Extensions/ExtensionsGalleryViewModel.cs

@@ -13,6 +13,11 @@ protected override IEnumerable<SectionModel> CreateItems() => new[]
 				typeof(ImageResourceExtensionPage),
 				nameof(ImageResourceExtension),
 				"A XAML extension that helps to display images from embedded resources"),
+
+			new SectionModel(
+				typeof(SemanticExtensionsPage),
+				nameof(SemanticExtensions),
+				"An extension that offers further semantic APIs for screen reader accessibility"),
 		};
 	}
 }

src/CommunityToolkit/Xamarin.CommunityToolkit/Extensions/Semantic/SemanticExtensions.android.cs

@@ -0,0 +1,39 @@
+using System;
+using Android.Views.Accessibility;
+using Xamarin.Forms;
+using Xamarin.Forms.Platform.Android;
+using AView = Android.Views.View;
+using AApplication = Android.App.Application;
+using AContext = Android.Content.Context;
+
+namespace Xamarin.CommunityToolkit.Extensions
+{
+	public static partial class SemanticExtensions
+	{
+		static void PlatformSetSemanticFocus(this VisualElement element)
+		{
+			var androidView = Platform.GetRenderer(element);
+
+			if (androidView is not AView view)
+				throw new NullReferenceException("Can't access view");
+
+			view.SendAccessibilityEvent(EventTypes.ViewFocused);
+		}
+
+		static void PlatformAnnounce(string text)
+		{
+			var manager = AApplication.Context.GetSystemService(AContext.AccessibilityService) as AccessibilityManager;
+			var announcement = AccessibilityEvent.Obtain();
+
+			if (manager == null || announcement == null)
+				return;
+
+			if (!(manager.IsEnabled || manager.IsTouchExplorationEnabled))
+				return;
+
+			announcement.EventType = EventTypes.Announcement;
+			announcement.Text?.Add(new Java.Lang.String(text));
+			manager.SendAccessibilityEvent(announcement);
+		}
+	}
+}

src/CommunityToolkit/Xamarin.CommunityToolkit/Extensions/Semantic/SemanticExtensions.ios.cs

@@ -0,0 +1,32 @@
+using System;
+using Foundation;
+using UIKit;
+using Xamarin.Forms;
+using Xamarin.Forms.Platform.iOS;
+
+namespace Xamarin.CommunityToolkit.Extensions
+{
+	public static partial class SemanticExtensions
+	{
+		static void PlatformSetSemanticFocus(this VisualElement element)
+		{
+			var iosView = Platform.GetRenderer(element);
+
+			if (iosView == null)
+				throw new NullReferenceException("Can't access view");
+
+			if (iosView is not NSObject nativeView)
+				return;
+
+			UIAccessibility.PostNotification(UIAccessibilityPostNotification.LayoutChanged, nativeView);
+		}
+
+		static void PlatformAnnounce(string text)
+		{
+			if (!UIAccessibility.IsVoiceOverRunning)
+				return;
+
+			UIAccessibility.PostNotification(UIAccessibilityPostNotification.Announcement, new NSString(text));
+		}
+	}
+}

src/CommunityToolkit/Xamarin.CommunityToolkit/Extensions/Semantic/SemanticExtensions.netstandard.macos.tvos.watchos.tizen.wpf.gtk.cs

@@ -0,0 +1,14 @@
+using System;
+using Xamarin.Forms;
+
+namespace Xamarin.CommunityToolkit.Extensions
+{
+	public static partial class SemanticExtensions
+	{
+		static void PlatformSetSemanticFocus(this VisualElement element) =>
+			throw new NotSupportedException($"The current platform '{Device.RuntimePlatform}' does not support Xamarin.CommunityToolkit.SemanticExtensions");
+
+		static void PlatformAnnounce(string text) =>
+			throw new NotSupportedException($"The current platform '{Device.RuntimePlatform}' does not support Xamarin.CommunityToolkit.SemanticExtensions");
+	}
+}

src/CommunityToolkit/Xamarin.CommunityToolkit/Extensions/Semantic/SemanticExtensions.shared.cs

@@ -0,0 +1,17 @@
+using Xamarin.Forms;
+
+namespace Xamarin.CommunityToolkit.Extensions
+{
+	public static partial class SemanticExtensions
+	{
+		/// <summary>
+		/// Force semantic screen reader focus to specified element
+		/// </summary>
+		/// <param name="element"></param>
+		public static void SetSemanticFocus(this VisualElement element) =>
+			PlatformSetSemanticFocus(element);
+
+		public static void Announce(string text) =>
+			PlatformAnnounce(text);
+	}
+}

src/CommunityToolkit/Xamarin.CommunityToolkit/Extensions/Semantic/SemanticExtensions.uwp.cs

@@ -0,0 +1,59 @@
+using System;
+using Xamarin.Forms;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Automation.Peers;
+using Windows.UI.Xaml.Media;
+
+namespace Xamarin.CommunityToolkit.Extensions
+{
+	public static partial class SemanticExtensions
+	{
+		internal const string ActivityId = "270FA098-C644-40A2-A0BE-A9BEA1222A1E";
+
+		static void PlatformSetSemanticFocus(this VisualElement element) =>
+			throw new NotSupportedException($"The current platform '{Device.RuntimePlatform}' does not support Xamarin.CommunityToolkit.SemanticExtensions");
+
+		static void PlatformAnnounce(string text)
+		{
+			if (Window.Current == null)
+				return;
+
+			var peer = FindAutomationPeer(Window.Current.Content);
+
+			// This GUID correlates to the internal messages used by UIA to perform an announce
+			// You can extract it  by using accessibility insights to monitor UIA events
+			// If you're curious how this works then do a google search for the GUID
+			peer?.RaiseNotificationEvent(
+				AutomationNotificationKind.ActionAborted,
+				AutomationNotificationProcessing.ImportantMostRecent,
+				text,
+				ActivityId);
+		}
+
+		// This isn't great but it's the only way I've found to announce with WinUI.
+		// You have to locate a control that has an automation peer and then use that 
+		// to perform the announce operation. This creates scenarios where the 
+		// screen might not have any automation peers on it to use but in those cases
+		// you really shouldn't be using the announce API
+		static AutomationPeer? FindAutomationPeer(DependencyObject depObj)
+		{
+			if (depObj == null)
+				return null;
+
+			var count = VisualTreeHelper.GetChildrenCount(depObj);
+			for (var i = 0; i < count; i++)
+			{
+				var child = VisualTreeHelper.GetChild(depObj, i);
+				if (child is UIElement element && FrameworkElementAutomationPeer.FromElement(element) != null)
+				{
+					return FrameworkElementAutomationPeer.FromElement(element);
+				}
+
+				var childItem = FindAutomationPeer(child);
+				if (childItem != null)
+					return childItem;
+			}
+			return null;
+		}
+	}
+}