microsoft
WinUI TitleBar API Spec
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
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)
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>
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
a month: 10/11-11/11
This took my UK brain a moment to decipher lol 11th October – 11th November right?
a month: 10/11-11/11
This took my UK brain a moment to decipher lol 11th October – 11th November right?
Correct :)
I hope there will be some sample, guidance, or official support for apps which use tabbed navigation within the titlebar area.
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.
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?
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.
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!
hey sorry to post it here, can anyone look at this?https://github.com/microsoft/microsoft-ui-xaml/issues/10319#issuecomment-2617055632
Hi @karkarl we are in v1.7-Preview1 and still Many TitleBar feedbacks are unresolved, Most importantly, AppWindow.TitleBar APIs do not work with TitleBar control.
https://github.com/microsoft/microsoft-ui-xaml/issues/9784 https://github.com/microsoft/microsoft-ui-xaml/issues/9864 https://github.com/microsoft/microsoft-ui-xaml/issues/9907 https://github.com/microsoft/microsoft-ui-xaml/issues/9866 https://github.com/microsoft/microsoft-ui-xaml/issues/9865 https://github.com/microsoft/microsoft-ui-xaml/issues/9863
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:
- RTL Scenarios @ghost1372
- Single-clicking TitleBar Icon to show system menu @whiskhub
- Naming of custom content areas in TitleBar @whiskhub, @Jay-o-Way @dotMorten @eduardobragaxz @riverar
- Visual Alignment with Windows Fluent Design Guidelines @niels9001
- Exposing Xaml widths as ThemeResources and TemplateBinding TitleBar.Height property @nielslaute @Jay-O-Way
- TemplateBinding TitleBar.Foreground and Background property
- Fix #9845 Title in TitleBar shows up after resizing the window when the window loses focus @eduardobragaxz
Upcoming post 1.7 stable fixes that we are committed to:
- #9784 New TitleBar control with PathIconSource as IconSource breaks the app @Diegorro98
- AppWindow.TitleBar.LeftInset & RightInset should be exposed as TemplateSettings properties, so LeftPaddingColumn and RightPaddingColumn is not hard-coded.
- #9907 Double-clicking TitleBar Icon does not close the window. @whiskhub
- This is blocked by an issue with InputNonClientPointerSource APIs.
- Issue with LeftPaddingColumn and RightPaddingColumn when toggling between RTL multiple times
- This fix is blocked on AppWindowTitleBar.LeftInset / RightInset APIs.
In addition, we’ve documented and marked the following suggestions for future versions:
- Supporting Fluent system context menus, or custom context menus @ghost1372
- Improving AppWindow.TitleBar API to not need the extra Grid layout in Window @Jay-o-Way
- Updating AppWindow APIs to avoid needing to set Win32 APIs for CaptionButtons in RTL
- Syncing WinUI TitleBar with AppWindow.TitleBar APIs @brunosonnino @whiskhub
- #9864, #9866, #9865, #9863
- These are considered feature requests. It is entirely possible to update all these properties by simply setting the properties on WinUI TitleBar itself.
- Tabbed TitleBar @mdtauk
- Functionality-wise, this is an entirely separate control outside of the scope of this TitleBar
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!
For those interested (@dotMorten, @whiskhub, @Jay-o-Way , @riverar ), the new titlebar now uses RightContent, LeftContent, CenterContent
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?
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.
- Would Left go on the right side and vice versa? (confusing/misleading naming) or:
- Would left stay on the left and forcing developers to write code to detect RTL and swap the contents of the two? (too complicated developer story that will set developers up to fail).
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)
@dotMorten
Would Left go on the right side and vice versa? (confusing/misleading naming) or:
Yes, consistent with the rest of Xaml where the Left* elements are swapped to the right side in RTL and vice versa.
Would left stay on the left and forcing developers to write code to detect RTL and swap the contents of the two? (too complicated developer story that will set developers up to fail).
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! In the end I don’t really mind the exact naming. It was just confusing for us that this came out of nowhere. If it’s a spec, IMO all considerations must be documented in advance. And the taken decision should also be documented here together with a short reason. If some information stays internal, it’s just challenging for the community to understand what is happening.
@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...
My main concern here is I don't understand how this should work in an RTL scenario.
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 LeftHeader, Content, and RightHeader.
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 LeftHeader is before the Icon/Title/Subtitle, so it's not just left of the content area.