how to Customize Titlebar in winui 3?

[ghost1372]

The following methods are created in order:

1. using window.Extend... and window.SetTitlebar(element)
2. using AppWindow.Titlebar.Extend... and SetDragRegions(rects)

With version 1.4, new API were introduced for the title bar.

My question is, should we use the first method + InputNonClientPointerSource or the second method + InputNonClientPointerSource to use these new API?

I've seen the gallery codes and I'm a bit confused:

WinUI allows mix and match of higher level WinUI custom titlebar apis with lower level AppWindow and NonClientInputPointerSource apis for most cases.
One exception is one should not use Window.SetTitlebar api along with any lower level api which also sets drag regions as it can result in unexpected behavior.
If needed, set Window.SetTitlebar to null (default case) and proceed to use lower level apis for drag functionality.

but then in sample codes we can see Window.SetTitlebar is used!

Window window = App.MainWindow;
window.ExtendsContentIntoTitleBar = true;
window.SetTitleBar(AppTitleBar);
var nonClientInputSrc = InputNonClientPointerSource.GetForWindowId(window.AppWindow.Id);

// textbox on titlebar area
var txtBoxNonClientArea = UIHelper.FindElementByName(sender as UIElement, "AppTitleBarTextBox") as FrameworkElement;
GeneralTransform transformTxtBox = txtBoxNonClientArea.TransformToVisual(null);
Rect bounds = transformTxtBox.TransformBounds(new Rect(0, 0, txtBoxNonClientArea.ActualWidth, txtBoxNonClientArea.ActualHeight));

// Windows.Graphics.RectInt32[] rects defines the area which allows click throughs in custom titlebar 
// it is non dpi-aware client coordinates. Hence, we convert dpi aware coordinates to non-dpi coordinates
var scale = WindowHelper.GetRasterizationScaleForElement(this);
var transparentRect = new Windows.Graphics.RectInt32(
    _X: (int)Math.Round(bounds.X * scale),
    _Y: (int)Math.Round(bounds.Y * scale),
    _Width: (int)Math.Round(bounds.Width * scale),
    _Height: (int)Math.Round(bounds.Height * scale)
);
var rects = new Windows.Graphics.RectInt32[] { transparentRect };

nonClientInputSrc.SetRegionRects(NonClientRegionKind.Passthrough, rects); // areas defined will be click through and can host button and textboxes

https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/ControlPagesSampleCode/Window/TitleBar/TitleBarSample3.txt

Therefore, which one should we use to use the latest changes and the best method for customizing? Definitely, to calculate the drag areas, from the last method, but which one for customizing the titlebar?

@pratikone Since you made the latest changes to the gallery, can you help?

[DarranRowe]

It shouldn't matter, since as the release notes state Microsoft.UI.Xaml.Window.ExtendsContentIntoTitleBar uses the same implementation as Microsoft.UI.Windowing.AppWindowTitleBar.ExtendsContentIntoTitleBar.

However, there is an issue where:

    MainWindow::MainWindow()
    {
        ExtendsContentIntoTitleBar(true);
        bool extended = AppWindow().TitleBar().ExtendsContentIntoTitleBar(); //extended will be set to true.
    }

    MainWindow::MainWindow()
    {
        AppWindow().TitleBar().ExtendsContentIntoTitleBar(true);
        bool extended = ExtendsContentIntoTitleBar(); //extended will be set to false!!!
    }

So it is currently better to use Microsoft.UI.Xaml.Window.ExtendsContentIntoTitleBar.
However, Microsoft.UI.Xaml.Window.SetTitleBar is currently completely useless. It was used by the Window implementation of the custom title bar to tell Xaml what elements it should apply the custom title bar colours to. This isn't implemented in the newer custom title bar.

[ghost1372]

so we should use Microsoft.UI.Xaml.Window.ExtendsContentIntoTitleBar and we dont need to use Microsoft.UI.Xaml.Window.SetTitleBar.
and if we want to customize colours we can use Microsoft.UI.Windowing.AppWindowTitleBar.....?
right?

[Wenveo]

In fact, winui 3 doesn't provide a convenient way to customize the title bar.

So, I created a way to customize the title bar prior to WASDK 1.4 and it was simple and easy to use:
(using ExtendsContentIntoTitleBar and SetDragRectangles)

using System;
using System.Collections.Generic;

using Microsoft.UI.Windowing;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;

namespace App1.Controls;

public static class WinUITitleBar
{
    public static readonly DependencyProperty IsWindowTitleBarProperty =
        DependencyProperty.RegisterAttached("IsWindowTitleBar", typeof(bool),
            typeof(WinUITitleBar), new PropertyMetadata(false, OnIsWindowTitleBarChangedCallback));

    public static bool GetIsWindowTitleBar(Grid obj)
    {
        return (bool)obj.GetValue(IsWindowTitleBarProperty);
    }

    public static void SetIsWindowTitleBar(Grid obj, bool value)
    {
        obj.SetValue(IsWindowTitleBarProperty, value);
    }

    private static void OnIsWindowTitleBarChangedCallback(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        if (d is Grid titleBar)
        {
            void OnTitleBarLayoutUpdated(object? sender, object e)
            {
                // sender is null in here!?
                UpdateDragRegionForCustomTitleBar(titleBar);
            }

            titleBar.LayoutUpdated -= OnTitleBarLayoutUpdated;
            if (e.NewValue is bool b && b)
            {
                titleBar.LayoutUpdated += OnTitleBarLayoutUpdated;
            }
        }
    }

    private static void UpdateDragRegionForCustomTitleBar(Grid titleBar)
    {
        if (titleBar is not { IsLoaded: true, XamlRoot: { } xamlRoot })
        {
            return;
        }

        var columnDefinitions = titleBar.ColumnDefinitions;
        var columnDefinitionsCount = columnDefinitions.Count;

        var scaleAdjustment = xamlRoot.RasterizationScale;
        var dragRectsList = new List<Windows.Graphics.RectInt32>();

        int x = 0, height = (int)Math.Round(titleBar.ActualHeight * scaleAdjustment);
        for (var i = 0; i < columnDefinitionsCount; i++)
        {
            var column = columnDefinitions[i];
            var physicalWidth = (int)Math.Round(column.ActualWidth * scaleAdjustment);

            if (GetUIContentType(column) is WinUITitleBarUIContentType.Caption)
            {
                dragRectsList.Add(new() { X = x, Height = height, Width = physicalWidth });
            }

            x += physicalWidth;
        }

        var appWindowId = xamlRoot.ContentIslandEnvironment.AppWindowId;
        AppWindow.GetFromWindowId(appWindowId).TitleBar.SetDragRectangles([.. dragRectsList]);
    }

    public static readonly DependencyProperty UIContentTypeProperty =
        DependencyProperty.RegisterAttached("UIContentType", typeof(WinUITitleBarUIContentType),
            typeof(WinUITitleBar), new PropertyMetadata(WinUITitleBarUIContentType.Caption));

    public static WinUITitleBarUIContentType GetUIContentType(ColumnDefinition obj)
    {
        return (WinUITitleBarUIContentType)obj.GetValue(UIContentTypeProperty);
    }

    public static void SetUIContentType(ColumnDefinition obj, WinUITitleBarUIContentType value)
    {
        obj.SetValue(UIContentTypeProperty, value);
    }
}

public enum WinUITitleBarUIContentType
{
    // HTCATPION
    Caption,
    // CLIENT AREA
    Client
}

First, set the ExtendsContentIntoTitleBar to true in the main window.

// ....
public MainWindow()
{
    InitializeComponent();
    ExtendsContentIntoTitleBar = true;
}
// ....

And then we can define the custom title bar in xaml:

<!-- xmlns:ctrls="using:App1.Controls" -->

<Grid>
    <Grid.RowDefinitions>
        <!--  Title bar  -->
        <RowDefinition Height="Auto" />
        <!--  Client Area  -->
        <RowDefinition Height="*" />
    </Grid.RowDefinitions>

    <Grid Height="32" ctrls:WinUITitleBar.IsWindowTitleBar="True">
        <Grid.ColumnDefinitions>
            <!--  [0] Left Padding  -->
            <ColumnDefinition Width="4" ctrls:WinUITitleBar.UIContentType="Caption" />
            <!--  [1] Column of BackButton  -->
            <ColumnDefinition Width="Auto" ctrls:WinUITitleBar.UIContentType="Client" />
            <!--  [2] Padding  -->
            <ColumnDefinition Width=".2*" ctrls:WinUITitleBar.UIContentType="Caption" />
            <!--  [3] Column of SearchBox  -->
            <ColumnDefinition Width="*" ctrls:WinUITitleBar.UIContentType="Client" />
            <!--  [4] Padding  -->
            <ColumnDefinition Width=".4*" ctrls:WinUITitleBar.UIContentType="Caption" />
            <!--  [5] Right Padding  -->
            <ColumnDefinition Width="192" ctrls:WinUITitleBar.UIContentType="Caption" />
        </Grid.ColumnDefinitions>

        <Button
            Grid.Column="1"
            Width="32"
            Height="32"
            Padding="8">
            <Viewbox Width="12" Height="12">
                <SymbolIcon Symbol="Back" />
            </Viewbox>
        </Button>

        <AutoSuggestBox
            Grid.Column="3"
            PlaceholderText="Search..."
            QueryIcon="Find" />
    </Grid>

</Grid>

We use "Client" to indicate that the column is in the client area, "Caption" is in the title bar. (If that column is "Caption", then elements in that column cannot be interacted with.)

Grid	Column0	Column1	Column2	Column3	Column4	Column5
	[Left Padding]	BackButton	[Padding]	SearchBox	[Padding]	[Right Padding]
Type	Caption	Client	Caption	Client	Caption	Caption

This is a way to customize the title bar based on the grid and columns, and it's done with attached properties, but importantly, it's not complicated and easy to use (I think^^).

This copy from my repo, you can get it in WinUITitleBar.cs .

[ghost1372]

@Wenveo Why make things difficult when they are so simple?

winui 3 now support interactive elements and use AppWindow Titlebar customization so we can define drag regions with new api and calculating drag regions is so much easy.
i suggest you check my codes:
https://github.com/WinUICommunity/WinUICommunity/blob/main/dev/Components/Controls/Labs/TitleBar/TitleBar.WASDK.cs

public void SetDragRegion(NonClientRegionKind nonClientRegionKind, params FrameworkElement[] frameworkElements)
    {
        var nonClientInputSrc = InputNonClientPointerSource.GetForWindowId(Window.AppWindow.Id);
        List<Windows.Graphics.RectInt32> rects = new List<Windows.Graphics.RectInt32>();
        var scale = GetRasterizationScaleForElement(this);

        foreach (var frameworkElement in frameworkElements)
        {
            GeneralTransform transformElement = frameworkElement.TransformToVisual(null);
            Windows.Foundation.Rect bounds = transformElement.TransformBounds(new Windows.Foundation.Rect(0, 0, frameworkElement.ActualWidth, frameworkElement.ActualHeight));
            var transparentRect = new Windows.Graphics.RectInt32(
                _X: (int)Math.Round(bounds.X * scale),
                _Y: (int)Math.Round(bounds.Y * scale),
                _Width: (int)Math.Round(bounds.Width * scale),
                _Height: (int)Math.Round(bounds.Height * scale)
            );
            rects.Add(transparentRect);
        }
        
        nonClientInputSrc.SetRegionRects(nonClientRegionKind, rects.ToArray());
    }

[Wenveo]

I used it for a long time before 1.4, and it was highly customizable and very simple.
I saw the new api later, but didn't have any more details or examples. So I didn't use it and focused on other work.

But anyway, thanks for you suggest and codes! I'll try to use the new api later ^^.

[0x427279]

The link to the file referenced by @ghost1372 above is broken, but here's an updated one...

https://github.com/WinUICommunity/WinUICommunity/blob/main/dev/Components/Controls/Ported/TitleBar/TitleBar.WASDK.cs

[agat366]

There seems a bug with NonClientRegionKind.Icon of InputNonClientPointerSource.SetRegionRects. While NonClientRegionKind.Passthrough works well, the .Icon mode does apply clickable area within the element rect provided. But only until the window is dragged holding the title bar. Right after that the icon area reduces to the initial one and stays the same until SetRegionRects is called again (on the bar resized etc.)

[ghost1372]

i think you should create a new issue for tracking mentationed issue

[Jay-o-Way]

WASDK 1.6 will have https://learn.microsoft.com/windows/apps/windows-app-sdk/experimental-channel#new-titlebar-control 🥳