What’s New in .NET MAUI 9 – Window TitleBar

Window TitleBar is one of the two prominent enhancements in .NET MAUI 9, the recently released major version of the cross-platform App UI framework.

The other new feature is HybridWebView, consult this article titled Exploring .NET MAUI 9 – HybridWebView to delve into the details of this new control.

An article that comprehensively outlines the significant features of this version has already been published and is accessible here.

The Window type defines two properties – Page and TitleBar.

Page:

In .NET MAUI 9, the MainPage property of the Application class is now obsolete, replaced by the Page property of the Window class to accommodate this new TitleBar feature for the Desktop (Windows and Mac Catalyst). To know more about this MainPage change, refer to this article.

TitleBar:

Features:

• Same look and feel of the Store apps
• Tall TitleBar
• Host controls on the TitleBar
• Support for Mac Catalyst is coming soon. Track here
  • Update: Released as part of .NET MAUI 9 SR4 – v9.0.40

Properties:

For understanding, the area displaying the Title, Subtitle, and Icon is referred to as the App Info section.

Apart from ForegroundColor, all other attributes are listed in their order of appearance.

All of these properties are bindable.

• ForegroundColor – of type Color
  • The forecolor of the title bar and is used as the color for the Title and Subtitle text.
• Icon – of type ImageSource
  • An optional 16x16px icon image for the title bar.
• Title – of type string
  • The title text of the title bar.
• Subtitle – of type string
  • The subtitle text of the title bar.
• LeadingContent – of type IView
  • These controls that follow the App Info section.
• Content – of type IView
  • These controls centered in the title bar
  • The region between Leading and Trailing sections.
• TrailingContent – of type IView
  • These controls follow the Content region and before the Caption controls.

Since TitleBar is derived from TemplatedView, it inherits all the properties of the foundational types, such as VisualElement and View, including attributes such as BackgroundColor, Height, and others.

Note: The TitleBar can be hidden by setting the IsVisible property to false, which causes the window content to be displayed in the title bar region.

Customization:

A title bar is extensively customizable through its properties: Content, LeadingContent, and TrailingContent, all of which are of type IView.

One may assign either a singular View or a collection of Views contained within a Layout to these properties.

Views incorporated into these three sections will prevent any interaction with the title bar region and will directly manage input.

Tall TitleBar:

The standard height of the title bar is 32px; however, it may be adjusted to a larger value to style your desktop apps to match the aesthetic of Store apps.

The Microsoft Store app is a WinUI app that incorporates a tailored title bar, which includes a Search control embedded within it. The target platform of .NET MAUI for Windows is WinUI, thus facilitating the development of such apps utilizing .NET MAUI.

Implementation:

The TitleBar can be defined in both XAML and C#.

The primary window of the App can be created and returned via the Application’s CreateWindow() method. Furthermore, additional windows may be instantiated as necessary, employing the ActivateWindow() method to bring them to the forefront.

Application.Current?.ActivateWindow(new MyWindow());

XAML:

<Window
    x:Class="MyApp.MyWindow"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:vw="clr-namespace:MyApp.Views"
    Title="MyApp">
    <Window.Page>
        <vw:MainPage />
    </Window.Page>
    <Window.TitleBar>
        <TitleBar
            Title="MyApp"
            BackgroundColor="{StaticResource Primary}"
            ForegroundColor="{StaticResource White}"
            HeightRequest="48"
            Subtitle="Home">
            <TitleBar.Content>
                <SearchBar
                    BackgroundColor="{StaticResource White}"
                    HorizontalOptions="Fill"
                    MaximumWidthRequest="300"
                    Placeholder="Search"
                    VerticalOptions="Center" />
            </TitleBar.Content>
            <TitleBar.TrailingContent>
                <ImageButton
                    Background="Transparent"
                    BorderWidth="0"
                    HeightRequest="36"
                    WidthRequest="36">
                    <ImageButton.Source>
                        <FontImageSource
                            FontFamily="FAS"
                            Glyph="&#xf013;"
                            Size="18" />
                    </ImageButton.Source>
                </ImageButton>
            </TitleBar.TrailingContent>
        </TitleBar>
    </Window.TitleBar>
</Window>

C#:

All types that derive from VisualElement possess access to the Window property. Create a new TitleBar instance and assign it to the Window’s TitleBar property.

It is imperative to access the Window property of the Page when it is ready to render within the UI events such as OnAppearing or OnNavigatedTo. Otherwise, it would be null.

// Assuming a static using statement is included for Colors
Window.TitleBar = new TitleBar()
{
    BackgroundColor = Color.FromArgb("#512BD4"),
    ForegroundColor = White,
    Height = 48, // Tall TitleBar
    Title = "MyApp",
    Subtitle = "Home",
    Content = new SearchBar()
    {
        BackgroundColor = White,
        HorizontalOptions = LayoutOptions.Fill,
        MaximumWidthRequest = 300,
        Placeholder = "Search",
        VerticalOptions = LayoutOptions.Center,
    },
    TrailingContent = new ImageButton()
    {
        Background = new SolidColorBrush(Transparent),
        BorderWidth = 0d,
        Height = 36,
        Source = new FontImageSource()
        {
            FontFamily = "FAS",
            Glyph = "\xf013",
            Size = 18,
        },
        Width = 36,
    },
};

Output:

Open Points:

• The BindingContext assigned to the TitleBar is not propagated to its three child Content sections – Track here
• The font-related properties of both the Title and the Subtitle are not subject to customization – Track here
  • As you can observe, the size of the Title and Subtitle are minute
  • The possible workaround would be to configure it as the LeadingContent.
  • While doing so, it is advisable to refrain from using the default Icon property, as it renders after the LeadingContent, instead include an Image control to the LeadingContent section and align it
• The LeadingContent of the TitleBar appears before the App Info section – Issue logged – Track here
• There is no straightforward option to control the Window style and Caption controls such as disabling the Maximize button.
  • Using Win32 API P/Invoke is a possible workaround

Further Reading:

• TitleBar for Windows
• TitleBar
• TitleBar Design Guidance

Happy coding. Stay connected as we continue to learn and share the experiences from this exciting journey of being a .NET developer.