Skip to content

Create TabbedCommandBar.md #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 14 commits into from
Closed

Create TabbedCommandBar.md #405

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
51bb022
Create TabbedCommandBar.md
yoshiask Nov 3, 2020
6552f78
Added TabbedCommandBar to ToC
yoshiask Feb 8, 2021
80ecc82
Fixed links at end of doc
yoshiask Feb 8, 2021
9ec3514
Update "Syntax" section with code from SampleApp
yoshiask Feb 8, 2021
8f018ab
Updated properties; Added few examples
yoshiask Feb 8, 2021
ac7538b
Added overview GIF
yoshiask Feb 9, 2021
a63a266
Merge branch 'master' into patch-1
Kyaa-dost Feb 25, 2021
6a83ab2
Update docs/controls/TabbedCommandBar.md
michael-hawker Feb 25, 2021
b9b0b35
Apply suggestions from code review
michael-hawker Mar 5, 2021
a2e64c3
Merge branch 'master' into patch-1
michael-hawker Mar 5, 2021
1f71dbc
Update toc.md
Kyaa-dost Mar 5, 2021
fa67ea4
Updated contextual tab example; Switched from GIF to PNG for overview
yoshiask Mar 6, 2021
fdd0679
Use `https`
yoshiask Mar 8, 2021
d6eefb4
Satisfy linter
yoshiask Mar 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 209 additions & 0 deletions docs/controls/TabbedCommandBar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
---
title: TabbedCommandBar XAML Control
author: yoshiask
description: TabbedCommandBar is a control for displaying multiple CommandBars in the same space, like Microsoft Office's ribbon.
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, TabbedCommandBar, CommandBar, ribbon
dev_langs:
- csharp
---

# TabbedCommandBar XAML Control
The [TabbedCommandBar](https://docs.microsoft.com/dotnet/api/microsoft.toolkit.uwp.ui.controls.tabbedcommandbar) displays a set of [TabbedCommandBarItem](https://docs.microsoft.com/dotnet/api/microsoft.toolkit.uwp.ui.controls.tabbedcommandbaritem) in a shared container, like Microsoft Office's ribbon.

> [!div class="nextstepaction"]
> [Try it in the sample app](uwpct://Controls?sample=TabbedCommandBar)

## Syntax

```xaml
<ribbon:TabbedCommandBar Grid.Row="1" Background="{ThemeResource SystemControlAcrylicWindowBrush}">
<ribbon:TabbedCommandBar.Footer>
<CommandBar Background="Transparent" DefaultLabelPosition="Right">
<AppBarButton Label="Support developer">
<AppBarButton.Resources>
<Thickness x:Key="AppBarButtonTextLabelOnRightMargin">0,11,12,13</Thickness>
</AppBarButton.Resources>
</AppBarButton>
<AppBarButton Icon="Setting">
<AppBarButton.Resources>
<Thickness x:Key="AppBarButtonTextLabelOnRightMargin">0,11,12,13</Thickness>
</AppBarButton.Resources>
</AppBarButton>
</CommandBar>
</ribbon:TabbedCommandBar.Footer>

<ribbon:TabbedCommandBar.Resources>
<StaticResource x:Key="NavigationViewTopPaneBackground" ResourceKey="SystemControlChromeMediumLowAcrylicWindowMediumBrush" />
<StaticResource x:Key="TabbedCommandBarContentBackground" ResourceKey="SystemControlChromeLowAcrylicWindowBrush" />
</ribbon:TabbedCommandBar.Resources>

<ribbon:TabbedCommandBarItem Header="Home">
<AppBarButton Icon="Undo" Label="Undo"/>
<AppBarButton Icon="Redo" Label="Redo"/>
<AppBarButton Icon="Paste" Label="Paste"/>
<AppBarSeparator />
<AppBarElementContainer>
<ComboBox SelectedIndex="0">
<ComboBoxItem Content="Arial" />
<ComboBoxItem Content="Calibri" />
<ComboBoxItem Content="JetBrains Mono" />
<ComboBoxItem Content="Roboto" />
<ComboBoxItem Content="Sergio UI" />
<ComboBoxItem Content="Sergio UI Semibold" />
</ComboBox>
</AppBarElementContainer>
<AppBarToggleButton Icon="Bold" Label="Bold" />
<AppBarToggleButton Icon="Italic" Label="Italic" />
<AppBarToggleButton Icon="Underline" Label="Underline" />
</ribbon:TabbedCommandBarItem>

<ribbon:TabbedCommandBarItem Header="Insert">
<AppBarButton Icon="Pictures" Label="Pictures">
<AppBarButton.Flyout>
<MenuFlyout Placement="BottomEdgeAlignedLeft">
<MenuFlyoutItem Text="This Device">
<MenuFlyoutItem.Icon>
<FontIcon FontFamily="Segoe MDL2 Assets" Glyph="&#xEC4E;" />
</MenuFlyoutItem.Icon>
</MenuFlyoutItem>
<MenuFlyoutItem Text="Stock Images">
<MenuFlyoutItem.Icon>
<FontIcon FontFamily="Segoe MDL2 Assets" Glyph="&#xE721;" />
</MenuFlyoutItem.Icon>
</MenuFlyoutItem>
<MenuFlyoutItem Icon="Globe" Text="Online Pictures" />
</MenuFlyout>
</AppBarButton.Flyout>
</AppBarButton>

<ribbon:TabbedCommandBarItem.SecondaryCommands>
<AppBarButton Icon="Add" Label="New item" />
</ribbon:TabbedCommandBarItem.SecondaryCommands>
</ribbon:TabbedCommandBarItem>
</ribbon:TabbedCommandBar>
```

## Sample Output

![TabbedCommandBar Overview](../resources/images/Controls/TabbedCommandBar/Overview.gif)

## Properties

### TabView Properties

| Property | Type | Description |
| -- | -- | -- |
| CanCloseTabs | bool | Default value for if the TabViewItem doesn't specify a IsClosable value. |
| IsCloseButtonOverlay | bool | Changes the behavior of how the Close button effects layout. If True, the close button will overlay itself on top of content if the tab is a fixed size. |
| ItemHeaderTemplate | DataTemplate | Default Template for the TabViewItem Header if no template is specified. |
| SelectedTabWidth | double | Size to set the Selected Tab Header. Defaults to Auto. |
| TabActionHeader | object | Area to the Right of Tab Strip before Padding. |
| TabActionHeaderTemplate | DataTemplate | Template for the TabActionHeader. |
| TabEndHeader | object | Area to the Right of the Tab Strip after Padding. |
| TabEndHeaderTemplate | DataTemplate | Template for the TabEndHeader. |
| TabStartHeader | object | Description Area to the Left of the Tab Strip. |
| TabStartHeaderTemplate | DataTemplate | Template for the TabStartHeader. |
| TabWidthBehavior | TabWidthMode | Actual, Equal, or Compact values specify how Tab Headers should be sized. Defaults to Actual. |

> [!IMPORTANT]
> Do not use `ItemsStackPanel` if you override the ItemsPanel. It is suggested to keep the `TabWidthBehavior` to `Actual` when using a custom panel.

### TabViewItem Properties

| Property | Type | Description |
| -- | -- | -- |
| Content | object | Main Tab Content. |
| Header | object | Header Content of the Tab. |
| HeaderTemplate | DataTemplate | Template for the Header object. |
| Icon | IconElement | Icon of the Tab. |
| IsClosable | bool | Set to true for the TabViewItem to show a close button. |

## Events

### TabView Events

| Events | Description |
| -- | -- |
| TabClosing | Fires when a Tab is about to be closed, can be intercepted to prevent closure. |
| TabDraggedOutside | Fires when a Tab is dragged outside of the Tab bar. |

### TabViewItem Events
| Events | Description |
| -- | -- |
| TabClosing | Fires when a Tab's closed button is clicked. |

## Examples

If you want to replicate the behavior of Microsoft Edge with the TabView, you can use the following setup:

```xaml
<controls:TabView TabWidthBehavior="Equal"
CanCloseTabs="True"
IsCloseButtonOverlay="True"
CanDragItems="True"
CanReorderItems="True"
AllowDrop="True">
<controls:TabView.Resources>
<x:Double x:Key="TabViewItemHeaderMinHeight">32</x:Double>
<x:Double x:Key="TabViewItemHeaderMinWidth">90</x:Double>
<x:Double x:Key="TabViewItemHeaderMaxWidth">200</x:Double>
</controls:TabView.Resources>
...
</controls:TabView>
```

The TabView supports data binding as well. The following example shows binding the TabView to a collection of 'DataItems' which have both 'Value' and 'MyText' properties:

```xaml
<controls:TabView x:Name="TabItems"
ItemsSource="{Binding TabItemCollection}">
<controls:TabView.ItemHeaderTemplate>
<DataTemplate>
<TextBlock>
<Run Text="{Binding Value}"/>
<Run Text=": "/>
<Run Text="{Binding MyText}"/>
</TextBlock>
</DataTemplate>
</controls:TabView.ItemHeaderTemplate>
<controls:TabView.ItemTemplate>
<DataTemplate>
<StackPanel>
<TextBlock Margin="8">
<Run Text="Tab Value: "/>
<Run Text="{Binding Value}" />
</TextBlock>
<TextBlock Margin="8,0,0,0" Text="Some other shared content..." />
</StackPanel>
</DataTemplate>
</controls:TabView.ItemTemplate>
</controls:TabView>
```

> [!NOTE]
> It's recommended to use an [ObservableCollection](https://docs.microsoft.com/en-us/dotnet/api/system.collections.objectmodel.observablecollection-1) when working with the TabView.

## Sample Project

[TabView Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/TabView). You can [see this in action](uwpct://Controls?sample=TabView) in the [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp).

## Default Template

[TabView XAML File](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/Microsoft.Toolkit.Uwp.UI.Controls/TabView/TabView.xaml) is the XAML template used in the toolkit for the default styling.

## Requirements

| Device family | Universal, 10.0.16299.0 or higher |
| -- | -- |
| Namespace | Microsoft.Toolkit.Uwp.UI.Controls |
| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) |

## API

- [TabView source code](https://github.com/Microsoft/WindowsCommunityToolkit//tree/master/Microsoft.Toolkit.Uwp.UI.Controls/TabView)

## Related Topics

- [ObservableCollection](https://docs.microsoft.com/en-us/dotnet/api/system.collections.objectmodel.observablecollection-1)
- [IconElement](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Controls.IconElement)
- [TabControl (WPF)](https://docs.microsoft.com/en-us/dotnet/api/system.windows.controls.tabcontrol)