Add WindowChrome DWM caption/backdrop support

[sisar4]

Introduce modern DWM-driven window chrome: add CaptionTextColorHelper and WindowCaptionAdorner; extend WindowChrome with new enums/properties (FrameMode, CaptionTheme, BackdropType, CornerPreference, caption/border/text colors) and read-only attached properties for per-window state. Rewrite WindowChromeWorker to manage extended-client-area, DWM attributes, backdrop, DPI-aware frame insets, caption buttons and adorner. Expand NativeMethods and Utilities for new DWM/monitor/AppBar APIs. Remove legacy WindowBackdropManager and WindowBackdropType. Integrate with ThemeManager and update Ribbon templates to use WindowChrome extended mode. Add comprehensive unit tests for caption color, frame insets and WindowChrome behavior. Update project includes and internals visibility for tests.

Fixes #11973 11973

Description

Introduces modern DWM-driven window chrome integration for WindowChrome:

• New CaptionTextColorHelper and WindowCaptionAdorner
• New WindowChrome properties/enums: FrameMode, CaptionTheme, BackdropType, CornerPreference, caption/border/text colors, plus read-only attached properties for per-window state
• WindowChromeWorker rewritten to manage extended client area, DWM attributes, backdrop, DPI-aware frame insets, caption buttons and the adorner
• Expanded NativeMethods/Utilities for the new DWM/monitor/AppBar APIs
• Removed legacy WindowBackdropManager/WindowBackdropType
• Ribbon templates and ThemeManager updated to use the new extended chrome mode
• Added unit tests for caption color, frame insets and WindowChrome behavior

Customer Impact

Enables apps to opt into native Mica/Acrylic backdrops, rounded corner preference, and DWM-driven caption/border theming without custom chrome hacks.

Regression

No known regressions have been observed when the new opt-in properties are not used. Because this change substantially updates WindowChromeWorker, additional review and testing are still needed for existing custom-chrome scenarios.

Testing

Added unit tests for the managed property and frame-inset behavior. Native DWM behavior, rendering, DPI transitions, and caption-button interaction were manually verified on Windows 11 (including dpi and high contrast theme).

Risk

Touches WindowChromeWorker internals broadly. The changes are covered by unit tests where practical and are gated behind new opt-in properties. Some behavior, including native DWM integration, rendering, DPI transitions, and caption-button interaction, requires manual validation on supported Windows configurations.

Microsoft Reviewers: Open in CodeFlow

[sisar4]

@sisar4 please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@dotnet-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@dotnet-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@dotnet-policy-service agree company="Microsoft"

Contributor License Agreement

@dotnet-policy-service agree

[sisar4]

I opened this PR before the issue was approved because the changes were already largely implemented in three of my personal projects, covering both WinForms and WPF. I consolidated, adapted, and refactored that existing work (with AI assistance) into a unified WindowChrome extension. I’m sharing it alongside the proposal to enable concrete review of the implementation and API design.

[sisar4]

Estimated impact

Addressed

Issue	Impact
4825, 8543 Snap Layout on custom title bar	In Custom mode, an element with CaptionButtonRole="Maximize" answers as the system maximize button, so the Win11 snap flyout appears. Hover and pressed state come through IsCaptionButtonHovered / IsCaptionButtonPressed, and Click/Command still fire. In ExtendedClientArea, DWM draws its own buttons, so snap works natively. Verified on Win11.
11048, 5854 Title bar customization pain	ExtendedClientArea keeps the system frame: shadow, animations, DWM buttons, snap. Maximized, the client area fits the work area exactly (no overflow, no covered taskbar, auto-hide taskbar handled). Content goes in the caption via TitleBarBounds / CaptionButtonsBounds, and caption/border colors can be set. Not covered: per-button enable/disable (see 4294).
3887 WindowChrome frame sizes wrong on Win10+	Custom mode metrics are unchanged. The new modes replace the hard-coded metrics with frame insets measured from DWM and DPI-correct system metrics (PMv2 and V1), and handle visible frames (high contrast). For the accent-change content shift reported in the comments, see 11204.
10757 RibbonWindow broken with ThemeMode	Under Fluent, RibbonWindow keeps its own template (the style is looked up by DefaultStyleKey), with the QAT in the title bar plus Mica. The Ribbon controls themselves are still not Fluent-styled (out of scope).
9496 MicaAlt not public	BackdropType="Tabbed" (MicaAlt) is public; the internal WindowBackdropType was removed.
8545 Mica/Acrylic backdrop	Window-level Mica/Acrylic/Tabbed, Win11 22H2+, including transparent captions (CaptionColor="Transparent"). Not done: in-app layering/card surfaces, performance measurement.
11906 NRE on CompositionTarget	Fixed as a side effect: all four unguarded dereferences from main now go through null-checked helpers (_SetCompositionBackground / _RestoreCompositionBackground).

Partially addressed

Issue	Impact
9966 Backdrop API proposal	Covers the feature, but the API shape differs: an enum on WindowChrome vs the proposed Window.Backdrop with WindowBackdrop classes (MicaKind, tint parameters). This needs to be reconciled in API review.
4967 Acrylic/Mica brush	Only window-level backdrop. There is no brush for an arbitrary element.
3608 Blur via SetWindowCompositionAttribute	Provides a documented alternative (BackdropType="Acrylic") on Win11 22H2+. Nothing for Win10 or for the undocumented API itself.
11204 Content shifts after a theme/accent change with NonClientFrameEdges	After a theme or color change, the worker now requests a full repaint (InvalidateRect) in every mode where WPF manages the non-client area, Custom included. This matches the workaround in the thread. The fix is verified in ExtendedClientArea; the exact repro of the issue (Custom with NonClientFrameEdges="Left,Right,Bottom") has not been tested yet.
4110 RibbonWindow wrong size	Aero2/AeroLite RibbonWindow now uses the real system frame and DWM buttons, so it should match a plain Window. Not checked against the attached repro. Classic/high-contrast template unchanged.
7769 Rounded corners / snapping with GlassFrameThickness=0	CornerPreference lets DWM decide the corners, and the new modes keep DWM corners and square snapped edges. The Custom + glass 0 path (WPF's own region rounding, white strips, jerky resize) is unchanged.
7573 Close button stays highlighted	A role-based custom button clears its hover state on non-client mouse leave, and the new modes use DWM's own buttons. Plain WPF buttons in Custom mode are unchanged.

Not addressed

Issue	Note
4294 Disable min/max buttons	No new API.
3741 Hit-test precedence (ResizeGrip vs IsHitTestVisibleInChrome)	Order kept for compatibility, in both Custom and ExtendedClientArea.
1176 Resize flicker	Custom mode unchanged. The new modes resize like a standard window, but this was not measured.
3675 Blank caption content (render race)	No direct change.
5853, 10513 White flash on show	Not addressed: no cloaking until WPF draws its first frame.
10858 App.xaml style not applied under Fluent	No real impact. The DefaultStyleKey lookup only matters for subclasses that override DefaultStyleKey.
8540 ThemeManager public API	No public theme API added. The chrome follows ThemeMode internally (CaptionTheme=Auto).