Merge pull request #5302 from MicrosoftDocs/main

main to live merge for PowerToys Command Palette PR for alvinashcraft

Author: alvinashcraft

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/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

@@ -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

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

@@ -108,7 +108,7 @@ The tables below describe the properties of the action definition JSON file.
 | inputCombinations | InputCombination[] | Provides descriptions for different combinations of inputs. | Yes |
 | outputs | Output[] | If specified, must be an empty string in the current release. | No |
 | invocation | Invocation | Provides information about how the action is invoked. | Yes |
-| contentAgeRating | string | A field name from the [UserAgeConsentGroup](/uwp/api/windows.system.userageconsentgroup)that specifies the appropriate age rating for the action. The allowed values are "Child", "Minor", "Adult". If no value is specified, the default behavior allows access to all ages. | No |
+| contentAgeRating | string | A field name from the [UserAgeConsentGroup](/uwp/api/windows.system.userageconsentgroup) that specifies the appropriate age rating for the action. The allowed values are "Child", "Minor", "Adult". If no value is specified, the default behavior allows access to all ages. | No |
 
 ### Output
 
@@ -224,7 +224,7 @@ The following example shows a *where* clause that evaluates to true if a **File*
 Multiple *where* clauses can be combined using the logical AND and logical OR operators.
 
 ```json
-where": [ 
+"where": [ 
   "${File.Extension} ~= \".txt\" || ${File.Extension} ~= \".md\"" 
 ] 
 ```

hub/apps/design/toc.yml

@@ -26,7 +26,7 @@ Action providers must provide a **Registration** element which specifies the pat
         Id="..." 
         PublicFolder="Assets"> 
       <uap3:Properties> 
-        <Registration>path\to\registration.json</Registration> 
+        <Registration>path\to\registration.json</Registration> <!-- path relative to the PublicFolder above -->
       </uap3:Properties> 
     </uap3:AppExtension> 
 </uap3:Extension> 
@@ -35,8 +35,8 @@ Action providers must provide a **Registration** element which specifies the pat
 
 ## Additional requirements
 
-Both COM and URI-launched action providers must have package identity. Package identity is declare in the app package manifest file using the [Identity](/uwp/schemas/appxpackage/uapmanifestschema/element-identity) element. For more information, see [An overview of Package Identity in Windows apps](/windows/apps/desktop/modernize/package-identity-overview).
+Both COM and URI-launched action providers must have package identity. Package identity is declared in the app package manifest file using the [Identity](/uwp/schemas/appxpackage/uapmanifestschema/element-identity) element. For more information, see [An overview of Package Identity in Windows apps](/windows/apps/desktop/modernize/package-identity-overview).
 
-COM-based action providers must have be *full trust apps* which have an integrity level of *mediumIL*. This is declared in the app package manifest file by setting the [*uap10:TrustLevel](/uwp/schemas/appxpackage/uapmanifestschema/element-uap10-extension) attribute to "mediumIL".
+COM-based action providers must be *full trust apps* which have an integrity level of *mediumIL*. This is declared in the app package manifest file by setting the [*uap10:TrustLevel](/uwp/schemas/appxpackage/uapmanifestschema/element-uap10-extension) attribute to "mediumIL".
 
-URI-launched action providers must also have a trust level of *mediumIL*. If a URI-launched action provider will return outputs, the app must implement the ability to be launched for results. For more information, see [Launch an app for results](/windows/uwp/launch-resume/how-to-launch-an-app-for-results). URI-launched action providers that return outputs must also instantiate the runtime.
+URI-launched action providers must also have a trust level of *mediumIL*. If a URI-launched action provider will return outputs, the app must implement the ability to be launched for results. For more information, see [Launch an app for results](/windows/uwp/launch-resume/how-to-launch-an-app-for-results). URI-launched action providers that return outputs must also instantiate the runtime.

hub/apps/develop/actions/action-json.md

@@ -16,7 +16,7 @@ Actions are atomic units of functionality that can be invoked by the Windows Cop
 When building AI backed actions, it is your responsibility as the Action author to perform content moderation and abuse monitoring when it comes to entities returned to the user. For more information about Microsoft Responsible AI policies for more information, see [Microsoft Responsible AI: Principles and approach](https://www.microsoft.com/en-us/ai/principles-and-approach)
 
 > [!NOTE]
-> Consider if children should have access to the action using the ‘age-rating’ property in the action definition.
+> Consider if children should have access to the action using the ‘contentAgeRating’ property in the action definition JSON.
 
 ## Related articles
 

hub/apps/develop/actions/action-provider-manifest.md

@@ -266,3 +266,6 @@ private LRESULT WindowSubClass(HWND hWnd, uint uMsg, WPARAM wParam, LPARAM lPara
 }
 ```
 
+## Sign your Windows Copilot hardware key provider.
+
+Provider apps must be signed in order to be enabled as a target of the Microsoft Copilot hardware key. For information on packaging and signing your app, see [Package a desktop or UWP app in Visual Studio](https://learn.microsoft.com/en-us/windows/msix/package/packaging-uwp-apps).

hub/apps/develop/actions/index.md

@@ -53,3 +53,8 @@ The following table *uap3:AppExtension* describes the attributes of the **uap3:A
 | DisplayName | The app name displayed in the Windows Copilot hardware button picker UI.  | Yes |
 | Description | The app description displayed in the Windows Copilot hardware button picker UI. | Yes |
 | PublicFolder|  The folder that the instance declares as the location where a host can have read access to files through a broker. | Yes | 
+
+
+## Sign your Windows Copilot hardware key provider.
+
+Provider apps must be signed in order to be enabled as a target of the Microsoft Copilot hardware key. For information on packaging and signing your app, see [Package a desktop or UWP app in Visual Studio](https://learn.microsoft.com/en-us/windows/msix/package/packaging-uwp-apps).