-
Notifications
You must be signed in to change notification settings - Fork 678
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
WinUI TitleBar API Spec #10056
base: main
Are you sure you want to change the base?
WinUI TitleBar API Spec #10056
Conversation
If TitleBar is in minimal display mode, Title textbox will automatically be collapsed. | ||
If Title string is empty, Title textbox will be collapsed. | ||
|
||
## TitleBar.Subtitle event |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## TitleBar.Subtitle event | |
## TitleBar.Subtitle property |
Are the following modes considered?
|
- Punch hole through Header / Content / Footer for drag regions. Calculations needs to be updated on SizeChanged. | ||
- Regions with hole punched through are non-draggable. | ||
|
||
- Currently TitleBar treats all custom content as interactable and punches a whole through the drag region. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Currently TitleBar treats all custom content as interactable and punches a whole through the drag region. | |
- Currently TitleBar treats all custom content as interactable and punches a hole through the drag region. |
- Reference Teams forward / backward button. It is draggable when disabled. | ||
|
||
- Interactive content in TitleBar must also be capable of keyboard navigation. | ||
They should be treated as a normal elements in the app's visual tree. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
They should be treated as a normal elements in the app's visual tree. | |
They should be treated as normal elements in the app's visual tree. |
It is to be used in lieu of the Shell title bar for when developers want more than the basic shell title bar functionalities. | ||
|
||
Current implementations of a custom titlebar involves the developer to fully create a user component from scratch. A notable painpoint in this process is | ||
to manually calculate drag regions for when there are elements in the title bar (ie. AutoSuggestBox - refer to WinUI-Gallery sample). WinUI titleBar is meant |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
to manually calculate drag regions for when there are elements in the title bar (ie. AutoSuggestBox - refer to WinUI-Gallery sample). WinUI titleBar is meant | |
to manually calculate drag regions for when there are interactive elements in the title bar (ie. AutoSuggestBox - refer to WinUI-Gallery sample). WinUI titleBar is meant |
|
||
`m_interactableElementsList` | ||
- A list of interactable elements is tracked in the lifetime of the TitleBar. | ||
- The list is updated everytime the specified elements' visibility changes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- The list is updated everytime the specified elements' visibility changes. | |
- The list is updated every time the specified elements' visibility changes. |
`m_interactableElementsList` | ||
- A list of interactable elements is tracked in the lifetime of the TitleBar. | ||
- The list is updated everytime the specified elements' visibility changes. | ||
- eg. `BackButton`, `PaleToggleButton`, `Header`, `Content`, `Footer`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- eg. `BackButton`, `PaleToggleButton`, `Header`, `Content`, `Footer`. | |
- eg. `BackButton`, `PaneToggleButton`, `Header`, `Content`, `Footer`. |
|
||
# Sample scenarios | ||
|
||
## **Scenario: Default TitleBar** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Multiple occasions: By MD guidance, mixing a header with formatting is...not ideal
</Window> | ||
``` | ||
|
||
**C#** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Multiple occasions: the word "XAML" up above is not bold, but "C#" is?
```cs | ||
public UIElement Header { get; set; } | ||
``` | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is typically used to populate controls such as `PersonPicture` and the "More" `AppBarButton`. The default is `null`. | ||
|
||
### Remarks | ||
The content property of `Content` can only be set once. Elements are right aligned by default. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The content property of `Content` can only be set once. Elements are right aligned by default. | |
The content property of `Footer` can only be set once. Elements are right aligned by default. |
TitleBarAutomationPeer implements ... | ||
|
||
# API Details | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's that dotted line doing there?
|
||
# Design considerations | ||
|
||
## AppWindow TitleBar (IXP) vs. WinUI TitleBar |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- What does IXP mean?
- Please don't abbreviate a word like versus when there's no need to.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the left it says Tall = default, but a few images below here, this window buttons show Short even with content elements. That's inconsistent.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing any mention of Titlebar.Height property in this file.
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> |
|
||
# Functional spec link | ||
|
||
[Functional Spec](images/titleBar-functional-spec.md) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dead link
- Custom Height - 32px as default / 48px if content != null | ||
![TitleBar Size Variants](images/titlebar-sizevariant.png) | ||
|
||
## Considerations |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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