[Windows] Add TitleBar Control

[Foda]

This PR is a draft and seeking API feedback for an initial release

Description of Change

This PR adds a new TitleBar control and API to set the TitleBar on a Window. It currently only applies to the Windows platform, but it's built entirely as a MAUI control to allow macOS support later.

Please read the full API description here: #13023

Feature demo (PlatformSpecifics page in Maui.Controls.Sample):

titlebar.mp4

API/Usage

The primary API is the Window.SetTitleBar function -- which removes the TitleBar control from the visual tree and inserts it as the native TitleBar (this approach was shamelessly copied from the WinAppSDK). This was used vs an attached property (ex: <Window.TitleBar>) because it was difficult to get a valid Window object when the property was first set.

Example using XAML:

MainWindow.xaml

<Window.TitleBar>
  <TitleBar
    x:Name="TeamsTitleBar"
    HeightRequest="46"
    Title="Hello World">
    <TitleBar.Content>
      <Entry
        x:Name="SearchTitleBar"
        Placeholder="Search"
        VerticalOptions="Center"
        MinimumWidthRequest="300"
        MaximumWidthRequest="450"
        HeightRequest="32"/>
    </TitleBar.Content>
  </TitleBar>
</Window.TitleBar>

Example using code

MainPage.xaml.cs

protected override void OnAppearing()
{
    base.OnAppearing();
    
    Window.TitleBar = new TitleBar()
    {
        Title = "MAUI App",
        Icon = "appicon.png",
        LeadingContent = new AvatarButton()
    };
}

Issues Fixed

Fixes #13023

[tj-devel709]

Wow this is super cool! Few questions from me!

[drasticactions]

This PR adds a new TitleBar control and API to set the TitleBar on a Window. It currently only applies to the Windows platform, but it's built entirely as a MAUI control to allow macOS support later.

How do we plan to add support for this with Catalyst?

If you want to use something like NSToolbarDelegate to build a title bar like this:

That uses specific NSToolBar items and a layout system where you set identifiers and set the flexibility of where items should appear. The TitleBar API allows for arbitrary existing controls and layout which AFAIK wouldn't work with that delegate.

So if you want arbitrary controls, you would probably need to do something special with the UIWindow, merge the title bar into the inner content, and handle the managing the layout yourself. Or there could be other ways to create a more "native" looking titlebar on Catalyst that uses arbitrary controls. Making sure we have a plan for that now before deciding on this approach only to see it won't work on MacOS wouldn't be ideal.

[Foda]

This PR adds a new TitleBar control and API to set the TitleBar on a Window. It currently only applies to the Windows platform, but it's built entirely as a MAUI control to allow macOS support later.

How do we plan to add support for this with Catalyst?

If you want to use something like NSToolbarDelegate to build a title bar like this:

That uses specific NSToolBar items and a layout system where you set identifiers and set the flexibility of where items should appear. The TitleBar API allows for arbitrary existing controls and layout which AFAIK wouldn't work with that delegate.

So if you want arbitrary controls, you would probably need to do something special with the UIWindow, merge the title bar into the inner content, and handle the managing the layout yourself. Or there could be other ways to create a more "native" looking titlebar on Catalyst that uses arbitrary controls. Making sure we have a plan for that now before deciding on this approach only to see it won't work on MacOS wouldn't be ideal.

Yeah, we did talk briefly about this. One of the reasons why I made it a native MAUI control was so that we could just plop it into the "titlebar area" on both Win and Mac. I know it's possible to draw whatever custom control you want in the TitleBar (see: Edge w/ tabs) but I'm not sure what API does that, or what exactly the behavior is (maybe https://developer.apple.com/documentation/uikit/mac_catalyst/removing_the_title_bar_in_your_mac_app_built_with_mac_catalyst ??).

I'm going to play around today to see how that API works

[Foda]

@drasticactions here's what it looks like using that API + NavigationPage.TitleView:

I couldn't quite figure out how to get the NavigationBar to not have that top padding -- someone more familiar w/ macOS layout constraints would be able to figure it out. But other than the top margin, it works as expected: controls in that are can be clicked, etc, without breaking the drag behavior.

[Foda]

/rebase

[Foda]

/rebase

[MartyIX]

Would it be better to use file-scope namespaces in new files?

[MartyIX]

This change does not look like it is needed.