[API Spec] TitleBar's Content Custom Drag Regions

[vinnarayana-msft]

This PR introduces an API specification for improving TitleBar drag region handling. The proposal changes the default drag behavior to automatically exclude interactive controls, and adds TitleBar.IsDragRegion, AutoRefreshDragRegions, and RecomputeDragRegions() to give developers explicit control over which areas of TitleBar Content participate in window dragging.

Fixes

PR Type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

Description

Custom title bar layouts often combine interactive controls—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 TitleBar.Content should act as the draggable window surface. This can leave empty gaps and spacing areas unintentionally non‑draggable, resulting in inconsistent window movement.

This specification introduces two changes to address these issues:

Change 1: New default behavior

The framework now recursively walks the visual tree and automatically excludes only interactive controls from the drag region. Empty gaps and non‑interactive areas become draggable by default without any markup changes.

Change 2: Per‑element overrides and refresh control

A new set of APIs gives developers explicit control over drag region behavior:

• TitleBar.IsDragRegion — A nullable boolean (IReference<Boolean>) attached property that lets developers explicitly mark elements as draggable (True), clickable (False), or framework‑decided (unset / null).
• TitleBar.AutoRefreshDragRegions — When True, subscribes to LayoutUpdated events for continuous automatic drag region refresh. Default is False.
• TitleBar.RecomputeDragRegions() — Manually triggers a full recomputation of drag regions after dynamic content changes.

This work is part of the improvements tracked in #10421.

Motivation and Context

Developers need a predictable way to control which parts of a custom title bar participate in window dragging. The TitleBar.IsDragRegion attached property lets developers override the framework's auto‑detection on any element, while the improved defaults ensure that interactive controls are automatically excluded and all other areas—including empty gaps and non‑interactive visuals—are draggable without additional markup. For dynamic scenarios, AutoRefreshDragRegions provides continuous automatic refresh, and RecomputeDragRegions() enables on‑demand refresh, giving developers full control over drag region behavior in any TitleBar layout.

How Has This Been Tested?

• I have performed a self-review of my own code
• I have added tests to cover my changes

Screenshots (if appropriate):

[vinnarayana-msft]

@microsoft-github-policy-service agree

[ghost1372]

@vinnarayana-msft is there any plan to fix titlebar issues?
here you can find a list of titlebar issues:
microsoft/WindowsAppSDK#5250

[Zakariathr22]

I suggest also using IsDragEnabled instead of ExcludeFromDrag because it avoids negative wording and follows common boolean naming rules.

[vinnarayana-msft]

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.
That said, I’m open to considering alternative names that still convey this opt‑out pattern if there’s a clearer option.

[riverar]

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 ExcludeFromDrag to IsDraggable or IsDragEnabled).

[riverar]

Microsoft Office allows dragging and Microsoft Teams does not. Which one is right?

[Jay-o-Way]

So the property acts as an opt‑out, not an opt‑in

Irrelevant. It's a property, and if the default is true then so be it. A property should always have a neutral or positive phrasing.

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.

[pranav-gupta-msft]

The PR Description, can also contain, "BugFix" as this is one of the pending bugs which we are fixing.

[Jay-o-Way]

@pranav-gupta-msft how does a SPEC (documents for a new feature) fix an existing BUG? Those are two completely different things.

[vinnarayana-msft]

Microsoft Office allows dragging and Microsoft Teams does not. Which one is right?

This can be configured as per app requirements. With the new API's that we provide, the developer has the freedom to configure the behaviour that aligns with their requirements.

[oldnewthing]

Shouldn't the name be AutoRecomputeDragRegions to align with RecomputeDragRegions?

[oldnewthing]

Is this true? In the initial example, the outer Grid does not have the property set, and it is not interactive, so this statement says that the framework decides that it is draggable. Yet it has draggable children.

What is the rule if a parent and child disagree on draggability?

I think the rule is

• If the property is set, then the value of the property is applied to the element and its children. The values on child elements are ignored.
• If the property is not set, and the element is interactive, then the element and its children are excluded from drag. The values on child elements are ignored.
• If the property is not set, and the element is not interactive, then the element is included in drag, but recursion continues into child elements to determine whether child elements are draggable or not.