diff --git a/docs/TOC.yml b/docs/TOC.yml index 892dd1ed9..61b8d6fc9 100644 --- a/docs/TOC.yml +++ b/docs/TOC.yml @@ -437,6 +437,8 @@ href: user-interface/controls/tableview.md - name: TimePicker href: user-interface/controls/timepicker.md + - name: TitleBar + href: user-interface/controls/titlebar.md - name: TwoPaneView href: user-interface/controls/twopaneview.md - name: WebView diff --git a/docs/user-interface/controls/media/titlebar/titlebar-full.png b/docs/user-interface/controls/media/titlebar/titlebar-full.png new file mode 100644 index 000000000..e05fdcc50 Binary files /dev/null and b/docs/user-interface/controls/media/titlebar/titlebar-full.png differ diff --git a/docs/user-interface/controls/media/titlebar/titlebar-overview.png b/docs/user-interface/controls/media/titlebar/titlebar-overview.png new file mode 100644 index 000000000..a8357a5de Binary files /dev/null and b/docs/user-interface/controls/media/titlebar/titlebar-overview.png differ diff --git a/docs/user-interface/controls/titlebar.md b/docs/user-interface/controls/titlebar.md new file mode 100644 index 000000000..b9eb453cf --- /dev/null +++ b/docs/user-interface/controls/titlebar.md @@ -0,0 +1,164 @@ +--- +title: "TitleBar" +description: "Learn how to use the .NET MAUI TitleBar, which provides the ability to add a custom title bar to your app on Windows." +ms.date: 10/15/2024 +monikerRange: ">=net-maui-9.0" +--- + +# TitleBar + +[![Browse sample.](~/media/code-sample.png) Browse the sample](/samples/dotnet/maui-samples/userinterface-titlebar) + +The .NET Multi-platform App UI (.NET MAUI) is a view that lets you to add a custom title bar to a to match the personality of your app. The following diagram shows the components of the : + +:::image type="content" source="media/titlebar/titlebar-overview.png" alt-text=".NET MAUI Titlebar overview." border="false"::: + +> [!IMPORTANT] +> is only available on Windows. Mac Catalyst support will be added in a future release. + + defines the following properties: + +- , of type , which specifies the control for the content that's centered in the title bar, and is allocated the space between the leading and trailing content. +- , of type , which represents the default template for the title bar. +- , of type , which specifies the foreground colour of the title bar, and is used as the color for the title and subtitle text. +- , of type , which represents an optional 16x16px icon image for the title bar. +- , of type , which specifies the control for the content that follows the icon. +- , of type `IList`, which represents a list of elements that should prevent dragging in the title bar region and instead directly handle input. +- , of type `string`, which specifies the subtitle text of the title bar. This is usually secondary information about the app or window. +- , of type `string`, which specifies the title text of the title bar. This is usually the name of the app or indicates the purpose of the window. +- , of type , which specifies the control that follows the `Content` control. + +These properties, with the exception of and , are backed by objects, which means that they can be styled, and be the target of data bindings. + +> [!IMPORTANT] +> Views set as the value of the , , and properties will block all input to the title bar region and will directly handle input. + +The standard title bar height is 32px, but can be set to a larger value. For information about designing your title bar on Windows, see [Title bar](/windows/apps/design/basics/titlebar-design). + +## Create a TitleBar + +To add a title bar to a window, set the property to a object. + +The following XAML example shows how to add a to a : + +```xaml + + ... + + + + + + + + +``` + +A can also be defined in C# and added to a : + +```csharp +Window window = new Window +{ + TitleBar = new TitleBar + { + Icon = "titlebar_icon.png" + Title = "My App", + Subtitle = "Demo" + Content = new SearchBar { ... } + } +}; +``` + +A is highly customizable through its , , and properties: + +```xaml + + + + + + + + + + + + +``` + +The following screenshot shows the resulting appearance: + +:::image type="content" source="media/titlebar/titlebar-full.png" alt-text=".NET MAUI Titlebar screenshot."::: + +> [!NOTE] +> The title bar can be hidden by setting the property, which causes the window content to be displayed in the title bar region. + +## TitleBar visual states + + defines the following visual states that can be used to initiate a visual change to the : + +- `IconVisible` +- `IconCollapsed` +- `TitleVisible` +- `TitleCollapsed` +- `SubtitleVisible` +- `SubtitleCollapsed` +- `LeadingContentVisible` +- `LeadingContentCollapsed` +- `ContentVisible` +- `ContentCollapsed` +- `TrailingContentVisible` +- `TrailingContentCollapsed` +- `TitleBarTitleActive` +- `TitleBarTitleInactive` + +The following XAML example shows how to define a visual state for the `TitleBarTitleActive` and `TitleBarTitleInactive` states: + +```xaml + + + + + + + + + + + + + + + + + + + + +``` + +In this example, the visual state sets the `BackgroundColor` and `ForegroundColor` properties to specific colors based on whether the title bar is active or inactive. + +For more information about visual states, see [Visual states](~/user-interface/visual-states.md). diff --git a/docs/whats-new/dotnet-9.md b/docs/whats-new/dotnet-9.md index d751de4d3..bcebd959b 100644 --- a/docs/whats-new/dotnet-9.md +++ b/docs/whats-new/dotnet-9.md @@ -49,11 +49,11 @@ For more information, see [HybridWebView](~/user-interface/controls/hybridwebvie ### Titlebar for Windows -The `TitleBar` control provides the ability to add a custom title bar to your app on Windows: +The control provides the ability to add a custom title bar to your app on Windows: :::image type="content" source="media/dotnet-9/titlebar-overview.png" alt-text=".NET MAUI Titlebar overview." border="false"::: -A `TitleBar` can be set as the value of the `Window.TitleBar` property on any `Window`: +A can be set as the value of the property on any : ```xaml @@ -62,12 +62,11 @@ A `TitleBar` can be set as the value of the `Window.TitleBar` property on any `W Icon="appicon.png" HeightRequest="46"> - + @@ -76,16 +75,19 @@ A `TitleBar` can be set as the value of the `Window.TitleBar` property on any `W An example of its use in C# is: ```csharp -Window.TitleBar = new TitleBar +Window window = new Window { - Title = "MAUI App", - Icon = "appicon.png", - HeightRequest = 46, - LeadingContent = new AvatarButton() + TitleBar = new TitleBar + { + Icon = "titlebar_icon.png" + Title = "My App", + Subtitle = "Demo" + Content = new SearchBar { ... } + } }; ``` -A `TitleBar` is highly customizable through its `Content`, `LeadingContent`, and `TrailingContent` properties: +A is highly customizable through its , , and properties: ```xaml @@ -119,6 +121,8 @@ The following screenshot shows the resulting appearance: > [!NOTE] > Mac Catalyst support for the `TitleBar` control will be added in a future release. +For more information, see [TitleBar](~/user-interface/controls/titlebar.md). + ## Control enhancements .NET MAUI 9 includes control enhancements. diff --git a/docs/whats-new/media/dotnet-9/titlebar-overview.png b/docs/whats-new/media/dotnet-9/titlebar-overview.png index 57d4a0be1..a8357a5de 100644 Binary files a/docs/whats-new/media/dotnet-9/titlebar-overview.png and b/docs/whats-new/media/dotnet-9/titlebar-overview.png differ