WinUI TitleBar API Spec #10056

karkarl · 2024-10-11T21:46:54Z

This PR adds the dev and functional spec for WinUI TitleBar.

Community members can provide feedback by commenting directly on the PR, or through a code suggestion with Github tools.
Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality.

This PR will be open for feedback for a month: October 11th – November 11th
For more info on the public api review process: https://aka.ms/winappsdk/api-specs-review

specs/TitleBar/titlebar-functional-spec.md

ghost1372 · 2024-10-12T09:49:16Z

Are the following modes considered?

Right To Left
Dark/Light Theme support for System Context menu (Right Click on TitleBar)
Support Fluent (Menu Flyout) Context Menu (Disable System Context menu and using Custom Context menu)

specs/TitleBar/titleBar-dev-spec.md

specs/TitleBar/titlebar-functional-spec.md

specs/TitleBar/images/default-titlebar.png

specs/TitleBar/titleBar-dev-spec.md

specs/TitleBar/images/titlebar-sizevariant.png

specs/TitleBar/titlebar-functional-spec.md

Jay-o-Way · 2024-10-15T18:47:17Z

TitleBar currently needs to be set explicitly in the grid.row and referenced by Window in codebehind as shown above. Improvements to Window are being considered to avoid this extra grid layout and codebehind.

Yes, this is an inherent and logical result of the whole ExtendsContentIntoTitleBar concept. You're telling the app/window to hide its actual title bar. If you want a control (like this) to be used as a window's title bar, from an app's perspective, this raises the bigger question of "Is this control part of the window's content or not?"

If we could set the window's title bar properties in the following manner, then the ExtendsContentIntoTitleBar part will become unneeded. Just make sure the background of the title bar is transparent so that it show the window background.

Think of it like this:

<Window
    x:Class="App1.MainWindow"
    xmlns:local="using:App1"
    mc:Ignorable="d">

    <TitleBar x:Name="DefaultTitleBar" Title="Default TitleBar" Subtitle="Preview">
        <TitleBar.IconSource>
            <SymbolIconSource Symbol="Home"/>
        </TitleBar.IconSource>
    </TitleBar>

      <!-- App content - in the 100% correct term -->
</Window>

specs/TitleBar/titleBar-dev-spec.md

whiskhub · 2024-10-20T20:18:25Z

specs/TitleBar/titleBar-dev-spec.md

+- Custom Height - 32px as default / 48px if content != null  
+![TitleBar Size Variants](images/titlebar-sizevariant.png)
+
+## Considerations


The WinUI title bar should meet Windows app design guidelines (see #9907). For example:

A single-click/tap on the icon should show system window menu.
A double-click/tap should close the window.

Great callout. I will make sure it is included in the Considerations section.

aboodic · 2024-10-22T13:51:04Z

This PR adds the dev and functional spec for WinUI TitleBar.

Community members can provide feedback by commenting directly on the PR, or through a code suggestion with Github tools.

Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality.

This PR will be open for feedback for a month: 10/11-11/11

For more info on the public api review process: https://aka.ms/winappsdk/api-specs-review

mdtauk · 2024-10-22T16:00:24Z

a month: 10/11-11/11

This took my UK brain a moment to decipher lol
11th October – 11th November right?

duncanmacmichael · 2024-10-23T11:38:46Z

a month: 10/11-11/11

This took my UK brain a moment to decipher lol 11th October – 11th November right?

Correct :)

whiskhub · 2024-10-28T20:08:52Z

specs/TitleBar/titlebar-functional-spec.md

+public class TitleBar : Control
+```
+
+## TitleBar.Header property


I'm surprised nobody has brought this up, after the heated discussions in #9700.
Header and Footer, while being concise terms, can be confusing in this context of a horizontal layout. Other terminology could be:

Start and End (e.g. Windows.UI.Xaml.TextAlignment.Start/End
TextAlignment

Before and After (e.g. CSS, Fluent Web UI)

Leading and Trailing (e.g. Apple SwiftUI Toolbar)

In the end, it will be hard to objectively decide on what's best. Personally, I prefer StartElement and EndElement here. Before and After imply the center of the title bar would have the actual content, while in most apps the center of the title bar is actually empty.

I understand the thought, but don't agree. 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'm with Whiskhub here. Header/Footer is misleading. The only argument I see for keeping the naming is that TabView also got this wrong, but I'd rather you don't continue down the confusing naming and address it here with better names, like Leading and Trailing.

I'm for header/footer if they're not going to change it everywhere else at the same time.

As per the original feedback thread, agree and prefer Before/After #9700 (comment)

mdtauk · 2024-10-28T22:30:41Z

I hope there will be some sample, guidance, or official support for apps which use tabbed navigation within the titlebar area.

dotMorten · 2024-10-28T23:25:36Z

specs/TitleBar/titlebar-functional-spec.md

+## TitleBarTemplateSettings Class
+<!-- TODO -->


I'd like to see information on this class. I had pointed out in #9700 that this was an odd way to set the icon here, rather than just setting the icon directly on the window or titlebar instance. It feels a bit like this is just internal plumbing that is bubbling up into the public API.

The TitleBarTemplateSettings class would not be used to set the Icon Property. It was added originally to implement interactive / non-interactive regions in the TitleBar. I will most likely be removing it, as it is no longer needed.

ghost1372 · 2024-11-12T05:54:21Z

Today is November 12! 😐

karkarl · 2024-11-12T16:59:52Z

The feedback period is up! Thank you all very much for your contributions thus far. I will be closing this PR while we parse through the feedback.

Updates to the spec will still be done on this branch, and I will re-open the PR when it is ready for final review and merge. Closing this PR is simply to indicate that we are no longer actively gathering feedback.

riverar · 2024-11-13T23:22:58Z

specs/TitleBar/titlebar-functional-spec.md

+public class TitleBar : Control
+```
+
+## TitleBar.Header property


As per the original feedback thread, agree and prefer Before/After #9700 (comment)

riverar · 2024-11-13T23:24:56Z

specs/TitleBar/titlebar-functional-spec.md

+Gets or sets the TitleBar's icon.
+
+```cs
+public IconSource IconSource { get; set; }


Make it clear who owns the underlying icon handle here, to avoid common handle leaks.

riverar · 2024-11-13T23:28:04Z

specs/TitleBar/titleBar-dev-spec.md

Didn't see any talk about wiring this up to Window.Titlebar.

riverar · 2024-11-13T23:29:22Z

specs/TitleBar/titlebar-functional-spec.md

+## TitleBar.IconSource property
+
+Gets or sets the TitleBar's icon.


Is this going to be wired up to WM_SETICON for the notification area? (If so, I have a laundry list of things you need to keep in mind...)

Great callout. Please do share the list of considerations here.

Some considerations include:

Ownership and lifetime of icon handles: You'll need to decide whether the developer is responsible for managing the HICON handle, or if ownership is transferred to the framework. If ownership is transferred, will the framework duplicate the handle for use in multiple windows, or allow developers to set per-window icons? And don't forget about globally shared handles, which should not be freed automatically.

Icon size variants: The API should support setting both small and big icon sizes, as both are used across different UI surfaces for visual consistency.

System theme and accessibility: The API should allow for setting multiple icon variants to accommodate different system themes (e.g., light/dark mode), high contrast mode, and high DPI scenarios. Again, it's all about visual consistency.

dotMorten · 2024-11-21T00:36:34Z

Is the v1.7experimental release the final TitleBar API? I'm a little confused that it is identical to the 1.6 one, and from my understanding it was pulled from the 1.6 release to address the design feedback?

michael-hawker · 2024-11-21T01:06:43Z

Is the v1.7experimental release the final TitleBar API? I'm a little confused that it is identical to the 1.6 one, and from my understanding it was pulled from the 1.6 release to address the design feedback?

No, the version in 1.7-experimental is still the one from 1.6-experimental. The feedback period for collection on the spec here just closed last week; so now that'll be go into improving the control. I agree the timing here is bit off, but part of it was us shoring up the definition of the process here.

I'll let @karkarl add any more specifics from a timeline/planning perspective, as I don't have up-to-date info on that, just the info above. I had called this out during the .NET Conf talk last week when we mentioned this as well.

dotMorten · 2024-11-21T01:09:08Z

@michael-hawker awesome! Great to hear!

Co-authored-by: whiskhub <[email protected]>

Co-authored-by: Jay <[email protected]>

karkarl · 2024-12-12T19:36:09Z

I hope there will be some sample, guidance, or official support for apps which use tabbed navigation within the titlebar area.

Upon investigation, tabbed navigation in TitleBar seems to be a complete different control needing separate implementation. Hence it is considered out of scope for this TitleBar control. As for future support, I hope so as well. Active community feedback for TitleBar has helped drive prioritization for the control, so please file feature requests or start a new discussion thread!

dotMorten · 2024-12-12T22:56:43Z

specs/TitleBar/titleBar-dev-spec.md

+Alternate naming considerations for `Header`, `Content`, `Footer`:
+- Header and Footer aligns with TabView.TabStripHeader and TabView.TabStripFooter
+- Start and End (e.g. [Windows.UI.Xaml.TextAlignment](https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml?view=winrt-26100))
+- Before and After (e.g. CSS, [Fluent Web UI](https://react.fluentui.dev/?path=/docs/components-input--docs#content-before-after))
+- Leading and Trailing (e.g. [Apple SwiftUI Toolbar](https://developer.apple.com/documentation/swiftui/toolbaritemplacement/topbarleading))


Does this mean this is up for discussion still in this design as a todo? Or is this more of a comparison to explain what is meant by these concepts?

These are notes for posterity. I am submitting this spec for review and wanted to call out the comparisons.

titlebar spec initial

1a9649f

karkarl added the SpecInReview label Oct 11, 2024

microsoft-github-policy-service bot added the needs-triage Issue needs to be triaged by the area owners label Oct 11, 2024

karkarl mentioned this pull request Oct 11, 2024

TitleBar API Spec #10057

Closed

karkarl self-assigned this Oct 11, 2024

karkarl removed the needs-triage Issue needs to be triaged by the area owners label Oct 11, 2024

whiskhub mentioned this pull request Oct 12, 2024

TitleBar API feedback #9700

Closed

whiskhub reviewed Oct 12, 2024

View reviewed changes

specs/TitleBar/titlebar-functional-spec.md Outdated Show resolved Hide resolved

Jay-o-Way suggested changes Oct 12, 2024

View reviewed changes

Jay-o-Way reviewed Oct 15, 2024

View reviewed changes

specs/TitleBar/images/default-titlebar.png Outdated Show resolved Hide resolved

Jay-o-Way reviewed Oct 15, 2024

View reviewed changes

specs/TitleBar/titleBar-dev-spec.md Outdated Show resolved Hide resolved

Jay-o-Way reviewed Oct 15, 2024

View reviewed changes

specs/TitleBar/images/titlebar-sizevariant.png Outdated Show resolved Hide resolved

Jay-o-Way reviewed Oct 15, 2024

View reviewed changes

specs/TitleBar/titlebar-functional-spec.md Show resolved Hide resolved

niels9001 reviewed Oct 16, 2024

View reviewed changes

specs/TitleBar/titleBar-dev-spec.md Outdated Show resolved Hide resolved

whiskhub reviewed Oct 20, 2024

View reviewed changes

whiskhub reviewed Oct 28, 2024

View reviewed changes

dotMorten reviewed Oct 28, 2024

View reviewed changes

karkarl closed this Nov 12, 2024

riverar reviewed Nov 13, 2024

View reviewed changes

microsoft-github-policy-service bot added the needs-triage Issue needs to be triaged by the area owners label Nov 21, 2024

karkarl reopened this Dec 9, 2024

karkarl and others added 10 commits December 9, 2024 14:17

Update specs/TitleBar/titlebar-functional-spec.md

1e26c97

Co-authored-by: whiskhub <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

d0f0323

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

b12c2cc

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

718f790

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

952119e

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

5f4be78

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titleBar-dev-spec.md

c21a9c9

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titlebar-functional-spec.md

25bb1a4

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titlebar-functional-spec.md

36f77af

Co-authored-by: Jay <[email protected]>

Update specs/TitleBar/titlebar-functional-spec.md

649c560

Co-authored-by: Jay <[email protected]>

karkarl closed this Dec 9, 2024

karkarl added 3 commits December 9, 2024 15:49

formatting changes from comments

e466acb

update images

acbf8e9

add height explanation

0b6d3a7

karkarl removed the needs-triage Issue needs to be triaged by the area owners label Dec 12, 2024

address more comments

71d2c0b

karkarl reopened this Dec 12, 2024

microsoft-github-policy-service bot added the needs-triage Issue needs to be triaged by the area owners label Dec 12, 2024

kmahone approved these changes Dec 12, 2024

View reviewed changes

karkarl added 2 commits December 12, 2024 14:49

add notes on header footer naming

644ae7a

contentBefore and contentAfter

709eb85

dotMorten reviewed Dec 12, 2024

View reviewed changes

kmahone approved these changes Dec 12, 2024

View reviewed changes

karkarl merged commit 650b2c1 into main Dec 13, 2024
1 of 2 checks passed

karkarl deleted the user/karkarl/TitleBarSpecReview branch December 13, 2024 01:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WinUI TitleBar API Spec #10056

WinUI TitleBar API Spec #10056

karkarl commented Oct 11, 2024 •

edited

Loading

ghost1372 commented Oct 12, 2024

Jay-o-Way commented Oct 15, 2024 •

edited

Loading

whiskhub Oct 20, 2024

karkarl Dec 12, 2024

aboodic commented Oct 22, 2024

mdtauk commented Oct 22, 2024

duncanmacmichael commented Oct 23, 2024

whiskhub Oct 28, 2024

Jay-o-Way Oct 28, 2024

dotMorten Oct 28, 2024

eduardobragaxz Nov 2, 2024

riverar Nov 13, 2024

mdtauk commented Oct 28, 2024

dotMorten Oct 28, 2024

karkarl Dec 12, 2024

ghost1372 commented Nov 12, 2024

karkarl commented Nov 12, 2024 •

edited

Loading

riverar Nov 13, 2024

riverar Nov 13, 2024

riverar Nov 13, 2024

riverar Nov 13, 2024 •

edited

Loading

karkarl Dec 12, 2024

riverar Dec 12, 2024 •

edited

Loading

dotMorten commented Nov 21, 2024

michael-hawker commented Nov 21, 2024

dotMorten commented Nov 21, 2024

karkarl commented Dec 12, 2024

dotMorten Dec 12, 2024

karkarl Dec 12, 2024

		## TitleBar.IconSource property

		Gets or sets the TitleBar's icon.

WinUI TitleBar API Spec #10056

WinUI TitleBar API Spec #10056

Conversation

karkarl commented Oct 11, 2024 • edited Loading

ghost1372 commented Oct 12, 2024

Jay-o-Way commented Oct 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aboodic commented Oct 22, 2024

mdtauk commented Oct 22, 2024

duncanmacmichael commented Oct 23, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdtauk commented Oct 28, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost1372 commented Nov 12, 2024

karkarl commented Nov 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

riverar Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

riverar Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

dotMorten commented Nov 21, 2024

michael-hawker commented Nov 21, 2024

dotMorten commented Nov 21, 2024

karkarl commented Dec 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

karkarl commented Oct 11, 2024 •

edited

Loading

Jay-o-Way commented Oct 15, 2024 •

edited

Loading

karkarl commented Nov 12, 2024 •

edited

Loading

riverar Nov 13, 2024 •

edited

Loading

riverar Dec 12, 2024 •

edited

Loading