Skip to content

Commit ff21a8a

Browse files
author
msftbot[bot]
authored
Add MetadataControl (#3686)
<!-- 🚨 Please Do Not skip any instructions and information mentioned below as they are all required and essential to evaluate and test the PR. By fulfilling all the required information you will be able to reduce the volume of questions and most likely help merge the PR faster 🚨 --> <!-- 📝 It is preferred if you keep the "☑️ Allow edits by maintainers" checked in the Pull Request Template as it increases collaboration with the Toolkit maintainers by permitting commits to your PR branch (only) created from your fork. This can let us quickly make fixes for minor typos or forgotten StyleCop issues during review without needing to wait on you doing extra work. Let us help you help us! 🎉 --> ## Fixes #3688 <!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes #1234) which will automatically close the issue once the PR is merged. --> Adds a control to display metadata separated by bullets like done in Groove Music or the Store. The metadata list can contain actionable links. **Groove** ![groove](https://user-images.githubusercontent.com/20152272/105519998-66aa6100-5cda-11eb-891a-4598ad5becf4.png) **Store** ![store](https://user-images.githubusercontent.com/20152272/105520090-817cd580-5cda-11eb-8bf1-36afbc2fe435.png) ## PR Type What kind of change does this PR introduce? - Feature ## What is the new behavior? I've added `MetadataControl`. It aggregates strings and commands separated by bullets ("•" / U+2022) in a `TextBlock`. The commands are represented using `Hyperlink` items. It receives the items to display as `MetadataUnit`s through its `MetadataControl.MetadataUnits` property. ## PR Checklist Please check if your PR fulfills the following requirements: - [x] Tested code with current [supported SDKs](../readme.md#supported) - [ ] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link --> - [x] Sample in sample app has been added / updated (for bug fixes / features) - [x] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets) - [ ] New major technical changes in the toolkit have or will be added to the [Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) e.g. build changes, source generators, testing infrastructure, sample creation changes, etc... - [ ] Tests for the changes have been added (for bug fixes / features) (if applicable) - [x] Header has been added to all new source files (run *build/UpdateHeaders.bat*) - [x] Contains **NO** breaking changes <!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. Please note that breaking changes are likely to be rejected within minor release cycles or held until major versions. --> ## Other information ![image](https://user-images.githubusercontent.com/20152272/105520377-f0f2c500-5cda-11eb-9116-8447969d1cdd.png)
2 parents 6c63d55 + e6d3c3b commit ff21a8a

File tree

10 files changed

+396
-0
lines changed

10 files changed

+396
-0
lines changed

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,7 @@
281281
<Content Include="SamplePages\TabbedCommandBar\TabbedCommandBar.png" />
282282
<Content Include="SamplePages\Animations\Effects\FadeBehavior.png" />
283283
<Content Include="SamplePages\ColorPicker\ColorPicker.png" />
284+
<Content Include="SamplePages\MetadataControl\MetadataControl.png" />
284285
<Content Include="SamplePages\TilesBrush\TilesBrush.png" />
285286
<Content Include="SamplePages\Eyedropper\Eyedropper.png" />
286287
<Content Include="SamplePages\OnDevice\OnDevice.png" />
@@ -506,6 +507,9 @@
506507
<Compile Include="SamplePages\FocusBehavior\FocusBehaviorPage.xaml.cs">
507508
<DependentUpon>FocusBehaviorPage.xaml</DependentUpon>
508509
</Compile>
510+
<Compile Include="SamplePages\MetadataControl\MetadataControlPage.xaml.cs">
511+
<DependentUpon>MetadataControlPage.xaml</DependentUpon>
512+
</Compile>
509513
<Compile Include="SamplePages\TilesBrush\TilesBrushPage.xaml.cs">
510514
<DependentUpon>TilesBrushPage.xaml</DependentUpon>
511515
</Compile>
@@ -966,6 +970,13 @@
966970
<Content Include="SamplePages\TabbedCommandBar\TabbedCommandBar.bind">
967971
<SubType>Designer</SubType>
968972
</Content>
973+
<Content Include="SamplePages\MetadataControl\MetadataControlCode.bind">
974+
<SubType>Designer</SubType>
975+
</Content>
976+
<Page Include="SamplePages\MetadataControl\MetadataControlPage.xaml">
977+
<SubType>Designer</SubType>
978+
<Generator>MSBuild:Compile</Generator>
979+
</Page>
969980
<Page Include="SamplePages\CanvasPathGeometry\CanvasPathGeometryPage.xaml">
970981
<SubType>Designer</SubType>
971982
<Generator>MSBuild:Compile</Generator>

‎Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MetadataControl/MetadataControl.png‎

883 Bytes
Loading

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<Page
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
5+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
6+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
7+
mc:Ignorable="d">
8+
9+
<StackPanel Padding="12">
10+
<controls:MetadataControl
11+
x:Name="metadataControl"
12+
Separator="@[Separator:String: • ]"
13+
AccessibleSeparator="@[AccessibleSeparator:String:, ]"/>
14+
</StackPanel>
15+
</Page>

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<Page x:Class="Microsoft.Toolkit.Uwp.SampleApp.SamplePages.MetadataControlPage"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
5+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
6+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
7+
mc:Ignorable="d">
8+
9+
<StackPanel Padding="12">
10+
<controls:MetadataControl x:Name="metadataControl" />
11+
</StackPanel>
12+
</Page>

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
using System;
6+
using System.Collections.ObjectModel;
7+
using Microsoft.Toolkit.Uwp.SampleApp.Common;
8+
using Microsoft.Toolkit.Uwp.UI;
9+
using Microsoft.Toolkit.Uwp.UI.Controls;
10+
using Windows.UI.Xaml;
11+
using Windows.UI.Xaml.Controls;
12+
13+
namespace Microsoft.Toolkit.Uwp.SampleApp.SamplePages
14+
{
15+
/// <summary>
16+
/// A page that shows how to use the MetadataControl
17+
/// </summary>
18+
public sealed partial class MetadataControlPage : Page, IXamlRenderListener
19+
{
20+
private static readonly string[] Labels = "Lorem ipsum dolor sit amet consectetur adipiscing elit".Split(" ");
21+
22+
private readonly Random _random;
23+
private readonly ObservableCollection<MetadataItem> _units;
24+
private readonly DelegateCommand<object> _command;
25+
private MetadataControl _metadataControl;
26+
27+
public MetadataControlPage()
28+
{
29+
_random = new Random();
30+
_units = new ObservableCollection<MetadataItem>();
31+
_command = new DelegateCommand<object>(OnExecuteCommand);
32+
InitializeComponent();
33+
Setup();
34+
}
35+
36+
public void OnXamlRendered(FrameworkElement control)
37+
{
38+
_metadataControl = control.FindChild("metadataControl") as MetadataControl;
39+
if (_metadataControl != null)
40+
{
41+
_metadataControl.Items = _units;
42+
}
43+
}
44+
45+
private void Setup()
46+
{
47+
SampleController.Current.RegisterNewCommand("Add label", (sender, args) =>
48+
{
49+
_units.Add(new MetadataItem { Label = GetRandomLabel() });
50+
});
51+
52+
SampleController.Current.RegisterNewCommand("Add command", (sender, args) =>
53+
{
54+
var label = GetRandomLabel();
55+
_units.Add(new MetadataItem
56+
{
57+
Label = label,
58+
Command = _command,
59+
CommandParameter = label,
60+
});
61+
});
62+
63+
SampleController.Current.RegisterNewCommand("Clear", (sender, args) =>
64+
{
65+
_units.Clear();
66+
});
67+
}
68+
69+
private string GetRandomLabel() => Labels[_random.Next(Labels.Length)];
70+
71+
private async void OnExecuteCommand(object obj)
72+
{
73+
var dialog = new ContentDialog
74+
{
75+
Title = "Command invoked",
76+
Content = $"Command parameter: {obj}",
77+
CloseButtonText = "OK"
78+
};
79+
80+
await dialog.ShowAsync();
81+
}
82+
}
83+
}

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,16 @@
133133
"Icon": "/SamplePages/RadialProgressBar/RadialProgressBar.png",
134134
"DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/RadialProgressBar.md"
135135
},
136+
{
137+
"Name": "MetadataControl",
138+
"Type": "MetadataControlPage",
139+
"Subcategory": "Status and Info",
140+
"About": "The control displays a list of metadata separated by bullets. The entries can either be strings or commands.",
141+
"CodeUrl": "https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.UI.Controls/MetadataControl",
142+
"XamlCodeFile": "MetadataControlCode.bind",
143+
"Icon": "/SamplePages/MetadataControl/MetadataControl.png",
144+
"DocumentationUrl": "https://raw.githubusercontent.com/MicrosoftDocs/WindowsCommunityToolkitDocs/master/docs/controls/MetadataControl.md"
145+
},
136146
{
137147
"Name": "RotatorTile",
138148
"Type": "RotatorTilePage",

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

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
using System.Collections.Generic;
6+
using System.Collections.Specialized;
7+
using System.Text;
8+
using Windows.UI.Xaml;
9+
using Windows.UI.Xaml.Automation;
10+
using Windows.UI.Xaml.Automation.Peers;
11+
using Windows.UI.Xaml.Controls;
12+
using Windows.UI.Xaml.Documents;
13+
14+
namespace Microsoft.Toolkit.Uwp.UI.Controls
15+
{
16+
/// <summary>
17+
/// Display <see cref="MetadataItem"/>s separated by bullets.
18+
/// </summary>
19+
[TemplatePart(Name = TextContainerPart, Type = typeof(TextBlock))]
20+
public sealed class MetadataControl : Control
21+
{
22+
/// <summary>
23+
/// The DP to store the <see cref="Separator"/> property value.
24+
/// </summary>
25+
public static readonly DependencyProperty SeparatorProperty = DependencyProperty.Register(
26+
nameof(Separator),
27+
typeof(string),
28+
typeof(MetadataControl),
29+
new PropertyMetadata(" • ", OnPropertyChanged));
30+
31+
/// <summary>
32+
/// The DP to store the <see cref="AccessibleSeparator"/> property value.
33+
/// </summary>
34+
public static readonly DependencyProperty AccessibleSeparatorProperty = DependencyProperty.Register(
35+
nameof(AccessibleSeparator),
36+
typeof(string),
37+
typeof(MetadataControl),
38+
new PropertyMetadata(", ", OnPropertyChanged));
39+
40+
/// <summary>
41+
/// The DP to store the <see cref="Items"/> property value.
42+
/// </summary>
43+
public static readonly DependencyProperty ItemsProperty = DependencyProperty.Register(
44+
nameof(Items),
45+
typeof(IEnumerable<MetadataItem>),
46+
typeof(MetadataControl),
47+
new PropertyMetadata(null, OnMetadataItemsChanged));
48+
49+
/// <summary>
50+
/// The DP to store the TextBlockStyle value.
51+
/// </summary>
52+
public static readonly DependencyProperty TextBlockStyleProperty = DependencyProperty.Register(
53+
nameof(TextBlockStyle),
54+
typeof(Style),
55+
typeof(MetadataControl),
56+
new PropertyMetadata(null));
57+
58+
private const string TextContainerPart = "TextContainer";
59+
60+
private TextBlock _textContainer;
61+
62+
/// <summary>
63+
/// Initializes a new instance of the <see cref="MetadataControl"/> class.
64+
/// </summary>
65+
public MetadataControl()
66+
{
67+
DefaultStyleKey = typeof(MetadataControl);
68+
ActualThemeChanged += OnActualThemeChanged;
69+
}
70+
71+
/// <summary>
72+
/// Gets or sets the separator to display between the <see cref="MetadataItem"/>.
73+
/// </summary>
74+
public string Separator
75+
{
76+
get => (string)GetValue(SeparatorProperty);
77+
set => SetValue(SeparatorProperty, value);
78+
}
79+
80+
/// <summary>
81+
/// Gets or sets the separator that will be used to generate the accessible string representing the control content.
82+
/// </summary>
83+
public string AccessibleSeparator
84+
{
85+
get => (string)GetValue(AccessibleSeparatorProperty);
86+
set => SetValue(AccessibleSeparatorProperty, value);
87+
}
88+
89+
/// <summary>
90+
/// Gets or sets the <see cref="MetadataItem"/> to display in the control.
91+
/// If it implements <see cref="INotifyCollectionChanged"/>, the control will automatically update itself.
92+
/// </summary>
93+
public IEnumerable<MetadataItem> Items
94+
{
95+
get => (IEnumerable<MetadataItem>)GetValue(ItemsProperty);
96+
set => SetValue(ItemsProperty, value);
97+
}
98+
99+
/// <summary>
100+
/// Gets or sets the <see cref="Style"/> to use on the inner <see cref="TextBlock"/> control.
101+
/// </summary>
102+
public Style TextBlockStyle
103+
{
104+
get => (Style)GetValue(TextBlockStyleProperty);
105+
set => SetValue(TextBlockStyleProperty, value);
106+
}
107+
108+
/// <inheritdoc/>
109+
protected override void OnApplyTemplate()
110+
{
111+
_textContainer = GetTemplateChild(TextContainerPart) as TextBlock;
112+
Update();
113+
}
114+
115+
private static void OnMetadataItemsChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
116+
{
117+
var control = (MetadataControl)d;
118+
void OnCollectionChanged(object sender, NotifyCollectionChangedEventArgs args) => control.Update();
119+
120+
if (e.OldValue is INotifyCollectionChanged oldNcc)
121+
{
122+
oldNcc.CollectionChanged -= OnCollectionChanged;
123+
}
124+
125+
if (e.NewValue is INotifyCollectionChanged newNcc)
126+
{
127+
newNcc.CollectionChanged += OnCollectionChanged;
128+
}
129+
130+
control.Update();
131+
}
132+
133+
private static void OnPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
134+
=> ((MetadataControl)d).Update();
135+
136+
private void OnActualThemeChanged(FrameworkElement sender, object args) => Update();
137+
138+
private void Update()
139+
{
140+
if (_textContainer is null)
141+
{
142+
// The template is not ready yet.
143+
return;
144+
}
145+
146+
_textContainer.Inlines.Clear();
147+
148+
if (Items is null)
149+
{
150+
AutomationProperties.SetName(_textContainer, string.Empty);
151+
NotifyLiveRegionChanged();
152+
return;
153+
}
154+
155+
Inline unitToAppend;
156+
var accessibleString = new StringBuilder();
157+
foreach (var unit in Items)
158+
{
159+
if (_textContainer.Inlines.Count > 0)
160+
{
161+
_textContainer.Inlines.Add(new Run { Text = Separator });
162+
accessibleString.Append(AccessibleSeparator ?? Separator);
163+
}
164+
165+
unitToAppend = new Run
166+
{
167+
Text = unit.Label,
168+
};
169+
170+
if (unit.Command != null)
171+
{
172+
var hyperLink = new Hyperlink
173+
{
174+
UnderlineStyle = UnderlineStyle.None,
175+
Foreground = _textContainer.Foreground,
176+
};
177+
hyperLink.Inlines.Add(unitToAppend);
178+
179+
void OnHyperlinkClicked(Hyperlink sender, HyperlinkClickEventArgs args)
180+
{
181+
if (unit.Command.CanExecute(unit.CommandParameter))
182+
{
183+
unit.Command.Execute(unit.CommandParameter);
184+
}
185+
}
186+
187+
hyperLink.Click += OnHyperlinkClicked;
188+
189+
unitToAppend = hyperLink;
190+
}
191+
192+
var unitAccessibleLabel = unit.AccessibleLabel ?? unit.Label;
193+
AutomationProperties.SetName(unitToAppend, unitAccessibleLabel);
194+
accessibleString.Append(unitAccessibleLabel);
195+
196+
_textContainer.Inlines.Add(unitToAppend);
197+
}
198+
199+
AutomationProperties.SetName(_textContainer, accessibleString.ToString());
200+
NotifyLiveRegionChanged();
201+
}
202+
203+
private void NotifyLiveRegionChanged()
204+
{
205+
if (AutomationPeer.ListenerExists(AutomationEvents.LiveRegionChanged))
206+
{
207+
var peer = FrameworkElementAutomationPeer.FromElement(this);
208+
peer?.RaiseAutomationEvent(AutomationEvents.LiveRegionChanged);
209+
}
210+
}
211+
}
212+
}

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
2+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
3+
xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls">
4+
5+
<Style TargetType="controls:MetadataControl">
6+
<Setter Property="Template">
7+
<Setter.Value>
8+
<ControlTemplate TargetType="controls:MetadataControl">
9+
<TextBlock x:Name="TextContainer"
10+
Style="{TemplateBinding TextBlockStyle}" />
11+
</ControlTemplate>
12+
</Setter.Value>
13+
</Setter>
14+
</Style>
15+
</ResourceDictionary>

0 commit comments

Comments
 (0)