WinUI TitleBar API Spec #10056
WinUI TitleBar API Spec #10056
Conversation
|
Are the following modes considered?
|
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> |
| - Custom Height - 32px as default / 48px if content != null | ||
|  | ||
|
|
||
| ## Considerations |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Great callout. I will make sure it is included in the Considerations section.
|
This took my UK brain a moment to decipher lol |
Correct :) |
| public class TitleBar : Control | ||
| ``` | ||
|
|
||
| ## TitleBar.Header property |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I'm for header/footer if they're not going to change it everywhere else at the same time.
There was a problem hiding this comment.
As per the original feedback thread, agree and prefer Before/After #9700 (comment)
|
I hope there will be some sample, guidance, or official support for apps which use tabbed navigation within the titlebar area. |
| ## TitleBarTemplateSettings Class | ||
| <!-- TODO --> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Oops, I misspoke in my previous comment. The Icon in TitleBar will continue to be applied through TitleBarTemplateSettings.IconElement. By best practice, we should not be modifying xaml elements in codebehind, should the element be removed in re-templating.
There was a problem hiding this comment.
This confuses me. Normally templatesettings classes are used to simplify binding things into the template, and not as the main way to set a property (which would also make it harder to set from xaml). Reference: https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/template-settings-classes#the-scenario-for-templatesettings-classes
|
Today is November 12! 😐 |
|
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. |
| public class TitleBar : Control | ||
| ``` | ||
|
|
||
| ## TitleBar.Header property |
There was a problem hiding this comment.
As per the original feedback thread, agree and prefer Before/After #9700 (comment)
| Gets or sets the TitleBar's icon. | ||
|
|
||
| ```cs | ||
| public IconSource IconSource { get; set; } |
There was a problem hiding this comment.
Make it clear who owns the underlying icon handle here, to avoid common handle leaks.
There was a problem hiding this comment.
Didn't see any talk about wiring this up to Window.Titlebar.
| ## TitleBar.IconSource property | ||
|
|
||
| Gets or sets the TitleBar's icon. |
There was a problem hiding this comment.
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...)
There was a problem hiding this comment.
Great callout. Please do share the list of considerations here.
There was a problem hiding this comment.
Some considerations include:
-
Ownership and lifetime of icon handles: You'll need to decide whether the developer is responsible for managing the
HICONhandle, 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.
|
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. |
| 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)) |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
These are notes for posterity. I am submitting this spec for review and wanted to call out the comparisons.
|
hey sorry to post it here, can anyone look at this?#10319 (comment) |
|
For those interested (@dotMorten, @whiskhub, @Jay-o-Way , @riverar ), the new titlebar now uses RightContent, LeftContent, CenterContent |
|
That’s unfortunate and may confuse RTL customers, but the decision has been made. The good news, I suppose, is that the team is still making progress. |
|
I agree, this decision is quite weird. Why do all this effort for a spec discussion, if you internally decide for something entirely different? The final decision should’ve been at least documented here. Probably it was just forgotten since all the work is done in the internal Microsoft repo and there is actually rarely anyone looking at this GitHub repo :/ |
|
Hey everyone, We want to take a moment to sincerely thank you for your feedback and contributions to improving WinUI controls, in this case, TitleBar. Your insights help us refine the control and ensure we're delivering the best possible experience for developers and users alike. Based on your feedback, we've made several improvements since 1.6Experimental, including:
Upcoming post 1.7 stable fixes that we are committed to:
In addition, we’ve documented and marked the following suggestions for future versions:
Your engagement makes a real impact, and we truly appreciate the time and effort you put into testing, reporting issues, and suggesting enhancements. This is the first iteration for open spec reviews for WinUI 3, and while there are growing pains and gaps in communication, we are working on streamlining this process. Please keep the feedback coming—we're excited to keep improving together! |
During internal review, after presenting the options that the community has offered, we found precedence with both Pivot and ScrollViewer having LeftHeader/RightHeader as a concept. The current naming ensued from that. Would folks have preferred LeftHeader/Content/RightHeader instead to align with more established patterns? |
My main concern here is I don't understand how this should work in an RTL scenario.
Right and Left content was explicitly mentioned in a few of the design comments as not tenable because of this, so I was rather confused it was ignored and instead became part of the shipping design, even though the spec never mentioned this naming as an option (having said that the spec was merged with only options for naming, not final naming which was a little confusing to me in a design spec that is merged with no final conclusion). I think comparing to Pivot and ScrollViewer doesn't make that much sense, because the expectation for these controls isn't to swap content in RTL (you still scroll/pivot left/right when clicking that content) |
Yes, consistent with the rest of Xaml where the
A developer would have to handle the RTL language change and update the FlowDirection property on the app first to enable RTL scenario. This is an obvious gap in WinUI developer experience but this code should probably live in the XamlWindow layer. It is outside of the scope of WinUI TitleBar. |
|
I appreciate your response to the community, this is what we need more of! |
|
@karkarl can you please file a dedicated issue in the WindowsAppSDK repo that includes whole of your this comment, so that we people outside of MS can be aware of its progress? because right now, it's buried deep down in the github-PR-comments soup. |
|
Remember that iconic situation of two kids, facing each other, one tells the other to raise their left hand and, because they are not on the same side, the first one tells the other that they're doing it wrong...? The words RIGHT and LEFT, like east and west, are supposed to be objective and not to be mixed up! It's the whole reason that we were suggesting other words! Oh, Microsoft, you made another dumb choice once again. Mark my words, I predict a huge pile of complaints coming in the near future...
|
By the way, there is such a case in CSS, and in Flexbox API it's solved by using terms like "start" and "end". When the writing direction is changed, the positions are swapped. So I think these are good words to describe it |
|
We've talked a lot about various naming conventions here. They all have their drawbacks. The main goal for us is to try and remain as consistent as possible with what's been done in the past to make things more discoverable or consumable by others. Header/Content/Footer has been the established pattern for a long time, even for horizontal layouts (though not as common). This was the direction from the initial reviews during the preliminary development as well. However, this got a lot of pushback last year, so after evaluation of other possibilities, it was discovered there was another fallback with the Left/Right Header convention done by Pivot and ScrollViewer. Unfortunately for its roots based over a decade ago, Left/Right and swapping them in RTL mode with FlowDirection is the current pattern established by the framework for handling these scenarios. Even if it's not well understood or confusing, though hopefully we can do a better job documenting this convention in the interim. It's better for us to be more consistent now than try to one-off a new paradigm that'll cause further confusion, and look towards an opportunity in the future to revisit things as a whole to rework across the platform with some future breaking change (whenever that opportunity arises). |
|
@michael-hawker ugh that's tough but I can understand the issues you're dealing with here, and the reasoning for making this change. Thank you for the above description. I do wish that would have been part of the design discussion rather than the blind-sided change in the release. It really devalued the purpose of the public design review. I do wonder though if people would have hated header/footer as much had they known this was the only other alternative to keep consistency. |
|
Hey everyone! I just want to give an update that the API names have been offically updated to |
|
Does it make sense to have different names for these properties when you can put exactly the same things in them? What makes the headers different from Content apart from position? Left/RightContent makes more sense to me, even though I dislike it for not being consistent with other controls. |
|
@eduardobragaxz the |
|
I just mean they have different names yet achieve the same: to set some content. |
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