diff --git a/active/TabView/TabView_Close_Hover.gif b/active/TabView/TabView_Close_Hover.gif new file mode 100644 index 000000000..68bbe2bc1 Binary files /dev/null and b/active/TabView/TabView_Close_Hover.gif differ diff --git a/active/TabView/TabView_Close_Persistent.png b/active/TabView/TabView_Close_Persistent.png new file mode 100644 index 000000000..574653f36 Binary files /dev/null and b/active/TabView/TabView_Close_Persistent.png differ diff --git a/active/TabView/TabView_Width_Compact.png b/active/TabView/TabView_Width_Compact.png new file mode 100644 index 000000000..394e6f70d Binary files /dev/null and b/active/TabView/TabView_Width_Compact.png differ diff --git a/active/TabView/TabView_v2.md b/active/TabView/TabView_v2.md new file mode 100644 index 000000000..7e21684d8 --- /dev/null +++ b/active/TabView/TabView_v2.md @@ -0,0 +1,142 @@ + +# Background + +> This spec corresponds to [issue 2007](https://github.com/microsoft/microsoft-ui-xaml/issues/2007) on the WinUI repo. + +The WinUI [TabView](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.TabView) control is a way to display a set of tabs and their respective content. There's also a TabView control in the [Windows Community Toolkit](https://docs.microsoft.com/en-us/windows/communitytoolkit/controls/tabview), which has two main features not found in the WinUI version.: +* **TabWidthMode: Compact** ([WCT API Link](https://docs.microsoft.com/en-us/dotnet/api/microsoft.toolkit.uwp.ui.controls.tabwidthmode?view=win-comm-toolkit-dotnet-stable)) +* **Overlay close button** ([WCT API Link](https://docs.microsoft.com/en-us/dotnet/api/microsoft.toolkit.uwp.ui.controls.tabview.isclosebuttonoverlay?view=win-comm-toolkit-dotnet-stable#Microsoft_Toolkit_Uwp_UI_Controls_TabView_IsCloseButtonOverlay)) + +Once these feature gaps have been closed and the WinUI TabView is at parity with the Windows Community Toolkit version, we will be able to deprecate the WCT TabView control. + +# Examples + +## TabView.TabWidthMode + +A TabView with two items, showing only the icons for the item tabs because TabWidthMode is set to Compact + +```XML + + + + + + + + + + + + + + + + + + + + + + +``` + +## TabView.CloseButtonOverlayMode + +A TabView where the unselected tab items have a close button that only displays when the mouse is over it. (The selected tab item always has a close button, regardless of this property value.) + +```XML + + + +``` + +# API Notes + +## TabViewWidthMode: Compact + +This change introduces a new value to the existing `TabViewWidthMode` enum: `Compact`. + +Setting `Compact` will cause unselected tab headers to display only the tab's icon. If an icon is not set, the tab will be the same size as if an icon was present but display an empty space where the icon would be. + +The selected tab will render at its natural size (ie. the size it would render in `SizeToContent` mode.) + +![Compact](./TabView_Width_Compact.png) + +## CloseButtonOverlayMode + +Describes the behavior of the x-to-close button found on each TabViewItem. + +The `CloseButtonOverlayMode` enum has three values: {`Auto`, `OnPointerOver`, `Always`} + +> The `CloseButtonOverlayMode` will only affect tabs that are closeable - ie. the value of the `TabViewItem`'s `IsClosable` property is `TRUE`. + +`OnPointerOver`: The x-to-close button only appears on the selected tab and any tabs that are being hovered. + +![Hover](./TabView_Close_Hover.gif) + +`Always`: The x-to-close button always appears on every tab. + +![Persistent](./TabView_Close_Persistent.png) + +`Auto`: Currently maps to `Always`. + +> Prior to this change, the behavior of the x-to-close button was `Always` with no option to change the behavior. + +> See the [Appendix](#Appendix) section for why this value is an enum and not a boolean. + +# API Details + + +``` +[WUXC_VERSION_MUXONLY] +[webhosthidden] +enum TabViewWidthMode +{ + Equal = 0, + SizeToContent = 1, + Compact = 2, +}; + +[WUXC_VERSION_MUXONLY] +[webhosthidden] +enum TabViewCloseButtonOverlayMode +{ + Auto = 0, + OnPointerOver = 1, + Always = 2, +}; + +[WUXC_VERSION_MUXONLY] +[webhosthidden] +[contentproperty("TabItems")] +unsealed runtimeclass TabView : Windows.UI.Xaml.Controls.Control +{ + + [WUXC_VERSION_PREVIEW] + [MUX_DEFAULT_VALUE("winrt::TabViewCloseButtonOverlayMode::Auto")] + [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)] + TabViewCloseButtonOverlayMode CloseButtonOverlayMode{ get; set; }; + + [WUXC_VERSION_PREVIEW] + static Windows.UI.Xaml.DependencyProperty CloseButtonOverlayModeProperty{ get; }; +} +``` + +# Appendix + + +**Why is CloseButtonOverlayMode an enum and not a boolean?** + +1. The corresponding visual effect might change over time + +The CloseButtonOverlayMode enum describes a visual effect that is likely to change over time. For example, Spartan Edge used the OnPointerOver model, whereas chromium Edge uses a Always model. An enum allows that platform to have an opinion (via `Auto`) and an option to change the behavior over time in a way that a boolean does not. + +2. Per-device input support + +The original spec had discussion around the desired default (Always vs. pointer over) both in the context of user experience as well as touch-friendliness. An enum value provides the platform an option to set per-device or per-input behavior if desired. + +3. Futureproofing + +An enum gives the platform an option to introduce other modes in the future. Although there haven't been specific modes proposed yet, an enum leaves the door open for changes. diff --git a/archive/Microsoft.UI.Xaml 2.2/.gitkeep b/archive/Microsoft.UI.Xaml 2.2/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/active/tab/images/TabView_dark.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_dark.png similarity index 100% rename from active/tab/images/TabView_dark.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_dark.png diff --git a/active/tab/images/TabView_dark_accent.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_dark_accent.png similarity index 100% rename from active/tab/images/TabView_dark_accent.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_dark_accent.png diff --git a/active/tab/images/TabView_light.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_light.png similarity index 100% rename from active/tab/images/TabView_light.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_light.png diff --git a/active/tab/images/TabView_light_accent.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_light_accent.png similarity index 100% rename from active/tab/images/TabView_light_accent.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/TabView_light_accent.png diff --git a/active/tab/images/tab-control-keyboarding-1.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-1.PNG similarity index 100% rename from active/tab/images/tab-control-keyboarding-1.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-1.PNG diff --git a/active/tab/images/tab-control-keyboarding-2.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-2.PNG similarity index 100% rename from active/tab/images/tab-control-keyboarding-2.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-2.PNG diff --git a/active/tab/images/tab-control-keyboarding-3.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-3.PNG similarity index 100% rename from active/tab/images/tab-control-keyboarding-3.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-keyboarding-3.PNG diff --git a/active/tab/images/tab-control-parts-1.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-1.PNG similarity index 100% rename from active/tab/images/tab-control-parts-1.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-1.PNG diff --git a/active/tab/images/tab-control-parts-2.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-2.PNG similarity index 100% rename from active/tab/images/tab-control-parts-2.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-2.PNG diff --git a/active/tab/images/tab-control-parts-3.PNG b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-3.PNG similarity index 100% rename from active/tab/images/tab-control-parts-3.PNG rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-control-parts-3.PNG diff --git a/active/tab/images/tab-extend-to-title.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-extend-to-title.png similarity index 100% rename from active/tab/images/tab-extend-to-title.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-extend-to-title.png diff --git a/active/tab/images/tab-new-window.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-new-window.png similarity index 100% rename from active/tab/images/tab-new-window.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-new-window.png diff --git a/active/tab/images/tab-overview.png b/archive/Microsoft.UI.Xaml 2.2/tab/images/tab-overview.png similarity index 100% rename from active/tab/images/tab-overview.png rename to archive/Microsoft.UI.Xaml 2.2/tab/images/tab-overview.png diff --git a/active/tab/tabcontrol.md b/archive/Microsoft.UI.Xaml 2.2/tab/tabcontrol.md similarity index 98% rename from active/tab/tabcontrol.md rename to archive/Microsoft.UI.Xaml 2.2/tab/tabcontrol.md index 42f6be7e6..b2e485783 100644 --- a/active/tab/tabcontrol.md +++ b/archive/Microsoft.UI.Xaml 2.2/tab/tabcontrol.md @@ -1,3 +1,6 @@ +> This spec is archived and may not be up to date. +> For up-to-date developer documentation please see: [Guidance Doc](https://docs.microsoft.com/windows/uwp/design/controls-and-patterns/tab-view), [API Doc](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.tabview?view=winui-2.3) +