🧪 TitleBar

[niels9001]

TitleBar

Problem Statement

With the refreshed design of Windows 11, the preferred window titlebar has changed as well. To replicate this experience, can be time consuming and requires a lot of XAML + code-behind to get right.

Inspiration

Proposed Solution

A control, defined in XAML, that contains all required properties to create a modern titlebar experience. It would automatically handle all the required code behind APIs (like ExtendContentIntoTitlebar) for both UWP and WinAppSDK

Properties:

Property name	Type	Comments
Header	object	Any object to be hosted at the far left of the control
Icon	IconElement	App icon
Title	string	App title
Subtitle	string	For displaying additional text (e.g. release branch)
Content	object	For displaying (interactive) xaml element (e.g. AutoSuggestBox)
Footer	object	For displaying additional content next to the caption buttons (e.g. account button)
IsBackButtonVisible	bool	To show/hide the back button
IsPaneToggleButtonVisible	bool	To show/hide the menu button
Mode	enum	Compact (default) - Expanded
Window	Window	WinAppSDK only - we cannot use CoreApplicationView

Events	Comments
BackButtonClick	The back button is clicked
PaneToggleButtonClick	The menu button is clicked.

Layouts

XAML

<controls:TitleBar Icon="ms-appx:///Assets/AppTitleBar.png" Title="Toolkit Labs Gallery" Subtitle="Preview"              IsPaneButtonVisible="True"  IsBackButtonVisible="True">
            <controls:TitleBar.Content>
                <AutoSuggestBox />
            </controls:TitleBar.Content>
            <controls:TitleBar.Footer>
                <PersonPicture Initials="MS" />
            </controls:TitleBar.Footer>
</controls:TitleBar>

When the window is smaller, the Title and SubTitle components should collapse:

Expanded mode: 48px height
Compact mode (default): 32px height

Working branch: https://github.com/CommunityToolkit/Tooling-Windows-Submodule/pull/88/files

Open Questions

• Do we need a Header property to display custom content left of the Icon?
• Would we need support for TabView type of layouts in a V1?

API Reference Docs

[- Expander](https://learn.microsoft.com/en-us/windows/apps/develop/title-bar?tabs=wasdk)

References

https://learn.microsoft.com/en-us/windows/apps/design/basics/titlebar-design

[ghost1372]

Wow... I am really looking forward to this experiment
I hope this title bar also supports the mode used by WinUI Gallery (NavigationView + TitleBar)

[niels9001]

Yes, that is the goal.. you'd hide the PaneToggleButton on the NavigationView and show the PaneToggleButton of the TitleBar instead.. see updated image above

[ghost1372]

Great😍

[niels9001]

Working branch with an initial PR to get the logic into the sample app. Once tested, we can spin this out into a dedicated Labs Experiment: https://github.com/CommunityToolkit/Tooling-Windows-Submodule/pull/88/files

[ghost1372]

One more questions...
Which method will be used for titlebar?
Window.setTitleBar()
Or
Window.AppWindow.TitleBar
Or both?
And do we have access to PreferredHeightOption property?
Tnx

[dongle-the-gadget]

AppWindow.TitleBar has been supported on Windows 10 since Windows App SDK 1.2

[ghost1372]

[bogdan-patraucean]

The documentation is not updated. @ghost1372 , it's fully supported.

[ghost1372]

oh tnx

[dongle-the-gadget]

IIRC Color support on the standard DWM drawn title bar is not supported, but setting colors on the title bar buttons when using ExtendsContentIntoTitleBar is supported.

[Pdawg-bytes]

100% agree. I think this will make it a lot easier to get a basic app up and running, just like the days of UWP. It was great being able to make an app look good in 5 minutes. I'm all for it!

[bogdan-patraucean]

I would be a fan of this and probably use it, if not directly, at least as an inspiration. Must haves would be the following two aspects:

• proper theming support with automatic updates of the colors when the theme is changed from the OS or from the app, including the caption button colors when hovering and caption button icons
• draggable areas so we don't have to calculate it ourselves if we put a SearchBox in the Content area, for example

Header and Footer are not suggestive as namings because this terminology is mainly used for content that's displayed vertically, not horizontally but it might work well anyway. Header is not necessary, I consider, and, without it, we can have another name for Footer, maybe one of these ideas:

• Right
• RightSide
• More
• Extra
• NearCaptions
• Caption

Tab support would be awesome, but maybe added later.

One question I would have, any chance this issue can get fixed with the reusable control?

Great idea, @niels9001 , it's nice to see contributions like this that might help the community. I also see it as a step into the right direction of having consistent titlebars across Windows native apps.

[ghost1372]

MS itself uses header and footer for TabView:
TabStripHeader, TabStripFooter
it is Good to have both Header and Footer.

[ghost1372]

I can see different modes in the provided images, if we use the NavigationView with Top mode and have all those options (Header, Footer, SearchBox, Icon etc.), what will the situation be? How will the elements act?

[niels9001]

@ghost1372 To keep things simple, I would not try to integrate with NavigationView at all? The current approach is the ability to set the IsPaneToggleButtonVisible property to show a NavigationView pane togglebutton.. the dev would then hide it on the NavigationView itself. Would love to hear your thoughts on this!

[ghost1372]

I really appreciate the simplicity, I think we can consider this for future versions like TabView, or at least give the user the possibility to manage the elements themselves, such as hiding

[niels9001]

Yep, I think having great samples of what would look for common layouts would be very helpful. With TabView would be a complicated one for us.

Maybe we can provide a set of titlebar helpers that would atleast make this very simple in case you want to build something yourself.

[ghost1372]

Hi @niels9001
any news?

There are some things that should be considered

1. Support NavigationView with PaneDisplayMode="Top"
2. RTL Support (Both Content and TitleBar)
3. RTL Support (Only Content)

Right-to-left languages create their apps in two ways:

1.The whole app from right to left == In this option, the titlebar and content are created from right to left

2.TitleBar from left to right and content from right to left

In these cases, it is better for the navigation view to function properly

[niels9001]

I hope to wrap up the initial PR for the sample app today with all core logic integrated.. after that I'll create a new Labs experiment for other to give feedback on.

[niels9001]

Experiment is in draft PR.. I believe I have the fundamentals + UI logic working for both UWP and WASDK :-)!

Would love to get feedback!

#459

[ghost1372]

Hi @niels9001

Isn't it better to set the icon and title in the AppWindow and window itself?

Window.Title = TitleText;
Window.AppWindow.Title = TitleText;
Window.AppWindow.SetIcon(Icon); // icon (*.ico)

[niels9001]

Yeah, the TitleBar doesn't do that. Not sure if we want to as it might override things alway? E.g. you might want to have a dofferent text label of your window vs. what taskbar shows you?

If so - it should be something that is added to the "full sample" though - two lines for devs to manually set.

[Jay-o-Way]

As mentioned, the words "header" and "footer" are a no-go. They sound too "vertical". MS docs has a page on using a fully custom titlebar, with examples. We can/should follow that as much as possible.

It's a personal preference of mine to use Spacings in favor of margins. In my (recent) experience, ColumnSpacing=16 works great! And VerticalAlign=Center always looks good to me. 👍🏻

[niels9001]

Yeah, it's not the best naming - but I also cannot come up with a better alternative.

Additionally, TabView uses TabViewHeader and TabViewFooter as well - which is pretty similiar.

[Jay-o-Way]

MS example:

            <Grid.ColumnDefinitions>
                <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
                <ColumnDefinition x:Name="IconColumn" Width="Auto"/>
                <ColumnDefinition x:Name="TitleColumn" Width="Auto"/>
                <ColumnDefinition x:Name="LeftDragColumn" Width="*"/>
                <ColumnDefinition x:Name="SearchColumn" Width="Auto"/>
                <ColumnDefinition x:Name="RightDragColumn" Width="*"/>
                <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
            </Grid.ColumnDefinitions>

https://learn.microsoft.com/nl-nl/windows/apps/develop/title-bar?tabs=wasdk#full-customization-example

Best to copy

[Jay-o-Way]

[niels9001]

Yes, see GIF: #459

[YourOrdinaryCat]

The UWP TitleBar customization APIs are pretty good, but they do miss a few things. Namely, there is no reliable way to know whether the user wants to see their accent color in the TitleBar:

https://www.elevenforum.com/t/turn-on-or-off-show-accent-color-on-title-bars-and-windows-borders-in-windows-11.1149/

I've seen many users complaining because UWP apps specifically don't respect this preference. The article above shows a way to adjust the setting from the registry, which could make respecting this preference viable for WinUI 3 apps.

Not sure how the API would look like, something along the lines of AccentAdjustedBackground maybe? And a few events for when the setting is enabled/disabled.

Another alternative would be having an AccentAdjustmentMode, with the developer being able to choose between Auto (color the background internally and fire the events), Manual (the developer handles the events themselves), or Disabled (no internal adjustments, the events are never fired).

[Jay-o-Way]

IsBackButtonVisible bool

@niels9001 the "original" value/type isn't a bool but an enum: 0,1,Auto

[niels9001]

@Jay-o-Way Do you mean UWP window back button?

Not sure if it's still there - but a Window has access to the navigation history and could show the back button if there were still items listed in the history.

This is a basic control - with no sense of nav history. So not sure what 'Auto' would do here? (I believe NavigationView is using bool as well)

[Jay-o-Way]

UWP, WinRt, WinUI... 🤷‍♂️ Just saying. I learned it via microsoft/microsoft-ui-xaml#8521
Bool ≠ enum

[ghost1372]

Hi @Jay-o-Way
I want to start working on Tabbed Titlebar. And we should use TabView.TabStripFooter as a draggable area. There are a few questions that should be clear.
1.What should we do with some of the properties like Footer, Content,....?
Disable them all? If not, how and where should we use them?

2.how should we use tabview in titlebar?

A static method?without xaml? Which define draggable area for a tabview?
TitleBar.SetTabView(tabview)
Or we should use xaml stuff?

<Titlebar.Tabview>

</TitleBar.Tabview>

[ghost1372]

i created a blank project with tabbed titlebar, and it seems that working fine😁
i need some advice, for example:
for margin from Right side (Caption Buttons), i used this code which is equile to File Explorer margin i dont know is this a good option?
int CaptionButtonOcclusionWidthRight = titleBar.RightInset + 20;
also i tested with:
int CaptionButtonOcclusionWidthRight = titleBar.RightInset * scale;
but margin is more than File Explorer!
should we use LeftInset for RTL situation?

Tabbed Titlebar is done with TabStripFooter, this means our drag region defined inside TabStripFooter.
Should we add Header in TabStripHeader, and Footer in TabStripFooter?

[cricketthomas]

Would you mind sharing the xaml for this? or the repo? Thanks

[ghost1372]

Xaml:

<Window x:Class="App4.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:local="using:App4"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        Title="App4"
        mc:Ignorable="d">

    <Grid x:Name="MainGrid">
        <TabView>
            <TabView.TabStripFooter>
                <Grid x:Name="CustomDragRegion"
                      Background="Red"
                      IsHitTestVisible="False"
                      Loaded="CustomDragRegion_Loaded"
                      SizeChanged="CustomDragRegion_SizeChanged" />
            </TabView.TabStripFooter>
            <TabView.TabItems>
                <TabViewItem Header="TabItem1">
                    <TextBlock Text="Item 1" />
                </TabViewItem>
                <TabViewItem Header="TabItem2" />
            </TabView.TabItems>
        </TabView>

    </Grid>
</Window>

C#:

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();


        if (!AppWindowTitleBar.IsCustomizationSupported())
        {
            // Why? Because I don't care
            throw new Exception("Unsupported OS version.");
        }

        var titleBar = AppWindow.TitleBar;

        ExtendsContentIntoTitleBar = true;
        var btnColor = Colors.Transparent;
        titleBar.BackgroundColor = btnColor;
        titleBar.ButtonBackgroundColor = btnColor;
        titleBar.InactiveBackgroundColor = btnColor;
        titleBar.ButtonInactiveBackgroundColor = btnColor;
    }

    private void CustomDragRegion_SizeChanged(object sender, SizeChangedEventArgs e)
    {
        UpdateDragRegion();
    }

    private void CustomDragRegion_Loaded(object sender, RoutedEventArgs e)
    {
        UpdateDragRegion();
    }
    public double GetRasterizationScaleForElement(UIElement element)
    {
        return element.XamlRoot?.RasterizationScale ?? 0.0;
    }

    private void UpdateDragRegion()
    {
        double scaleAdjustment = GetRasterizationScaleForElement(MainGrid);

        CustomDragRegion.Measure(new Size(double.PositiveInfinity, double.PositiveInfinity));
        var customDragRegionPosition = CustomDragRegion.TransformToVisual(null).TransformPoint(new Point(0, 0));

        List<Windows.Graphics.RectInt32> dragRectsList = new();

        Windows.Graphics.RectInt32 dragRectL;
        dragRectL.X = (int)(customDragRegionPosition.X * scaleAdjustment);
        dragRectL.Y = (int)(customDragRegionPosition.Y * scaleAdjustment);
        dragRectL.Height = (int)((CustomDragRegion.ActualHeight - customDragRegionPosition.Y) * scaleAdjustment);
        dragRectL.Width = (int)((CustomDragRegion.ActualWidth / 2) * scaleAdjustment);
        dragRectsList.Add(dragRectL);

        Windows.Graphics.RectInt32 dragRectR;
        dragRectR.X = (int)((customDragRegionPosition.X + CustomDragRegion.ActualWidth / 2) * scaleAdjustment);
        dragRectR.Y = (int)(customDragRegionPosition.Y * scaleAdjustment);
        dragRectR.Height = (int)((CustomDragRegion.ActualHeight - customDragRegionPosition.Y) * scaleAdjustment);
        dragRectR.Width = (int)((CustomDragRegion.ActualWidth / 2) * scaleAdjustment);
        dragRectsList.Add(dragRectR);

        Windows.Graphics.RectInt32[] dragRects = dragRectsList.ToArray();

        AppWindow.TitleBar.SetDragRectangles(dragRects);
    }
}

[ghost1372]

@Jay-o-Way @AnalogFeelings

[ghost1372]

also, for using wasdk v1.4 i used VisualTreeHelper for finding AddButton and TabViewListView for calculating Drag Regions, code is simple but should we use VisualTreeHelper or we can just copy Style from https://github.com/microsoft/microsoft-ui-xaml/blob/winui3/release/1.4-stable/controls/dev/TabView/TabView.xaml?

https://github.com/microsoft/microsoft-ui-xaml/blob/685d2bfa86d6169aa1998a7eaa2c38bfcf9f74bc/controls/dev/TabView/TabView.xaml#L4-L50

[Jay-o-Way]

Hey @ghost1372, lots of questions! :) I don't know the answer for the most of them. Niels should be able to answer more. My thoughts:

• CaptionButtonOcclusionWidthRight -> Not sure, but hardcoding numbers is often not the best. But I don't know if there's any variable to be found somewhere.
• use LeftInset for RTL situation -> Usually it's best to leave as much as possible to the framework. It should automatically reverse the order.
• Should the Footer stick to the tabs or to the right side?

[Euclidite]

This is looking great! One piece of feedback - it would be nice if it would be possible for this control to natively support:

• Individually hiding the caption buttons
• Individually disabling the caption buttons

I'm working on a few enterprise applications where the application is a "floating" status pane, where we still want the user to grab/drag it like they're used to with normal windows, but we don't want them closing the window. Disabling is an option, but there's also space constraints which make it less than ideal to show the caption buttons.

[ghost1372]

You can use winui new titlebar control
Introduced in v1.6-exp1

[Euclidite]

That's what brought me here - I didn't see they supported my above request, and the announcement mentioned that they solicited feedback from this discussion page - if there's a better place to leave this feedback let me know.

[ghost1372]

That's what brought me here - I didn't see they supported my above request, and the announcement mentioned that they solicited feedback from this discussion page - if there's a better place to leave this feedback let me know.

Take a look here
microsoft/microsoft-ui-xaml#9700