Microsoft-ui-xaml: Proposal: Titlebar Customization: Remove system reserved draggable region when providing an own draggable region

[Felix-Dev]

Summary

In UWP, we can easily add custom UI elements to the titlebar of our apps thanks to the CoreApplicationViewTitleBar API. The issue arises when we want to add interactive UI elements (such as Buttons) to the titlebar. By default, our added custom UI elements cannot be interacted with as the sytem will retain the entire titlebar area as a draggable region (minus the system caption buttons area). This behavior is described in the UWP documentation:

If you don’t specify a draggable region, a rectangle that is the width of the window, the height of the caption buttons, and positioned along the top edge of the window is set as the default draggable region.

If we want our custom UI elements such as buttons to be interactive, we need to define a custom draggable region as stated in the docs:

You must call SetTitleBar to define an area as the draggable title bar region. If you don’t, the system sets the default draggable region at the top of the page. The system will then handle all user input to this area, and prevent input from reaching your controls.

And here comes the issue: Defining a custom draggable titlebar region will automatically create a system reserved region in the titlebar which the developer cannot control:

If you do define a draggable region, the system shrinks the default draggable region down to a small area the size of a caption button, positioned to the left of the caption buttons (or to the right if the captions buttons are on the left side of the window). This ensures that there is always a consistent area the user can drag.

@yaichenbaum created an app demonstrating the effects of this behavior (attached at the bottom):

(red = system caption buttons area)
(pale red = system reserved draggable region when defining a custom draggable region)
(sky blue = titlebar region which can be made fully interactive)

As can be seen, any custom UI element added to the titlebar inside the system reserved draggable region cannot be interacted with.
In other words, if you want to place an interactive button to the left of the system caption buttons, you will always end up with the region displayed in pale red as a separator between your button and the system caption buttons.

This is a major issue which prevents developers from creating custom titlebar experiences which seamlessly integrate with the system provided titlebar for UWP apps.

Here are a few examples which show customized titlebars which cannot be realized by us UWP developers today:

NordVPN:

Microsoft UWP Sticky Notes:

In both images, the highlighted background of the custom titlebar button (Settings button in both cases) indicates mouse hovering/click and thus that the user can interact with the custom button.

Rationale

• While the idea of a reserved draggable titlebar region makes sense in certain app scenarios such as Internet browsers or the new Windows Terminal (which place a tab control in the titlebar), in many cases the app developer can always provide a draggable region in the titlebar at any given time. See for example @yaichenbaum's graphic above where the area shown in sky blue will always remain draggable, and as such renders the system reserved titlebar region irrelevant.

Thus, when the developer ensures that there always will be a draggable titlebar region at any given time, the developer should be allowed to fully create the experience which has been envisioned for the product in question.

• In WPF/Windows Forms apps, developers can create a totally custom titlebar experience enabling them to create the experience envisioned for the product they are working on. The example UIs shown above can all be realized in the aforementioned apps.
  Feature parity between WPF and UWP is essential so that designers/developers can take their existing Win32 apps and provide modern app experiences on Windows 10 without having to compromise their vision. They shouldn't be blocked by a titlebar policy enforced by the system with no way to opt-out even though they would always provide a draggable titlebar.

Scope

| Capability | Priority |
| :---------- | :------- |
| Allow developers to take their existing Win32 apps and re-create their existing titlebar experiences (with ensured drag support) in UWP apps without having to compromise their product vision to comply with a policy dictated by the system. | Must |
| Enable developers to create titlebar experiences as realized in the Microsoft UWP Sticky Notes app. | Must |
| Allow developers to create titlebar experiences where an app might not be draggable using the titlebar. | Won't |

Open Questions

• The current titlebar system policy ensures that there will always be a draggable region in the titlebar no matter how much a developer attempts to customize the titlebar. How can the current system policy be made more flexible to allow titlebar experiences as shown above, yet it is still ensured that every UWP app has a region in the titlebar the user can use to drag the app?

Attached Files

Stubborn_Button.zip

[Austin-Lamb]

I can't remember which team in XAML has normally worked on title bar stuff, but I think it may have been Rendering.

[codendone]

He just means that he thinks team-Rendering is the right sub-team within XAML for title bar issues/features. And he is correct.

In this case, the reserved draggable region is not controlled by XAML. This is enforced by the Windows shell for apps running in the UWP app model. So removing that reserved region will require agreement from the shell team and a change in the Windows shell code. This well-written proposal can be used for tracking that possibility. Since this would be an OS change, though, it would likely only be for whichever future release of Windows contains this theoretical change, and would therefore be a while before apps could always depend on the new behavior.

Note that WinUI Desktop apps will not be forced by shell to have this reserved draggable region. So this issue should not occur there (unless we go out of our way to make that happen, but this proposal is a compelling reason to not do that 😄).

[yaichenbaum]

@codendone Thank you so much for the answer. I am looking forward to when this will be fixed especially since I have at least one UWP app that I would like to implement this in.

[Felix-Dev]

@codendone Second what @yaichenbaum said. I do hope that apps using the UWP app model will also be able to create the example experiences shown in the proposal in the future and not just WinUI Desktop apps. In the case that I do want to target multiple different Windows devices in the future with an app, the UWP is the platform of choice. I don't want to end up having to create a separate WinUI Desktop app just so I can style the titlebar of my UPW app on Desktop with the freedom Win32 has been offering for many years now.

Especially when we see that Microsoft UWP Sticky Notes apparently already can create a custom titlebar experience tailored exactly to its needs.

[codendone]

@Felix-Dev and @yaichenbaum: I agree this needs to be reconsidered for UWP. I have logged this request for the Windows shell to provide the desired flexibility for UWP:

• https://microsoft.visualstudio.com/DefaultCollection/OS/_workitems/edit/25479999

[yaichenbaum]

@codendone Thank you for the update, I understand this may take some time to address due to it being tied into the OS, but it will make a big difference when the behavior is finally changed.

[mdtauk]

@Felix-Dev and @yaichenbaum: I agree this needs to be reconsidered for UWP. I have logged this request for the Windows shell to provide the desired flexibility for UWP:

• https://microsoft.visualstudio.com/DefaultCollection/OS/_workitems/edit/25479999

Hopefully this will extend to the new WinUI Windowing APIs in development for WinUI Desktop apps

[Felix-Dev]

@mdtauk

Note that WinUI Desktop apps will not be forced by shell to have this reserved draggable region.

[mdtauk]

@mdtauk

Note that WinUI Desktop apps will not be forced by shell to have this reserved draggable region.

If a developer wants to dig into the HWND and handle the drawing of the Titlebar. But with an API being developed at the moment - they may put that reserved space in, whilst UWP considers removing it.

[Felix-Dev]

Pretty sure WinUI desktop apps won't have this reserved titlebar space even if using the new API. It's not a question of the UWP API but system policy defined by the shell why UWP apps currently have this reserved space in the titlebar. The current UWP Windowing APIs can't work around the underlying shell policy. And since there is no such forced policy for WinUI Desktop apps, you can use the new API (i.e. ExtendIntoTitlebar()) just fine.

So this issue should not occur there (unless we go out of our way to make that happen, but this proposal is a compelling reason to not do that 😄).

Any such feature of the new Windowing APIs for WinUI Desktop would at least be optional then, and as I said above, I don't even think this behavior will be ported over.