[API Spec] TitleBar's Content Custom Drag Regions #10936
Conversation
microsoft-github-policy-service
bot
added
the
needs-triage
|
@microsoft-github-policy-service agree |
|
@vinnarayana-msft is there any plan to fix titlebar issues? |
vinnarayana-msft
changed the title
Zakariathr22
left a comment
Zakariathr22
left a comment
There was a problem hiding this comment.
I suggest also using IsDragEnabled instead of ExcludeFromDrag because it avoids negative wording and follows common boolean naming rules.
Thank you @Zakariathr22 for the suggestion. The intent behind using ExcludeFromDrag is that in custom TitleBar layouts, the entire content region effectively becomes draggable, and developers typically only need to mark interactive controls as not draggable. So the property acts as an opt‑out, not an opt‑in, which makes a negative‑form name more accurate for the underlying behavior. |
|
Is there prior art for negative-form Boolean properties? I think it's more common to use positive Boolean properties. +1 to the suggested change here (from |
|
Microsoft Office allows dragging and Microsoft Teams does not. Which one is right? 
|
|
|
||
| ### Keyboard Behaviour | ||
|
|
||
| This API does not introduce new keyboard interactions by itself; it influences pointer-driven window dragging. However, custom title bar content must still follow common keyboard accessibility expectations: |
|
|
||
| Custom title bar layouts often combine interactive controls with non-interactive visual elements using containers like `Grid`, `StackPanel`, or nested structures. These layouts can unintentionally create gaps or regions whose drag behavior the framework cannot reliably infer. As a result, some title bar areas may unexpectedly become non-draggable, leading to inconsistent window movement. | ||
|
|
||
| To ensure predictable dragging behavior, developers need a way to explicitly mark UI elements that should **not** participate in window dragging—typically interactive controls. All remaining areas then function automatically as draggable regions. This proposal introduces the `TitleBar.ExcludeFromDrag` attached property to provide explicit, predictable control. |
There was a problem hiding this comment.
Think ExcludeFromDrag should be renamed to IsDraggable or similar.
There was a problem hiding this comment.
+1 on renaming it to be positive. Although, both IsDraggable and IsDragEnabled make it sound, to me, like the control itself is draggable. What about something like IsDragRegion? Sounds weird, but something in this vein.
There was a problem hiding this comment.
Agree with above comment.
Irrelevant. It's a property, and if the default is Also, in my opinion, something like this should have been discussed and agreed upon, before opening a PR. Note that you are a Microsoft employee and therefore a professional level is inherently expected. |
vinnarayana-msft
changed the title
|
The PR Description, can also contain, "BugFix" as this is one of the pending bugs which we are fixing. |
|
|
||
| # Background | ||
|
|
||
| Custom title bar layouts often combine **interactive controls** and **non‑interactive visual elements** using containers such as `Grid`, `StackPanel`, or deeper nested structures. While this flexibility enables rich and branded title bar designs, it also introduces ambiguity when determining **which parts of the title bar should behave as draggable regions** for moving the window. |
There was a problem hiding this comment.
We should give examples of Interactive and Non Interactive visual elements.
|  | ||
|
|
||
| #### Notes on behavior | ||
| - The framework still uses `ReadLocalValue(IsDragRegionProperty)` to determine whether the developer **explicitly set** a value. If **omitted**, the framework applies the new default drag‑region rules. |
There was a problem hiding this comment.
nit: If we have a link to the new default drag-region rules, it will be great to add (Otherwise we can ignore)
|
@pranav-gupta-msft how does a SPEC (documents for a new feature) fix an existing BUG? Those are two completely different things. |
7 participants
This PR introduces an API specification for addressing custom TitleBar draggability issues. The proposal adds a new attached property, IsDragRegion, allowing developers to explicitly mark UI elements within TitleBar Content that should not participate in window dragging. By excluding interactive controls or specific regions, all remaining title bar areas behave predictably as draggable surfaces.
Fixes
PR Type
Please check the type of change your PR introduces:
Description
Custom title bar layouts often mix interactive elements—like buttons and search boxes—with non‑interactive visual elements. When these elements are arranged using containers such as Grid, StackPanel, or nested layouts, the system cannot reliably determine which parts of the TitleBar.Content should act as the draggable window surface. This can leave some areas unintentionally non‑draggable, resulting in inconsistent window movement.
To make dragging behavior predictable, developers need a simple way to exclude only the interactive elements from contributing to the drag surface, allowing the rest of the title bar to function as expected for window dragging. This proposal introduces an attached property to explicitly mark such elements, improving clarity and control in custom title bar designs.
This work is also part of the improvements tracked in #10421.
A lightweight and explicit API is therefore needed to let developers clearly mark non draggable regions within any TitleBar layout while keeping default behaviour unchanged.
Motivation and Context
Introduce a new attached property:
Developers can use the
TitleBar.ExcludeFromDragattached property to indicate which UI elements in a custom title bar should not act as drag surfaces. Interactive controls are typically excluded from dragging, while all other non‑interactive areas of the title bar automatically function as draggable regions.How Has This Been Tested?
Screenshots (if appropriate):