Merge branch 'main' into niels9001/toc-consistency

Author: niels9001

hub/apps/design/accessibility/designing-inclusive-software.md

@@ -94,7 +94,7 @@ In summary, follow these seven steps to ensure your software is inclusive.
 3.	Design a logical hierarchy for your product, noting where the standard controls, any custom controls, and keyboard focus are in the UI.  
 4.	Design useful system settings (such as keyboard navigation, high contrast, and high dpi) into your product.  
 5.	Implement your design, using the [Microsoft accessibility developer hub](https://developer.microsoft.com/windows/accessible-apps) and your framework’s accessibility specification as a reference point.  
-6.	Test your product with users who have special needs to ensure they will be able to take advantage of the inclusive design techniques implemented in it.  
+6.	Test your product with users who have functional needs to ensure they will be able to take advantage of the inclusive design techniques implemented in it.  
 7.	Deliver your finished product and document your implementation for those who may work on the project after you.  
 
 ## Related topics  

hub/apps/design/basics/titlebar-design.md

@@ -8,7 +8,7 @@ keywords: windows 10, uwp
 ms.localizationpriority: medium
 ---
 
-# Title bar
+# Title bar design
 
 The title bar sits at the top of an app on the [base layer](../signature-experiences/layering.md). Its main purpose is to allow users to be able to identify the app via its title, move the app window, and minimize, maximize, or close the app.
 

hub/apps/design/controls/forms.md

@@ -121,7 +121,7 @@ Control | Use | Example
 ### Lists
 Control | Use | Example
 - | - | -
-[ComboBox](combo-box.md) | Start in compact state and expand to show list of selectable items | Select from a long list of items, such as states or countries
+[ComboBox](combo-box.md) | Start in compact state and expand to show list of selectable items | Select from a long list of items, such as states or countries/regions
 [ListView](./lists.md#list-view) | Categorize items and assign group headers, drag and drop items, curate content, and reorder items | Rank options
 [GridView](./lists.md#grid-view) | Arrange and browse image-based collections | Pick a photo, color, display theme
 

hub/apps/design/controls/images/titlebar/title-bar-custom.png

@@ -0,0 +1,150 @@
+---
+description: Learn how to use a title bar control to give your app a custom title bar.
+title: Title bar
+label: Tile bar
+template: detail.hbs
+op-migration-status: ready
+ms.date: 03/31/2025
+ms.topic: article
+doc-status: Published
+ms.localizationpriority: medium
+---
+# Title bar
+
+The TitleBar control provides a simplified way to create a custom title bar for your app. The title bar is a fundamental component of a Windows app's user interface that identifies the app via its icon and title, houses the system caption buttons that let a user close, maximize, minimize, and restore the window, and lets a user drag the window around the screen.
+
+You can use a custom title bar to better integrate the title bar area with your app UI. The title bar can be customized to match the app's visual style using Mica theming. It can include other relevant information, such as a document title or the current state (e.g., “Editing,” “Viewing,” etc.). It can also host other WinUI controls, like AutoSuggestBox and PersonPicture, providing a cohesive user experience for your app.
+
+![Screenshot of an app window with a custom title bar](images/titlebar/title-bar-custom.png)
+
+## Is this the right control?
+
+Use the TitleBar control when you want to integrate the title bar area with your app UI using customizations such as subtitles, [Mica](../style/mica.md) theming, and integrations with WinUI controls.
+
+## Anatomy
+
+By default, the title bar shows only the system caption buttons. Other parts of the title bar are shown or hidden depending on associated property settings.
+
+The title bar is divided into these areas:
+
+![Screenshot showing the parts of a title bar control.](images/titlebar/title-bar-parts.png)
+
+- **Back button:** [IsBackButtonEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [IsBackButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonvisible), [BackRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.backrequested) - A built-in back button for navigation.
+- **Pane toggle button:** [IsPaneToggleButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [PaneToggleRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.panetogglerequested) - This button is intended to be used in conjunction with the NavigationView control.
+- **Left header:** [LeftHeader](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.leftheader)
+- **Icon:** [IconSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.iconsource)
+- **Title:** [Title](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.title)
+- **Subtitle:** [Subtitle](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.subtitle)
+- **Content:** [Content](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.content)
+- **Right header:** [RightHeader](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.rightheader)
+- **Min drag region:** This area is reserved next to the system caption buttons so that the user always has a place to grab the window for dragging.
+- **System caption buttons:** These buttons are not part of the TitleBar control - it simply allocates space where the caption buttons appear, depending on RTL or LTR settings. Caption buttons and customizations are handled by the [AppWindowTitleBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.windowing.appwindowtitlebar).
+
+The layout is reversed when the [FlowDirection](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection) is **RightToLeft**.
+
+## Create a title bar
+
+> [!div class="checklist"]
+>
+> - **Important APIs:** [TitleBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar), [Title property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.title)
+
+> [!div class="nextstepaction"]
+> [Open the WinUI 3 Gallery app and see the TitleBar in action](winui3gallery:/item/TitleBar)
+
+[!INCLUDE [winui-3-gallery](../../../includes/winui-3-gallery.md)]
+
+This example creates a simple title bar that replaces the system title bar. It has a title, icon, and Mica theming.
+
+```xaml
+<Window
+    ...  >
+    <Window.SystemBackdrop>
+        <MicaBackdrop Kind="Base"/>
+    </Window.SystemBackdrop>
+
+    <Grid>
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto" />
+            <RowDefinition Height="*" />
+        </Grid.RowDefinitions>
+
+        <TitleBar x:Name="SimpleTitleBar"
+                  Title="My App">
+            <TitleBar.IconSource>
+                <FontIconSource Glyph="&#xF4AA;"/>
+            </TitleBar.IconSource>
+        </TitleBar>
+
+        <!-- App content -->
+        <Frame x:Name="RootFrame" Grid.Row="1"/>
+    </Grid>
+</Window>
+```
+
+```csharp
+public MainWindow()
+{
+    this.InitializeComponent();
+
+    // Hides the default system title bar.
+    ExtendsContentIntoTitleBar = true;
+    // Replace system title bar with the WinUI TitleBar control. 
+    SetTitleBar(SimpleTitleBar); 
+}
+
+```
+
+## Integration with NavigationView
+
+The [Navigation view](navigationview.md) has a built-in back button and pane toggle button. Fluent Design guidance recommends that these controls be placed in the title bar when a custom title bar is used.
+
+This example demonstrates how to integrate the TitleBar control with a NavigationView control by hiding the back button and pane toggle button in the navigation view and using the corresponding buttons on the title bar instead.
+
+```xaml
+<Grid>
+    <Grid.RowDefinitions>
+        <RowDefinition Height="Auto" />
+        <RowDefinition Height="*" />
+    </Grid.RowDefinitions>
+
+    <TitleBar Title="My App"
+              IsBackButtonVisible="True"
+              IsBackButtonEnabled="{x:Bind RootFrame.CanGoBack, Mode=OneWay}"
+              BackRequested="TitleBar_BackRequested"
+              IsPaneToggleButtonVisible="True"
+              PaneToggleRequested="TitleBar_PaneToggleRequested">
+    </TitleBar>
+
+    <NavigationView x:Name="RootNavigationView" Grid.Row="1"
+                    IsBackButtonVisible="Collapsed"
+                    IsPaneToggleButtonVisible="False">
+        <Frame x:Name="RootFrame" />
+    </NavigationView>
+</Grid>
+```
+
+```csharp
+private void TitleBar_BackRequested(TitleBar sender, object args)
+{
+    if (RootFrame.CanGoBack)
+    {
+        RootFrame.GoBack();
+    }
+}
+
+private void TitleBar_PaneToggleRequested(TitleBar sender, object args)
+{
+    RootNavigationView.IsPaneOpen = !RootNavigationView.IsPaneOpen;
+}
+
+```
+
+## UWP and WinUI 2
+
+The TitleBar control is not available for UWP and WinUI 2. Instead, see [Title bar customization (UWP apps)](/windows/uwp/ui-input/title-bar).
+
+## Related articles
+
+- [Title bar (design)](../basics/titlebar-design.md)
+- [Title bar customization](../../develop/title-bar.md)
+- [TitleBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar)

hub/apps/design/controls/images/titlebar/title-bar-parts.png

@@ -20,7 +20,7 @@ Design and develop your app in such a way that it functions appropriately on sys
 | Appropriately format numbers, dates, times, addresses, and phone numbers. | These formats vary between cultures, regions, languages, and markets. If you're displaying these data then use [**Globalization**](/uwp/api/Windows.Globalization?branch=live) APIs to get the format appropriate for a particular audience. See [Globalize your date/time/number formats](use-global-ready-formats.md). The order in which family and given names are displayed, and the format of addresses, can differ as well. Use standard date, time, and number displays. Use standard date and time picker controls. Use standard address information. |
 | Support international units of measurement and currency. | Different units and scales are used in different countries, although the most popular are the metric system and the imperial system. Be sure to support the correct system measurement if you deal with measurements such as length, temperature, and area. Use the [**GeographicRegion.CurrenciesInUse**](/uwp/api/windows.globalization.geographicregion.CurrenciesInUse) property to get the set of currencies in use in a region. |
 | Use Unicode for character encoding. | By default, Microsoft Visual Studio uses Unicode character encoding for all documents. If you're using a different editor, be sure to save source files in the appropriate Unicode character encodings. All Windows Runtime APIs return UTF-16 encoded strings. |
-| Support international paper sizes. | The most common paper sizes differ between countries, so if you include features that depend on paper size, such as printing, be sure to support and test common international sizes. |
+| Support international paper sizes. | The most common paper sizes differ between countries/regions, so if you include features that depend on paper size, such as printing, be sure to support and test common international sizes. |
 | Record the language of the keyboard or IME. | When your app asks the user for text input, record the language tag for the currently enabled keyboard layout or Input Method Editor (IME). This ensures that when the input is displayed later it's presented to the user with the appropriate formatting. Use the [**Language.CurrentInputMethodLanguageTag**](/uwp/api/windows.globalization.language.CurrentInputMethodLanguageTag) property to get the current input language. |
 | Don't use language to assume a user's region; and don't use region to assume a user's language. | Language and region are separate concepts. A user can speak a particular regional variant of a language, like en-GB for English as spoken in the UK, but the user might be in an entirely different country or region. Consider whether your app requires knowledge about the user's language (for UI text, for example), or region (for licensing, for example). For more info, see [Understand user profile languages and app manifest languages](manage-language-and-region.md). |
 | The rules for comparing language tags are non-trivial. | [BCP-47 language tags](https://tools.ietf.org/html/bcp47) are complex. There are a number of issues when comparing language tags, including issues with matching script information, legacy tags, and multiple regional variants. The Resource Management System in Windows takes care of matching for you. You can specify a set of resources in any languages, and the system chooses the appropriate one for the user and the app. See [App resources and the Resource Management System](/windows/uwp/app-resources/index) and [How the Resource Management System matches language tags](/windows/uwp/app-resources/how-rms-matches-lang-tags). |

hub/apps/design/controls/title-bar.md

@@ -108,7 +108,7 @@ To ensure that the preferred calendar format is used, you can use the standard [
 
 ## Format phone numbers appropriately
 
-Phone numbers are formatted differently across regions. The number of digits, how the digits are grouped, and the significance of certain parts of the phone number vary between countries. Starting in Windows 10, version 1607, you can use classes in the [**PhoneNumberFormatting**](/uwp/api/windows.globalization.phonenumberformatting?branch=live) namespace to format phone numbers appropriately for the current region.
+Phone numbers are formatted differently across regions. The number of digits, how the digits are grouped, and the significance of certain parts of the phone number vary between countries/regions. Starting in Windows 10, version 1607, you can use classes in the [**PhoneNumberFormatting**](/uwp/api/windows.globalization.phonenumberformatting?branch=live) namespace to format phone numbers appropriately for the current region.
 
 [**PhoneNumberInfo**](/uwp/api/windows.globalization.phonenumberformatting.phonenumberinfo?branch=live) parses a string of digits and allows you to: determine whether the digits are a valid phone number in the current region; compare two numbers for equality; and to extract the different functional parts of the phone number, such as country code or geographical area code.
 

hub/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app.md

@@ -42,7 +42,7 @@ Optical zoom shouldn't be confused with [Semantic Zoom](../controls/semantic-zoo
 Use the following guidelines for apps that support either resizing or optical zooming:
 
 -   If maximum and minimum size constraints or boundaries are defined, use visual feedback to demonstrate when the user reaches or exceeds those boundaries.
--   Use snap points to influence zooming and resizing behavior by providing logical points at which to stop the manipulation and ensure a specific subset of content is displayed in the viewport. Provide snap points for common zoom levels or logical views to make it easier for a user to select those levels. For example, photo apps might provide a resizing snap point at 100% or, in the case of mapping apps, snap points might be useful at city, state, and country views.
+-   Use snap points to influence zooming and resizing behavior by providing logical points at which to stop the manipulation and ensure a specific subset of content is displayed in the viewport. Provide snap points for common zoom levels or logical views to make it easier for a user to select those levels. For example, photo apps might provide a resizing snap point at 100% or, in the case of mapping apps, snap points might be useful at city, state, and country/region views.
 
     Snap points enable users to be imprecise and still achieve their goals. If you're using XAML, see the snap points properties of [**ScrollViewer**](/uwp/api/Windows.UI.Xaml.Controls.ScrollViewer).
 

hub/apps/design/globalizing/use-global-ready-formats.md

@@ -296,6 +296,8 @@
           href: controls/content-links.md
         - name: Handwriting view
           href: controls/text-handwriting-view.md
+    - name: Title bar
+      href: controls/title-bar.md
 - name: Shell
   items:
     - name: Overview