Skip to content

Commit 1a0fa2b

Browse files
jwmsftjwmsft
authored
Add new article for SelectorBar (#4185)
* add new SelectorBar doc * add selector bar to toc * update links to selector bar * some minor updates to wording, metadata
1 parent eb3814d commit 1a0fa2b

File tree

4 files changed

+249
-2
lines changed

4 files changed

+249
-2
lines changed

‎hub/apps/design/controls/images/selector-bar.png

2.44 KB
Loading

‎hub/apps/design/controls/pivot.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The Pivot control enables touch-swiping between a small set of content sections.
1919
> [!WARNING]
2020
>The Pivot control is not recommended for [Windows 11 design patterns](../basics/app-silhouette.md). We strongly recommend using one of these alternatives instead:
2121
>
22-
> - **WinUI 3** - Use the [SelectorBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar) control.
22+
> - **WinUI 3** - Use the [SelectorBar](selector-bar.md) control.
2323
> - **WinUI 2/UWP** - Use a [NavigationView](navigationview.md) or [TabView](tab-view.md) control instead of a Pivot control. See the [Use NavigationView instead of Pivot](#use-navigationview-instead-of-pivot) section for an example.
2424
2525
To create a Pivot-like UI when using WinUI 3 and the Windows App SDK, use the [SelectorBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar) control.
@@ -113,7 +113,7 @@ This code mimics the Pivot control's built-in navigation experience, minus the t
113113
> [!WARNING]
114114
>The Pivot control is not recommended for [Windows 11 design patterns](../basics/app-silhouette.md). We strongly recommend using one of these alternatives instead:
115115
>
116-
> - **WinUI 3** - Use the [SelectorBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar) control.
116+
> - **WinUI 3** - Use the [SelectorBar](selector-bar.md) control.
117117
> - **WinUI 2/UWP** - Use a [NavigationView](navigationview.md) or [TabView](tab-view.md) control instead of a Pivot control. See the [Use NavigationView instead of Pivot](#use-navigationview-instead-of-pivot) section for an example.
118118
119119
This XAML creates a basic Pivot control with 3 sections of content.
@@ -191,4 +191,7 @@ The control comes in two modes:
191191
## Related topics
192192

193193
- [Pivot class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.pivot)
194+
- [SelectorBar](selector-bar.md)
195+
- [NavigationView](navigationview.md)
196+
- [TabView](tab-view.md)
194197
- [Navigation design basics](../basics/navigation-basics.md)

‎hub/apps/design/controls/selector-bar.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
description: The SelectorBar control enables switching between a small set of content sections.
3+
title: SelectorBar
4+
template: detail.hbs
5+
ms.date: 03/29/2024
6+
ms.topic: article
7+
doc-status: Published
8+
ms.localizationpriority: medium
9+
---
10+
11+
# Selector bar
12+
13+
A selector bar lets a user switch between a small number of different sets or views of data. One item at a time can be selected.
14+
15+
:::image type="content" source="images/selector-bar.png" alt-text="Selector bar with nodes Recent, Shared, Favorites. The Recent node is selected, as indicated by a blue line under the text.":::
16+
17+
When a user selects an item in the selector bar, you typically change the view by either:
18+
19+
- navigating between different pages in your app.
20+
- changing the data shown in a collection control.
21+
22+
The selector bar is a light-weight control that supports an icon and text. It's intended to present a limited number of options so it does not rearrange items to adapt to different window sizes.
23+
24+
## Is this the right control?
25+
26+
Use a SelectorBar when you want to let a user navigate between a limited number of views or pages and only one option can be selected at once.
27+
28+
Some examples include:
29+
30+
- Switching between "Recent," "Shared," and "Favorites" pages, where each page displays a unique list of content.
31+
- Switching between "All," "Unread," "Flagged," and "Urgent" views, where each view displays a uniquely filtered list of email items.
32+
33+
### When should a different control be used?
34+
35+
There are some scenarios where another control may be more appropriate to use.
36+
37+
- Use [NavigationView](navigationview.md) when you require consistent, top-level app navigation that adapts to different window sizes.
38+
- Use [TabView](tab-view.md) when the user should be able to open, close, rearrange, or tear off new views of the content.
39+
- Use [PipsPager](pipspager.md) when you need regular pagination of a single data view.
40+
- Use [RadioButtons](radio-button.md) when an option is not selected by default, and context is unrelated to page navigation.
41+
42+
## UWP and WinUI 2
43+
44+
> [!IMPORTANT]
45+
> The SelectorBar control is not available for UWP and WinUI 2. For alternatives, see [NavigationView](navigationview.md) or [TabView](tab-view.md).
46+
47+
## Create a SelectorBar control
48+
49+
> [!div class="checklist"]
50+
>
51+
> - **Important APIs**: [SelectorBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar), [Items property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.items), [SelectionChanged event](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.selectionchanged), [SelectorBarItem class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbaritem)
52+
53+
> [!div class="nextstepaction"]
54+
> [Open the WinUI 3 Gallery app and see the SelectorBar in action](winui3gallery:/item/SelectorBar).
55+
56+
[!INCLUDE [winui-3-gallery](../../../includes/winui-3-gallery.md)]
57+
58+
This XAML creates a basic SelectorBar control with 3 sections of content.
59+
60+
```xaml
61+
<SelectorBar x:Name="SelectorBar">
62+
<SelectorBarItem x:Name="SelectorBarItemRecent"
63+
Text="Recent" Icon="Clock"/>
64+
<SelectorBarItem x:Name="SelectorBarItemShared"
65+
Text="Shared" Icon="Share"/>
66+
<SelectorBarItem x:Name="SelectorBarItemFavorites"
67+
Text="Favorites" Icon="Favorite"/>
68+
</SelectorBar>
69+
```
70+
71+
This shows how to add a SelectorBarItem in code.
72+
73+
```csharp
74+
SelectorBarItem newItem = new SelectorBarItem()
75+
{
76+
Text = "New Item",
77+
Icon = new SymbolIcon(Symbol.Add)
78+
};
79+
selectorBar.Items.Add(newItem);
80+
```
81+
82+
### SelectorBar items
83+
84+
You populate the SelectorBar [Items](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.items) collection with [SelectorBarItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbaritem) objects. You can do this directly in XAML or in code. Because it's intended to display a limited number of options, SelectorBar does not have an `ItemsSource` property for binding to an external collection of items.
85+
86+
### Item content
87+
88+
The SelectorBarItem class provides [Text](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbaritem.text) and [Icon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbaritem.icon) properties that you use to set the content of your selector bar. You can set one or both properties; however, we recommend that you set the `Text` property to make the item more meaningful.
89+
90+
The `Icon` property takes an [IconElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.iconelement), so you can use any of these derived icon types:
91+
92+
- [AnimatedIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.animatedicon)
93+
- [BitmapIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.bitmapicon)
94+
- [FontIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.fonticon)
95+
- [IconSourceElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.iconsourceelement)
96+
- [ImageIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.imageicon)
97+
- [PathIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.pathicon)
98+
- [SymbolIcon](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.symbolicon)
99+
100+
> [!NOTE]
101+
> SelectorBarItem inherits the [Child](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemcontainer.child) property from ItemContainer. You can use this property to set the content, but we don't recommend this. Content set this way will not get the styling and visual states provided by the SelectorBarItem control template.
102+
103+
### Item selection
104+
105+
You can use the [SelectedItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.selecteditem) property to get or set the SelectorBar's active item. This is synchronized with the SelectorBarItem's [IsSelected](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemcontainer.isselected) property. If you set either property, the other is updated automatically.
106+
107+
Whenever the SelectorBar gets focus and `SelectedItem` is `null`, `SelectedItem` is automatically set to the first focusable instance in the [Items](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.items) collection, if any exists.
108+
109+
Whenever the selected item is removed from the `Items` collection, the `SelectedItem` property is set to `null`. If `SelectedItem` is set to `null` while the SelectorBar has focus, SelectorBar will have no item selected but keeps focus.
110+
111+
Setting `SelectedItem` to an element that is not currently in the `Items` collection throws an exception.
112+
113+
There is no `SelectedIndex` property, but you can get the index of the `SelectedItem` like this:
114+
115+
```csharp
116+
int currentSelectedIndex =
117+
selectorBar.Items.IndexOf(selectorBar.SelectedItem);
118+
```
119+
120+
### Selection changed
121+
122+
Handle the [SelectionChanged](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.selectionchanged) event to respond to the users selection and change what is shown to the user. The `SelectionChanged` event is raised when an item is selected in any of these ways:
123+
124+
- UI Automation
125+
- Tab focus (and a new item is selected)
126+
- Left and right navigation within the SelectorBar
127+
- Tapped event through mouse or touch
128+
- Programmatic selection (through either the [SelectorBar.SelectedItem](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.selecteditem) property or SelectorBarItem's [IsSelected](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemcontainer.isselected) property).
129+
130+
When a user selects an item, you typically change the view by either navigating between different pages in your app or changing the data shown in a collection control. Examples of both are shown here.
131+
132+
### Navigate with transition animations
133+
134+
> [!TIP]
135+
> You can find these examples in the SelectorBar page of the [WinUI Gallery app](#get-the-sample-code). Use the WinUI Gallery app to run and view the full code.
136+
137+
This example demonstrates handling the [SelectionChanged](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar.selectionchanged) event to navigate between different pages. The navigation uses the [SlideNavigationTransitionEffect](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.animation.slidenavigationtransitioneffect) to slide the pages in from the left or right, as appropriate.
138+
139+
```xaml
140+
<SelectorBar x:Name="SelectorBar2"
141+
SelectionChanged="SelectorBar2_SelectionChanged">
142+
<SelectorBarItem x:Name="SelectorBarItemPage1" Text="Page1"
143+
IsSelected="True" />
144+
<SelectorBarItem x:Name="SelectorBarItemPage2" Text="Page2" />
145+
<SelectorBarItem x:Name="SelectorBarItemPage3" Text="Page3" />
146+
<SelectorBarItem x:Name="SelectorBarItemPage4" Text="Page4" />
147+
<SelectorBarItem x:Name="SelectorBarItemPage5" Text="Page5" />
148+
</SelectorBar>
149+
150+
<Frame x:Name="ContentFrame" IsNavigationStackEnabled="False" />
151+
```
152+
153+
```csharp
154+
int previousSelectedIndex = 0;
155+
156+
private void SelectorBar2_SelectionChanged
157+
(SelectorBar sender, SelectorBarSelectionChangedEventArgs args)
158+
{
159+
SelectorBarItem selectedItem = sender.SelectedItem;
160+
int currentSelectedIndex = sender.Items.IndexOf(selectedItem);
161+
System.Type pageType;
162+
163+
switch (currentSelectedIndex)
164+
{
165+
case 0:
166+
pageType = typeof(SamplePage1);
167+
break;
168+
case 1:
169+
pageType = typeof(SamplePage2);
170+
break;
171+
case 2:
172+
pageType = typeof(SamplePage3);
173+
break;
174+
case 3:
175+
pageType = typeof(SamplePage4);
176+
break;
177+
default:
178+
pageType = typeof(SamplePage5);
179+
break;
180+
}
181+
182+
var slideNavigationTransitionEffect =
183+
currentSelectedIndex - previousSelectedIndex > 0 ?
184+
SlideNavigationTransitionEffect.FromRight :
185+
SlideNavigationTransitionEffect.FromLeft;
186+
187+
ContentFrame.Navigate(pageType, null, new SlideNavigationTransitionInfo()
188+
{ Effect = slideNavigationTransitionEffect });
189+
190+
previousSelectedIndex = currentSelectedIndex;
191+
}
192+
```
193+
194+
### Display different collections in an ItemsView
195+
196+
This example shows how to change the data source of an [ItemsView](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemsview) when the user selects an option in the SelectorBar.
197+
198+
```xaml
199+
<SelectorBar x:Name="SelectorBar3"
200+
SelectionChanged="SelectorBar3_SelectionChanged">
201+
<SelectorBarItem x:Name="SelectorBarItemPink" Text="Pink"
202+
IsSelected="True"/>
203+
<SelectorBarItem x:Name="SelectorBarItemPlum" Text="Plum"/>
204+
<SelectorBarItem x:Name="SelectorBarItemPowderBlue" Text="PowderBlue"/>
205+
</SelectorBar>
206+
207+
<ItemsView x:Name="ItemsView3"
208+
ItemTemplate="{StaticResource ColorsTemplate}"/>
209+
<ItemsView.Layout>
210+
<UniformGridLayout/>
211+
</ItemsView.Layout>
212+
</ItemsView/>
213+
```
214+
215+
```csharp
216+
private void SelectorBar3_SelectionChanged
217+
(SelectorBar sender, SelectorBarSelectionChangedEventArgs args)
218+
{
219+
if (sender.SelectedItem == SelectorBarItemPink)
220+
{
221+
ItemsView3.ItemsSource = PinkColorCollection;
222+
}
223+
else if (sender.SelectedItem == SelectorBarItemPlum)
224+
{
225+
ItemsView3.ItemsSource = PlumColorCollection;
226+
}
227+
else
228+
{
229+
ItemsView3.ItemsSource = PowderBlueColorCollection;
230+
}
231+
}
232+
```
233+
234+
235+
## Get the sample code
236+
237+
- [WinUI Gallery sample](https://github.com/Microsoft/WinUI-Gallery) - See all the XAML controls in an interactive format.
238+
239+
## Related topics
240+
241+
- [SelectorBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.selectorbar)
242+
- [Navigation design basics](../basics/navigation-basics.md)

‎hub/apps/design/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,8 @@
201201
href: controls/navigationview.md
202202
- name: Pivot
203203
href: controls/pivot.md
204+
- name: Selector bar
205+
href: controls/selector-bar.md
204206
- name: Tab view
205207
href: controls/tab-view.md
206208
- name: People

0 commit comments

Comments
 (0)