This is port of internal fix which adds Confirmation of Action featur…

…e to many actions in WinUI gallery (#1245)

Confirmation of Action is an accessibility feature where visual changes are notified to the impaired user using audio notification like Narrator. The common actions where it can be used when a visual is changing color or app theme is changing from light to dark or vice versa.

This PR introduces a AnnounceActionForAccessibility helper function which helps create this contextual announcement. This announcement is used by Narrator to inform the user that a large visual change has happened like scale/rotate of an object.
---------

Co-authored-by: Pratik Anand <praanan@microsoft.com>

WinUIGallery/ControlPages/ImplicitTransitionPage.xaml

@@ -12,15 +12,15 @@
             <Setter Property="TabNavigation" Value="Cycle"/>
         </Style>
     </Page.Resources>
-    <StackPanel>
+    <StackPanel Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
         <local:ControlExample HeaderText="Automatically animate changes to Opacity">
             <Rectangle x:Name="OpacityRectangle" Width="50" Height="50" Fill="{ThemeResource SystemAccentColor}" VerticalAlignment="Center" Margin="45,5,5,5" Opacity="0.5" />
 
             <local:ControlExample.Options>
                 <StackPanel>
                     <NumberBox x:Name="OpacityNumberBox" Header="Opacity (0.0 to 1.0)" 
                                     Value="0.5" Margin="5" Maximum="1" Minimum="0"  KeyDown="NumberBox_KeyDown"/>
-                    <Button Content="Set Opacity" Margin="5" Click="OpacityButton_Click" HorizontalAlignment="Stretch" />
+                    <Button x:Name="OpacityBtn" Content="Set Opacity" Margin="5" Click="OpacityButton_Click" HorizontalAlignment="Stretch" />
                 </StackPanel>
             </local:ControlExample.Options>
 
@@ -61,7 +61,7 @@ private void button_Click(object sender, RoutedEventArgs e)
                 <StackPanel>
                     <NumberBox x:Name="RotationNumberBox" Header="Rotation (0.0 to 360.0)" Value="45" Margin="5" 
                                     Minimum="0" Maximum="360"  KeyDown="NumberBox_KeyDown"/>
-                    <Button Content="Set Rotation" Margin="5" Click="RotationButton_Click" HorizontalAlignment="Stretch"/>
+                    <Button x:Name="RotateBtn"  Content="Set Rotation" Margin="5" Click="RotationButton_Click" HorizontalAlignment="Stretch"/>
                 </StackPanel>
             </local:ControlExample.Options>
 
@@ -102,7 +102,7 @@ private void button_Click(object sender, RoutedEventArgs e)
                     <CheckBox x:Name="ScaleZ" Content="Animate Z" IsChecked="True" />
                     <NumberBox x:Name="ScaleNumberBox" Header="Scale (0.0 to 5.0)" Value="1" 
                                     Minimum="0" Maximum="5" Margin="5" KeyDown="NumberBox_KeyDown" />
-                    <Button Content="Set custom scale" Click="ScaleButton_Click" Margin="5" HorizontalAlignment="Stretch" />
+                    <Button x:Name="ScaleBtn"  Content="Set custom scale" Click="ScaleButton_Click" Margin="5" HorizontalAlignment="Stretch" />
                 </StackPanel>
             </local:ControlExample.Options>
             <local:ControlExample.Xaml>
@@ -144,7 +144,7 @@ private void button_Click(object sender, RoutedEventArgs e)
                     <CheckBox x:Name="TranslateZ" Content="Animate Z" IsChecked="True" />
                     <NumberBox x:Name="TranslationNumberBox" Header="Translation (0.0 to 200.0)" Value="1"
                                     Minimum="0" Maximum="200" Margin="5" KeyDown="NumberBox_KeyDown" />
-                    <Button Content="Set custom Translation" Margin="5" Click="TranslateButton_Click" HorizontalAlignment="Stretch" />
+                    <Button x:Name="TranslateBtn" Content="Set custom Translation" Margin="5" Click="TranslateButton_Click" HorizontalAlignment="Stretch" />
                 </StackPanel>
             </local:ControlExample.Options>
             <local:ControlExample.Xaml>
@@ -174,7 +174,7 @@ private void button_Click(object sender, RoutedEventArgs e)
         <local:ControlExample HeaderText="Implicitly animate when the Background changes" >
             <ContentPresenter x:Name="BrushPresenter" Background="Blue" Width="50" Height="50" VerticalAlignment="Top" Margin="45,5,5,5" />
             <local:ControlExample.Options>
-                <Button Content="Change Background Color" Click="BackgroundButton_Click"  />
+                <Button x:Name="BgColorBtn" Content="Change Background Color" Click="BackgroundButton_Click"  />
             </local:ControlExample.Options>
             <local:ControlExample.Xaml>
                 <x:String xml:space="preserve">
@@ -220,7 +220,7 @@ private void button_Click(object sender, RoutedEventArgs e)
                 </StackPanel>
             </Grid>
             <local:ControlExample.Options>
-                <Button Content="Change Theme" Click="ThemeButton_Click" VerticalAlignment="Top"  />
+                <Button x:Name="ChangeThemeBtn" Content="Change Theme" Click="ThemeButton_Click" VerticalAlignment="Top"  />
             </local:ControlExample.Options>
             <local:ControlExample.Xaml>
                 <x:String xml:space="preserve">

WinUIGallery/ControlPages/ImplicitTransitionPage.xaml.cs

@@ -6,6 +6,7 @@
 using Microsoft.UI.Xaml.Input;
 using Microsoft.UI.Xaml.Media;
 using Microsoft.UI.Xaml.Controls.Primitives;
+using AppUIBasics.Helper;
 
 namespace AppUIBasics.ControlPages
 {
@@ -35,12 +36,16 @@ private void OpacityButton_Click(object sender, RoutedEventArgs e)
             var customValue = EnsureValueIsNumber(OpacityNumberBox);
             OpacityRectangle.Opacity = customValue;
             OpacityValue.Value = customValue;
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(OpacityBtn, $"Rectangle opacity changed by {OpacityValue.Value} points", "RectangleChangedNotificationActivityId");
         }
         private void RotationButton_Click(object sender, RoutedEventArgs e)
         {
             RotationRectangle.CenterPoint = new System.Numerics.Vector3((float)RotationRectangle.ActualWidth / 2, (float)RotationRectangle.ActualHeight / 2, 0f);
 
             RotationRectangle.Rotation = EnsureValueIsNumber(RotationNumberBox);
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(RotateBtn, $"Rectangle rotated by {RotationNumberBox.Value} degrees", "RectangleChangedNotificationActivityId");
         }
         private void ScaleButton_Click(object sender, RoutedEventArgs e)
         {
@@ -63,6 +68,8 @@ private void ScaleButton_Click(object sender, RoutedEventArgs e)
 
             ScaleRectangle.Scale = new Vector3(customValue);
             ScaleValue.Value = customValue;
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(ScaleBtn, $"Rectangle scaled by {ScaleValue.Value} points", "RectangleChangedNotificationActivityId");
         }
 
         private void TranslateButton_Click(object sender, RoutedEventArgs e)
@@ -85,6 +92,8 @@ private void TranslateButton_Click(object sender, RoutedEventArgs e)
 
             TranslateRectangle.Translation = new Vector3(customValue);
             TranslationValue.Value = customValue;
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(TranslateBtn, $"Rectangle translated by {TranslationValue.Value} points", "RectangleChangedNotificationActivityId");
         }
 
         private void NumberBox_KeyDown(object sender, KeyRoutedEventArgs e)
@@ -116,11 +125,16 @@ private void BackgroundButton_Click(object sender, RoutedEventArgs e)
             if ((BrushPresenter.Background as SolidColorBrush).Color == Microsoft.UI.Colors.Blue)
             {
                 BrushPresenter.Background = new SolidColorBrush(Microsoft.UI.Colors.Yellow);
+                // announce visual change to automation
+                UIHelper.AnnounceActionForAccessibility(BgColorBtn, "Rectangle color changed to Yellow", "RectangleChangedNotificationActivityId");
             }
             else
             {
                 BrushPresenter.Background = new SolidColorBrush(Microsoft.UI.Colors.Blue);
+                // announce visual change to automation
+                UIHelper.AnnounceActionForAccessibility(BgColorBtn, "Rectangle color changed to Blue", "RectangleChangedNotificationActivityId");
             }
+
         }
 
         private float EnsureValueIsNumber(NumberBox numberBox)
@@ -135,6 +149,8 @@ private float EnsureValueIsNumber(NumberBox numberBox)
         private void ThemeButton_Click(object sender, RoutedEventArgs e)
         {
             ThemeExampleGrid.RequestedTheme = ThemeExampleGrid.RequestedTheme == ElementTheme.Dark ? ElementTheme.Light : ElementTheme.Dark;
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(ChangeThemeBtn, $"UI local theme changed", "UILocalThemeChangedNotificationActivityId");
         }
     }
 }

WinUIGallery/ControlPages/ItemsRepeaterPage.xaml.cs

@@ -11,6 +11,7 @@
 using Microsoft.UI.Xaml.Controls;
 using Microsoft.UI.Xaml.Hosting;
 using Microsoft.UI.Xaml.Input;
+using AppUIBasics.Helper;
 
 namespace AppUIBasics.ControlPages
 {
@@ -284,7 +285,8 @@ private void OnAnimatedItemClicked(object sender, RoutedEventArgs e)
             // Update corresponding rectangle with selected color
             Button senderBtn = sender as Button;
             colorRectangle.Fill = senderBtn.Background;
-
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(sender as UIElement, $"Rectangle color set to {(sender as ContentControl).Content}", "RectangleChangedNotificationActivityId");
             SetUIANamesForSelectedEntry(senderBtn);
         }
 

WinUIGallery/ControlPages/TitleBarPage.xaml.cs

@@ -121,20 +121,24 @@ private void FgGridView_ItemClick(object sender, ItemClickEventArgs e)
         public void UpdateTitleBarColor()
         {
             var window = WindowHelper.GetWindowForElement(this);
-            var titleBarElement = WindowHelper.FindElementByName(this, "AppTitleBar");
+            var titleBarElement = UIHelper.FindElementByName(this, "AppTitleBar");
 
             (titleBarElement as Border).Background = new SolidColorBrush(currentBgColor); // changing titlebar uielement's color
             TitleBarHelper.SetCaptionButtonColors(window, currentFgColor);
         }
 
         private void customTitleBar_Click(object sender, RoutedEventArgs e)
         {
-            UIElement titleBarElement = WindowHelper.FindElementByName(sender as UIElement, "AppTitleBar");
+            UIElement titleBarElement = UIHelper.FindElementByName(sender as UIElement, "AppTitleBar");
             SetTitleBar(titleBarElement);
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(sender as UIElement, "TitleBar size and width changed", "TitleBarChangedNotificationActivityId");
         }
         private void defaultTitleBar_Click(object sender, RoutedEventArgs e)
         {
             SetTitleBar(null);
+            // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(sender as UIElement, "TitleBar size and width changed", "TitleBarChangedNotificationActivityId");
         }
     }
 }

WinUIGallery/Helper/TitleBarHelper.cs

@@ -15,6 +15,7 @@
 using Microsoft.UI.Xaml.Navigation;
 using WinRT;
 using System.Runtime.InteropServices;
+using AppUIBasics;
 
 namespace WinUIGallery.DesktopWap.Helper
 {
@@ -39,18 +40,21 @@ private static void triggerTitleBarRepaint(Window window)
 
         }
 
-        public static void ApplySystemThemeToCaptionButtons(Window window)
+        public static Windows.UI.Color ApplySystemThemeToCaptionButtons(Window window)
         {
             var res = Application.Current.Resources;
             var frame = (Application.Current as AppUIBasics.App).GetRootFrame() as FrameworkElement;
+            Windows.UI.Color color;
             if (frame.ActualTheme == ElementTheme.Dark)
             {
-                SetCaptionButtonColors(window, Colors.White);
+                color = Colors.White;
             }
             else
             {
-                SetCaptionButtonColors(window, Colors.Black);
+                color = Colors.Black;
             }
+            SetCaptionButtonColors(window,color);
+            return color;
         }
 
         public static void SetCaptionButtonColors(Window window, Windows.UI.Color color)

WinUIGallery/Helper/UIHelper.cs

@@ -1,6 +1,7 @@
 using System.Collections.Generic;
 using System.Linq;
 using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Automation.Peers;
 using Microsoft.UI.Xaml.Media;
 using Windows.Storage;
 
@@ -50,5 +51,26 @@ public static IEnumerable<DependencyObject> GetDescendants(this DependencyObject
                 }
             }
         }
+
+        static public UIElement FindElementByName(UIElement element, string name)
+        {
+            if (element.XamlRoot != null && element.XamlRoot.Content != null)
+            {
+                var ele = (element.XamlRoot.Content as FrameworkElement).FindName(name);
+                if (ele != null)
+                {
+                    return ele as UIElement;
+                }
+            }
+            return null;
+        }
+
+        // Confirmation of Action
+        static public void AnnounceActionForAccessibility(UIElement ue, string annoucement, string activityID)
+        {
+            var peer = FrameworkElementAutomationPeer.FromElement(ue);
+            peer.RaiseNotificationEvent(AutomationNotificationKind.ActionCompleted,
+                                        AutomationNotificationProcessing.ImportantMostRecent, annoucement, activityID);
+        }
     }
 }

WinUIGallery/Helper/WindowHelper.cs

@@ -61,19 +61,6 @@ static public Window GetWindowForElement(UIElement element)
             return null;
         }
 
-        static public UIElement FindElementByName(UIElement element, string name)
-        {
-            if (element.XamlRoot != null && element.XamlRoot.Content != null)
-            {
-                var ele = (element.XamlRoot.Content as FrameworkElement).FindName(name);
-                if (ele != null)
-                {
-                    return ele as UIElement;
-                }
-            }
-            return null;
-        }
-
         static public List<Window> ActiveWindows { get { return _activeWindows; }}
 
         static private List<Window> _activeWindows = new List<Window>();

WinUIGallery/Navigation/NavigationRootPage.xaml

@@ -41,6 +41,7 @@
 
         <Border
             x:Name="AppTitleBar"
+            AutomationProperties.AutomationId="AppTitleBar"
             Grid.Column="1"
             Height="{Binding ElementName=NavigationViewControl, Path=CompactPaneLength}"
             Margin="48,0,0,0"

WinUIGallery/Navigation/NavigationRootPage.xaml.cs

@@ -124,7 +124,7 @@ private void _settings_ColorValuesChanged(UISettings sender, object args)
             // This calls comes off-thread, hence we will need to dispatch it to current app's thread
             dispatcherQueue.TryEnqueue(() =>
             {
-                TitleBarHelper.ApplySystemThemeToCaptionButtons(App.StartupWindow);
+                _ = TitleBarHelper.ApplySystemThemeToCaptionButtons(App.StartupWindow);
             });
         }
 

WinUIGallery/SamplePages/SampleSystemBackdropsWindow.xaml.cs

@@ -6,6 +6,7 @@
 using System;
 using System.Runtime.InteropServices; // For DllImport
 using WinRT; // required to support Window.As<ICompositionSupportsSystemBackdrop>()
+using AppUIBasics.Helper;
 
 namespace AppUIBasics.SamplePages
 {
@@ -145,6 +146,8 @@ public void SetBackdrop(BackdropType type)
                     tbChangeStatus.Text += "  Acrylic isn't supported. Switching to default color.";
                 }
             }
+             // announce visual change to automation
+            UIHelper.AnnounceActionForAccessibility(btnChangeBackdrop, $"Background changed to {tbCurrentBackdrop.Text}", "BackgroundChangedNotificationActivityId");
         }
 
         bool TrySetMicaBackdrop(bool useMicaAlt)

WinUIGallery/SettingsPage.xaml

@@ -65,7 +65,7 @@
                     <labs:SettingsCard.HeaderIcon>
                         <FontIcon Glyph="&#xE790;" />
                     </labs:SettingsCard.HeaderIcon>
-                    <ComboBox x:Name="themeMode" SelectionChanged="themeMode_SelectionChanged">
+                    <ComboBox x:Name="themeMode" AutomationProperties.AutomationId="themeModeComboBox" SelectionChanged="themeMode_SelectionChanged">
                         <ComboBoxItem Content="Light" Tag="Light" />
                         <ComboBoxItem Content="Dark" Tag="Dark" />
                         <ComboBoxItem Content="Use system setting" Tag="Default" />

WinUIGallery/SettingsPage.xaml.cs

@@ -95,23 +95,28 @@ private void OnSettingsPageLoaded(object sender, RoutedEventArgs e)
         private void themeMode_SelectionChanged(object sender, RoutedEventArgs e)
         {
             var selectedTheme = ((ComboBoxItem)themeMode.SelectedItem)?.Tag?.ToString();
-            var window = WindowHelper.GetWindowForElement(this);
-
+            var window = WindowHelper.GetWindowForElement(this);
+            string color;
             if (selectedTheme != null)
             {
                 ThemeHelper.RootTheme = App.GetEnum<ElementTheme>(selectedTheme);
                 if (selectedTheme == "Dark")
                 {
                     TitleBarHelper.SetCaptionButtonColors(window, Colors.White);
+                    color = selectedTheme;
                 }
                 else if (selectedTheme == "Light")
                 {
                     TitleBarHelper.SetCaptionButtonColors(window, Colors.Black);
+                    color = selectedTheme;
                 }
                 else
-                {
-                    TitleBarHelper.ApplySystemThemeToCaptionButtons(window);
+                {
+                    color = TitleBarHelper.ApplySystemThemeToCaptionButtons(window) == Colors.White  ? "Dark" : "Light";
                 }
+                // announce visual change to automation
+                UIHelper.AnnounceActionForAccessibility(sender as UIElement, $"Theme changed to {color}",
+                                                                                "ThemeChangedNotificationActivityId");
             }
         }