Add MetadataControl

Microsoft.Toolkit.Uwp.SampleApp/Microsoft.Toolkit.Uwp.SampleApp.csproj

@@ -269,6 +269,7 @@
     <Content Include="Icons\Services.png" />
     <Content Include="SamplePages\Animations\Effects\FadeBehavior.png" />
     <Content Include="SamplePages\ColorPicker\ColorPicker.png" />
+    <Content Include="SamplePages\MetadataControl\MetadataControl.png" />
     <Content Include="SamplePages\TilesBrush\TilesBrush.png" />
     <Content Include="SamplePages\Eyedropper\Eyedropper.png" />
     <Content Include="SamplePages\OnDevice\OnDevice.png" />
@@ -497,6 +498,9 @@
     <Compile Include="SamplePages\FocusBehavior\FocusBehaviorPage.xaml.cs">
       <DependentUpon>FocusBehaviorPage.xaml</DependentUpon>
     </Compile>
+    <Compile Include="SamplePages\MetadataControl\MetadataControlPage.xaml.cs">
+      <DependentUpon>MetadataControlPage.xaml</DependentUpon>
+    </Compile>
     <Compile Include="SamplePages\TilesBrush\TilesBrushPage.xaml.cs">
       <DependentUpon>TilesBrushPage.xaml</DependentUpon>
     </Compile>
@@ -975,6 +979,14 @@
       <Generator>MSBuild:Compile</Generator>
       <SubType>Designer</SubType>
     </Page>
+    <Content Include="SamplePages\MetadataControl\MetadataControlCode.bind">
+      <SubType>Designer</SubType>
+      <Generator>MSBuild:Compile</Generator>
+    </Content>
+    <Page Include="SamplePages\MetadataControl\MetadataControlPage.xaml">
+      <SubType>Designer</SubType>
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
     <Page Include="SamplePages\TilesBrush\TilesBrushPage.xaml">
       <Generator>MSBuild:Compile</Generator>
       <SubType>Designer</SubType>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MetadataControl/MetadataControlCode.bind

@@ -0,0 +1,15 @@
+<Page
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d">
+
+  <StackPanel Padding="12">
+    <controls:MetadataControl
+      x:Name="metadataControl"
+      Separator="@[Separator:String: • ]"
+      AccessibleSeparator="@[AccessibleSeparator:String:, ]"/>
+  </StackPanel>
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MetadataControl/MetadataControlPage.xaml

@@ -0,0 +1,12 @@
+<Page x:Class="Microsoft.Toolkit.Uwp.SampleApp.SamplePages.MetadataControlPage"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      mc:Ignorable="d">
+
+    <StackPanel Padding="12">
+        <controls:MetadataControl x:Name="metadataControl" />
+    </StackPanel>
+</Page>

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MetadataControl/MetadataControlPage.xaml.cs

@@ -0,0 +1,83 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.ObjectModel;
+using Microsoft.Toolkit.Uwp.SampleApp.Common;
+using Microsoft.Toolkit.Uwp.UI.Controls;
+using Microsoft.Toolkit.Uwp.UI.Extensions;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+
+namespace Microsoft.Toolkit.Uwp.SampleApp.SamplePages
+{
+    /// <summary>
+    /// A page that shows how to use the MetadataControl
+    /// </summary>
+    public sealed partial class MetadataControlPage : Page, IXamlRenderListener
+    {
+        private static readonly string[] Labels = "Lorem ipsum dolor sit amet consectetur adipiscing elit".Split(" ");
+
+        private readonly Random _random;
+        private readonly ObservableCollection<MetadataUnit> _units;
+        private readonly DelegateCommand<object> _command;
+        private MetadataControl _metadataControl;
+
+        public MetadataControlPage()
+        {
+            _random = new Random();
+            _units = new ObservableCollection<MetadataUnit>();
+            _command = new DelegateCommand<object>(OnExecuteCommand);
+            InitializeComponent();
+            Setup();
+        }
+
+        public void OnXamlRendered(FrameworkElement control)
+        {
+            _metadataControl = control.FindChildByName("metadataControl") as MetadataControl;
+            if (_metadataControl != null)
+            {
+                _metadataControl.MetadataUnits = _units;
+            }
+        }
+
+        private void Setup()
+        {
+            SampleController.Current.RegisterNewCommand("Add label", (sender, args) =>
+            {
+                _units.Add(new MetadataUnit { Label = GetRandomLabel() });
+            });
+
+            SampleController.Current.RegisterNewCommand("Add command", (sender, args) =>
+            {
+                var label = GetRandomLabel();
+                _units.Add(new MetadataUnit
+                {
+                    Label = label,
+                    Command = _command,
+                    CommandParameter = label,
+                });
+            });
+
+            SampleController.Current.RegisterNewCommand("Clear", (sender, args) =>
+            {
+                _units.Clear();
+            });
+        }
+
+        private string GetRandomLabel() => Labels[_random.Next(Labels.Length)];
+
+        private async void OnExecuteCommand(object obj)
+        {
+            var dialog = new ContentDialog
+            {
+                Title = "Command invoked",
+                Content = $"Command parameter: {obj}",
+                CloseButtonText = "OK"
+            };
+
+            await dialog.ShowAsync();
+        }
+    }
+}

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/samples.json

@@ -136,6 +136,16 @@
         "Icon": "/SamplePages/RadialProgressBar/RadialProgressBar.png",
         "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/RadialProgressBar.md"
       },
+      {
+        "Name": "MetadataControl",
+        "Type": "MetadataControlPage",
+        "Subcategory": "Status and Info",
+        "About": "The control displays a list of metadata separated by bullets. The entries can either be strings or commands.",
+        "CodeUrl": "https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.UI.Controls/MetadataControl",
+        "XamlCodeFile": "MetadataControlCode.bind",
+        "Icon": "/SamplePages/MetadataControl/MetadataControl.png",
+        "DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/MetadataControl.md"
+      },
       {
         "Name": "RotatorTile",
         "Type": "RotatorTilePage",

Microsoft.Toolkit.Uwp.UI.Controls/MetadataControl/MetadataControl.cs

@@ -0,0 +1,194 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using System.Collections.Specialized;
+using System.Text;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Automation;
+using Windows.UI.Xaml.Automation.Peers;
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Documents;
+
+namespace Microsoft.Toolkit.Uwp.UI.Controls
+{
+    /// <summary>
+    /// Display <see cref="MetadataUnit"/>s separated by bullets.
+    /// </summary>
+    [TemplatePart(Name = TextContainerPart, Type = typeof(TextBlock))]
+    public sealed class MetadataControl : Control
+    {
+        /// <summary>
+        /// The DP to store the <see cref="Separator"/> property value.
+        /// </summary>
+        public static readonly DependencyProperty SeparatorProperty = DependencyProperty.Register(
+            nameof(Separator),
+            typeof(string),
+            typeof(MetadataControl),
+            new PropertyMetadata(" • ", OnPropertyChanged));
+
+        /// <summary>
+        /// The DP to store the <see cref="AccessibleSeparator"/> property value.
+        /// </summary>
+        public static readonly DependencyProperty AccessibleSeparatorProperty = DependencyProperty.Register(
+            nameof(AccessibleSeparator),
+            typeof(string),
+            typeof(MetadataControl),
+            new PropertyMetadata(", ", OnPropertyChanged));
+
+        /// <summary>
+        /// The DP to store the <see cref="MetadataUnits"/> property value.
+        /// </summary>
+        public static readonly DependencyProperty MetadataUnitsProperty = DependencyProperty.Register(
+            nameof(MetadataUnits),
+            typeof(IEnumerable<MetadataUnit>),
+            typeof(MetadataControl),
+            new PropertyMetadata(null, OnMetadataUnitsChanged));
+
+        private const string TextContainerPart = "TextContainer";
+
+        private TextBlock _textContainer;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MetadataControl"/> class.
+        /// </summary>
+        public MetadataControl()
+        {
+            DefaultStyleKey = typeof(MetadataControl);
+            ActualThemeChanged += OnActualThemeChanged;
+        }
+
+        /// <summary>
+        /// Gets or sets the separator to display between the <see cref="MetadataUnit"/>.
+        /// </summary>
+        public string Separator
+        {
+            get => (string)GetValue(SeparatorProperty);
+            set => SetValue(SeparatorProperty, value);
+        }
+
+        /// <summary>
+        /// Gets or sets the separator that will be used to generate the accessible string representing the control content.
+        /// </summary>
+        public string AccessibleSeparator
+        {
+            get => (string)GetValue(AccessibleSeparatorProperty);
+            set => SetValue(AccessibleSeparatorProperty, value);
+        }
+
+        /// <summary>
+        /// Gets or sets he <see cref="MetadataUnit"/> to display in the control.
+        /// If it implements <see cref="INotifyCollectionChanged"/>, the control will automatically update itself.
+        /// </summary>
+        public IEnumerable<MetadataUnit> MetadataUnits
+        {
+            get => (IEnumerable<MetadataUnit>)GetValue(MetadataUnitsProperty);
+            set => SetValue(MetadataUnitsProperty, value);
+        }
+
+        /// <inheritdoc/>
+        protected override void OnApplyTemplate()
+        {
+            _textContainer = GetTemplateChild(TextContainerPart) as TextBlock;
+            Update();
+        }
+
+        private static void OnMetadataUnitsChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            var control = (MetadataControl)d;
+            void OnCollectionChanged(object sender, NotifyCollectionChangedEventArgs args) => control.Update();
+
+            if (e.OldValue is INotifyCollectionChanged oldNcc)
+            {
+                oldNcc.CollectionChanged -= OnCollectionChanged;
+            }
+
+            if (e.NewValue is INotifyCollectionChanged newNcc)
+            {
+                newNcc.CollectionChanged += OnCollectionChanged;
+            }
+
+            control.Update();
+        }
+
+        private static void OnPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+            => ((MetadataControl)d).Update();
+
+        private void OnActualThemeChanged(FrameworkElement sender, object args) => Update();
+
+        private void Update()
+        {
+            if (_textContainer is null)
+            {
+                // The template is not ready yet.
+                return;
+            }
+
+            _textContainer.Inlines.Clear();
+
+            if (MetadataUnits is null)
+            {
+                AutomationProperties.SetName(_textContainer, string.Empty);
+                NotifyLiveRegionChanged();
+                return;
+            }
+
+            Inline unitToAppend;
+            var accessibleString = new StringBuilder();
+            foreach (var unit in MetadataUnits)
+            {
+                if (_textContainer.Inlines.Count > 0)
+                {
+                    _textContainer.Inlines.Add(new Run { Text = Separator });
+                    accessibleString.Append(AccessibleSeparator ?? Separator);
+                }
+
+                unitToAppend = new Run
+                {
+                    Text = unit.Label,
+                };
+
+                if (unit.Command != null)
+                {
+                    var hyperLink = new Hyperlink
+                    {
+                        UnderlineStyle = UnderlineStyle.None,
+                        Foreground = _textContainer.Foreground,
+                    };
+                    hyperLink.Inlines.Add(unitToAppend);
+
+                    void OnHyperlinkClicked(Hyperlink sender, HyperlinkClickEventArgs args)
+                    {
+                        if (unit.Command.CanExecute(unit.CommandParameter))
+                        {
+                            unit.Command.Execute(unit.CommandParameter);
+                        }
+                    }
+
+                    hyperLink.Click += OnHyperlinkClicked;
+
+                    unitToAppend = hyperLink;
+                }
+
+                var unitAccessibleLabel = unit.AccessibleLabel ?? unit.Label;
+                AutomationProperties.SetName(unitToAppend, unitAccessibleLabel);
+                accessibleString.Append(unitAccessibleLabel);
+
+                _textContainer.Inlines.Add(unitToAppend);
+            }
+
+            AutomationProperties.SetName(_textContainer, accessibleString.ToString());
+            NotifyLiveRegionChanged();
+        }
+
+        private void NotifyLiveRegionChanged()
+        {
+            if (AutomationPeer.ListenerExists(AutomationEvents.LiveRegionChanged))
+            {
+                var peer = FrameworkElementAutomationPeer.FromElement(this);
+                peer?.RaiseAutomationEvent(AutomationEvents.LiveRegionChanged);
+            }
+        }
+    }
+}

Microsoft.Toolkit.Uwp.UI.Controls/MetadataControl/MetadataControl.xaml

@@ -0,0 +1,15 @@
+<ResourceDictionary
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls">
+
+    <Style TargetType="controls:MetadataControl">
+        <Setter Property="Template">
+            <Setter.Value>
+                <ControlTemplate TargetType="controls:MetadataControl">
+                    <TextBlock x:Name="TextContainer" TextWrapping="Wrap" />
+                </ControlTemplate>
+            </Setter.Value>
+        </Setter>
+    </Style>
+</ResourceDictionary>