TitleBar API feedback

[dotMorten]

Summary

I'm looking at the new TitleBar, and while functionally and visually I LOVE it, I have some concerns about the API itself.

First of all, the naming of Header and Footer is very misleading. Those names typically refer to top/bottom items, and the entire control in-of-itself is a header control. I looked at those properties and couldn't at all guess what they really were for, until I saw this image:

Generally I'd prefer naming that allows you do an informed guess what they do, and in the community call several people were confused about this.

So these are left/right, and I'm not actually sure if Header is before or after those buttons (illustration doesn't make that clear). Header also clashes with the Title here, adding extra confusion.

My second (albeit slightly lesser) concern is the use of Pane and Back buttons. It's extremely opinionated, and I worry we're gonna get too many apps looking too identical. I'd rather this was a Button collection of sorts instead, where I could choose to add some buttons, or choose to just put them in the "Headers" content (pending a better name). If I needed a 3rd button there I'm out of luck.

Then there's the TitlebarTemplateSettings class:

I find this a bit weird. When I think template, I think control templates, but this appears to just be a way to set the app icon - why not just set the icon on the TitleBar directly? But more importantly I think that this should be a Window property (not AppWindow, but Window Window!) that also applies if I don't use the TitleBar.

Another approach is perhaps providing a MUCH simpler titlebar control that just takes care of allowing you to interact with buttons and textboxes etc, while still being able to drag the rest, but you own the entire content as a single content item. Then you add a secondary subclass of that titlebar that adds this more opionated version to cover some common scenarios.

[lolametro]

They probably wanted to avoid Left/Right due to RTL languages. Usually it would then be called Begin and End.

[riverar]

Agree with the commentary above. To add:

Header and Footer are very confusing. One proposal is to align with Microsoft Fluent components, which use [Content]Before and [Content]After (https://react.fluentui.dev/?path=/docs/components-input--default#content-before-after). This terminology is also suitable for right-to-left languages.

It's also confusing this isn't just part of Window, so that things like setting the icon are naturally wired up to WM_SETICON.

[dotMorten]

Yeah being able to write

<Window>
    <Window.TitleBar>
         <TitleBar />
    </Window.TitleBar>
</Window>

would have been way more intuitive, but unfortunately the baseclass of Window is wrong and prevents this.

[MikeHillberg]

That property element syntax is OK on Window; that's a general Xaml language syntax and not specific to DO. E.g. you can do

<Window>
    <Window.Title>
        My Window Title
    </Window.Title>
</Window>

[dotMorten]

@MikeHillberg Yes but now you can't evaluate binding context. The thing falls apart a soon as you want to bind etc:

<Window>
    <Window.TitleBar>
         <TitleBar Subtitle="{Binding CurrentOpenFile}" />
    </Window.TitleBar>
</Window>

Not to mention your example above didn't even work until very recently and had to be set in code-behind ;D

[mdtauk]

What would be the best practice to use this TitleBar control, along with a TabView control, where the tabs are not a drag region, but the bar where the tabs are contained, is draggable?

Titlebar's Tall mode would fit well with the TabView, but can you collapse the Header, Icon, Title, Subtitle parts, so content takes up more space?

[moshegutman]

Leading/Trailing instead of Header/Footer would work for RTL too.

That's what Apple does: https://developer.apple.com/documentation/swiftui/toolbaritemplacement/topbarleading

[BreeceW]

My second concern is the use of Pane and Back buttons. It's extremely opinionated, and I worry we're gonna get too many apps looking too identical. I'd rather this was a Button collection of sorts instead, where I could choose to add some buttons, or choose to just put them in the "Headers" content (pending a better name). If I needed a 3rd button there I'm out of luck.

I agree that the pane button is too opinionated and having a button collection instead would be good, but the back button makes sense as a dedicated option. Uniformity there is good and provides a direct alternative to the old CoreWindow back button from UWP. The back button also has a different style that makes sense only for the back button (goes all the way to the edges, like caption buttons), so it’s good that it’s distinct.

[roxk]

It's extremely opinionated, and I worry we're gonna get too many apps looking too identical.

It being opinionated is a good thing. Windows has been blamed for its inconsistency for a long time and enforcing some kind of consistency is good here. Devs who wish to have custom button collections could always implement their own. I find it wise to leave the official default to represent "what we want devs to do". That's the point of the title bar control - to make apps look the same according to the fluent guideline.

(In fact, you can argue navigation view etc also suffer from this "all apps look the same" problem, but again this is a good thing to have uniformity/consistency. The biggest benefit of consistency is users familiarity)

[AndrewKeepCoding]

First of all, the naming of Header and Footer is very misleading.

At least, it's consistent with the NavigationView's TopPane.

[dotMorten]

At least, it's consistent with the NavigationView's TopPane.

I'd argue that's just as confusing. I can see the consistency argument to some extent, but we could also break with it before it becomes a pattern.

[AndrewKeepCoding]

I'd argue that's just as confusing. I can see the consistency argument to some extent, but we could also break with it before it becomes a pattern.

I see. It's still in experimental preview. Everything is possible. Then I hope it gets simpler as you suggest in your comment above.

[dotMorten]

It's still in experimental preview. Everything is possible

Yeah hopefully the design isn't settled yet. I assume the experimental previews are here for not just bug testing, but also so we have a chance to give feedback on the overall features, hence this issue.

[mdtauk]

It's still in experimental preview. Everything is possible

Yeah hopefully the design isn't settled yet. I assume the experimental previews are here for not just bug testing, but also so we have a chance to give feedback on the overall features, hence this issue.

I think this control is trying to match the Design guidance the WinUI team put in the Figma toolkit some time ago - and match what the product teams have been doing with their custom Title Bars.

The only pre-existing use case that comes to mind is having a TabView in the titlebar region.

Maybe a button collection would enable something like OneNote

Things like Visual Studio Code are already possible with the TitleBar control as is

[ghost1372]

I am comfortable with the current design, however renaming the header and footer will be better, but I disagree with simplifying the title bar and removing the pane button, if you want to put more buttons you can use Header property. or if you dont need pane button, just Hide it. (IsPaneToggleButtonVisible). There is nothing wrong with the programs being similar.
Do not forget that the title bar is an optional control and is not mandatory. If you need more or simpler items, you can create your own title bar. or If you need various changes, maybe using Labs is more useful for you.

[Tiktack]

My second concern is the use of Pane and Back buttons. It's extremely opinionated, and I worry we're gonna get too many apps looking too identical.

I think opposite, that this is very good when platform get consistency across apps. This the first concern about windows, that every app looks different some from XP era, some from Vista/7, some Win10.

When you have a common component that satisfies 95% applications and it looks identical - this is good. It helps with muscle memory and overall experience.

[eduardobragaxz]

I disagree about the Pane and Back buttons point as well. I like that they're options in there.

[shinta0806]

I have a request for the Title / Subtitle property.

The Subtitle property is not required.
Instead, I would like the Title property to be a UIElement instead of a String, so that I can put in a Stackpanel, etc.

This will keep the properties clean, and if you want to include Subtitle, just put Title and Subtitle in the StackPanel.

[eduardobragaxz]

Isn't that the Header?

[Jay-o-Way]

@shinta0806

1. off-topic
2. put your Stackpanel in the Content

[shinta0806]

1. off-topic

Sorry, I meant TitleBar API feedback, but if you mean off-topic, forget it.

[dotMorten]

Just realizing that the repo https://github.com/microsoft/microsoft-ui-xaml-specs is still a tiny bit alive. Perhaps the TitleBar API should have been proposed over there first and feedback solicited prior to shipping it in EXP1? There's been several new controls shipped in the past few releases, but none of them went through the spec repo.

[dongle-the-gadget]

For whatever reason, the Content and Footer regions are both dragging regions rather than interactive regions for my code. Is there anything wrong with this?

<TitleBar x:Name="TitleBarControl" IsBackButtonVisible="True" IsPaneToggleButtonVisible="True" Title="Sample App" Subtitle="Sample">
    <AutoSuggestBox QueryIcon="Find" PlaceholderText="Find" MinWidth="300" MaxWidth="500" Margin="8"/>
    <TitleBar.Footer>
        <PersonPicture Height="30" Width="30" Initials="JD" />
    </TitleBar.Footer>
</TitleBar>

public MainWindow()
{
    this.InitializeComponent();
    this.ExtendsContentIntoTitleBar = true;
    this.AppWindow.TitleBar.PreferredHeightOption = Microsoft.UI.Windowing.TitleBarHeightOption.Tall;
    this.SetTitleBar(TitleBarControl);

    TitleBarControl.Loaded += TitleBarControl_Loaded;
}

private void TitleBarControl_Loaded(object sender, RoutedEventArgs e)
{
    // Parts get delay loaded. If you have the parts, make them visible.
    VisualStateManager.GoToState(TitleBarControl, "SubtitleTextVisible", false);
    VisualStateManager.GoToState(TitleBarControl, "ContentVisible", false);
    VisualStateManager.GoToState(TitleBarControl, "FooterVisible", false);

    // Run layout so we re-calculate the drag regions.
    TitleBarControl.InvalidateMeasure();
}

[AndrewKeepCoding]

@dongle-the-gadget
Don't worry. You are not the only one.
#9702

[karkarl]

Exciting to see this much enthusiasm for the new control! Let me try to answer questions here...

[karkarl]

Yeah being able to write

<Window>
    <Window.TitleBar>
         <TitleBar />
    </Window.TitleBar>
</Window>

would have been way more intuitive, but unfortunately the baseclass of Window is wrong and prevents this.

I agree with you here, it will be amazing to not need the extra code-behind and Grid for layout here. This will be a change on the Window class so more planning will be needed if feature is approved.

[karkarl]

I think this control is trying to match the Design guidance the WinUI team put in the Figma toolkit some time ago - and match what the product teams have been doing with their custom Title Bars.

You are correct. In the initial spec'ing process, we examined the existing design patterns and how we can achieve parity with what the design team has in the Windows Visual Design toolkit. The patterns and scenarios outlined in the toolkit are the most common use-cases for the control. It is important to be aligned with that to be consistent with Windows theming.

What would be the best practice to use this TitleBar control, along with a TabView control, where the tabs are not a drag region, but the bar where the tabs are contained, is draggable?

And in examining the TabView use case, we realized that TabView in the non-client (title bar) area is a control in itself, and does not need the features spec'd in this iteration of TitleBar. Hence, for now, TabView in TitleBar pattern will be a separate implementation to this control.

[karkarl]

Just realizing that the repo https://github.com/microsoft/microsoft-ui-xaml-specs is still a tiny bit alive. Perhaps the TitleBar API should have been proposed over there first and feedback solicited prior to shipping it in EXP1? There's been several new controls shipped in the past few releases, but none of them went through the spec repo.

👀

[karkarl]

For whatever reason, the Content and Footer regions are both dragging regions rather than interactive regions for my code. Is there anything wrong with this?

Yes this is a bug. This will be fixed in the next experimental release.

[karkarl]

Header and Footer are very confusing.

The Header and Footer naming convention is aligned with what TabView currently uses. I'm loving the discussion here regarding a more appropriate naming - let's keep it coming!

[riverar]

I agree with you here, it will be amazing to not need the extra code-behind and Grid for layout here. This will be a change on the Window class so more planning will be needed if feature is approved.

Is the change to the Window class something the team is actively considering?

In the initial spec'ing process, we examined the existing design patterns and how we can achieve parity with what the design team has in the Windows Visual Design toolkit. The patterns and scenarios outlined in the toolkit are the most common use-cases for the control. It is important to be aligned with that to be consistent with Windows theming.

What is the Windows Visual Design toolkit? Are you referring instead to the WinUI 3-only Windows UI Toolkit?

(Aside: Current design guidance is built around WinUI 3, which is not really accessible to anyone not using C# + MSBuild and cannot be adopted by the majority of apps in the ecosystem. We don't have any framework-agnostic design guidance or tokens at this time.)

The Header and Footer naming convention is aligned with what TabView currently uses. I'm loving the discussion here regarding a more appropriate naming - let's keep it coming!

Is renaming the attributes on the table? If not, it'd be great if you told us upfront so we don't waste our time discussing it further here.

[MPITech]

I would love to be able to use SVGs for the titlebar icon so they scale on high DPI correctly. Actually, SVGs everywhere in WinUI should be standard. Coming from WinForms + DevExpress controls where I have been using SVGs for years and everything scales beautifully, then coming to WinUI where we are still using PNGs feels like a big step backwards. Unless I am missing something, I have only been using WinUI for a few months. Fonts shouldn't be the only answer to scalable icons. Anyway, I love where the new titlebar changes are going, I have been using the WinUICommunity titlebar feature up until now.

[whiskhub]

There is now a PR for the TitleBar spec: #10056

[Jay-o-Way]

naming of Header and Footer is very misleading. Those names typically refer to top/bottom items

Here's an insight: A head is not a synonym for the top but for the leading part. Animals that are "built horizontally" have their head at the front, not on top. I understand the thought, but don't agree.

[dotMorten]

@Jay-o-Way Surely you will agree that their feet are usually on the ground, at the very bottom, and not trailing behind them? But this isn't about head and feet on animals but rather, but header and footer, so think documents, building construction etc where those words are used.