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: 10/11-11/11
For more info on the public api review process: https://aka.ms/winappsdk/api-specs-review

whiskhub · 2024-10-12T08:35:13Z

specs/TitleBar/titlebar-functional-spec.md

+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


Suggested change

## TitleBar.Subtitle event

## TitleBar.Subtitle property

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)

Jay-o-Way · 2024-10-12T10:58:00Z

specs/TitleBar/titleBar-dev-spec.md

+- 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. 


Suggested change

- 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.

Jay-o-Way · 2024-10-12T10:59:13Z

specs/TitleBar/titleBar-dev-spec.md

+     - 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.


Suggested change

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.

Jay-o-Way · 2024-10-12T11:05:58Z

specs/TitleBar/titleBar-dev-spec.md

+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 


Suggested change

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

Jay-o-Way · 2024-10-12T11:07:11Z

specs/TitleBar/titleBar-dev-spec.md

+
+`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.


Suggested change

- The list is updated everytime the specified elements' visibility changes.

- The list is updated every time the specified elements' visibility changes.

Jay-o-Way · 2024-10-12T11:07:42Z

specs/TitleBar/titleBar-dev-spec.md

+`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`.


Suggested change

- eg. `BackButton`, `PaleToggleButton`, `Header`, `Content`, `Footer`.

- eg. `BackButton`, `PaneToggleButton`, `Header`, `Content`, `Footer`.

Jay-o-Way · 2024-10-12T11:24:52Z

specs/TitleBar/titlebar-functional-spec.md

+
+# Sample scenarios
+
+## **Scenario: Default TitleBar**


Multiple occasions: By MD guidance, mixing a header with formatting is...not ideal

Jay-o-Way · 2024-10-12T11:27:02Z

specs/TitleBar/titlebar-functional-spec.md

+</Window>
+```
+
+**C#**


Multiple occasions: the word "XAML" up above is not bold, but "C#" is?

Jay-o-Way · 2024-10-12T11:41:06Z

specs/TitleBar/titlebar-functional-spec.md

+```cs
+public UIElement Header { get; set; }
+```
+


Colors imply something isn't as it should? Document rendering os good, so maybe it's just GitHub Diff rendering issue?

Jay-o-Way · 2024-10-12T11:48:40Z

specs/TitleBar/titlebar-functional-spec.md

+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.


Suggested change

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.

Jay-o-Way · 2024-10-12T11:53:32Z

specs/TitleBar/titlebar-functional-spec.md

+TitleBarAutomationPeer implements ...
+
+# API Details
+


Jay-o-Way · 2024-10-15T17:28:19Z

specs/TitleBar/images/default-titlebar.png

What's that dotted line doing there?

Jay-o-Way · 2024-10-15T17:30:45Z

specs/TitleBar/titleBar-dev-spec.md

+
+# Design considerations
+
+## AppWindow TitleBar (IXP) vs. WinUI TitleBar


What does IXP mean?

Please don't abbreviate a word like versus when there's no need to.

Jay-o-Way · 2024-10-15T17:35:15Z

specs/TitleBar/images/titlebar-sizevariant.png

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.

Jay-o-Way · 2024-10-15T17:50:00Z

specs/TitleBar/titlebar-functional-spec.md

Missing any mention of Titlebar.Height property in this file.

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>

niels9001 · 2024-10-16T09:00:09Z

specs/TitleBar/titleBar-dev-spec.md

+
+# Functional spec link
+
+[Functional Spec](images/titleBar-functional-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.

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.

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.

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

Open

whiskhub reviewed Oct 12, 2024

View reviewed changes

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

Copy link

Contributor

Jay-o-Way Oct 15, 2024

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?

Jay-o-Way reviewed Oct 15, 2024

View reviewed changes

specs/TitleBar/titlebar-functional-spec.md

Copy link

Contributor

Jay-o-Way Oct 15, 2024

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.

niels9001 reviewed Oct 16, 2024

View reviewed changes

specs/TitleBar/titleBar-dev-spec.md

# Functional spec link

[Functional Spec](images/titleBar-functional-spec.md)

Copy link

Contributor

niels9001 Oct 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dead link

whiskhub reviewed Oct 20, 2024

View reviewed changes

whiskhub reviewed Oct 28, 2024

View reviewed changes

dotMorten reviewed Oct 28, 2024

View reviewed changes

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

whiskhub Oct 12, 2024

ghost1372 commented Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024 •

edited

Loading

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 12, 2024

Jay-o-Way Oct 15, 2024

Jay-o-Way Oct 15, 2024

Jay-o-Way Oct 15, 2024 •

edited

Loading

Jay-o-Way Oct 15, 2024

Jay-o-Way commented Oct 15, 2024 •

edited

Loading

niels9001 Oct 16, 2024

whiskhub Oct 20, 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

mdtauk commented Oct 28, 2024

dotMorten Oct 28, 2024

	- 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.

	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.

	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

	- The list is updated everytime the specified elements' visibility changes.
	- The list is updated every time the specified elements' visibility changes.

	- eg. `BackButton`, `PaleToggleButton`, `Header`, `Content`, `Footer`.
	- eg. `BackButton`, `PaneToggleButton`, `Header`, `Content`, `Footer`.

	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.


		# Design considerations

		## AppWindow TitleBar (IXP) vs. WinUI TitleBar


		# Functional spec link

		[Functional Spec](images/titleBar-functional-spec.md)

WinUI TitleBar API Spec #10056

Are you sure you want to change the base?

WinUI TitleBar API Spec #10056

Conversation

karkarl commented Oct 11, 2024 • edited Loading

Choose a reason for hiding this comment

ghost1372 commented Oct 12, 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jay-o-Way Oct 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

mdtauk commented Oct 28, 2024

Choose a reason for hiding this comment

karkarl commented Oct 11, 2024 •

edited

Loading

Jay-o-Way Oct 12, 2024 •

edited

Loading

Jay-o-Way Oct 15, 2024 •

edited

Loading

Jay-o-Way commented Oct 15, 2024 •

edited

Loading