diff --git a/specs/SystemBackdropHost Spec.md b/specs/SystemBackdropHost Spec.md new file mode 100644 index 0000000000..4f6316e8ee --- /dev/null +++ b/specs/SystemBackdropHost Spec.md @@ -0,0 +1,154 @@ +SystemBackdropHost +=== + +# Background + +There are backdrop materials provided in WinUI such as Mica, Acrylic that are subclass of +[Microsoft.UI.Xaml.Media.SystemBackdrop](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop). Currently, it is possible to host a system backdrop only at the window level or on flyouts, but not in a specific area in the visual tree. This have been a major limitation on WinUI3 compared to WinUI2 in achieving the acrylic / mica effects, especially for achieving various animations. + +`SystemBackdropHost` is a lightweight `FrameworkElement` that bridges between the XAML tree and the composition +infrastructure required by `SystemBackdrop`. It creates the required composition components to host the systembackdrop on a specific container, keeps the placement +visual sized to the arranged bounds, and applies the element's `CornerRadius` to the backdrop clip so rounded corners +appear as expected. This control abstracts lot of details for the composition layer and hence make it easy +for WinUI3 developers to implement the acrylic effect in the applications. + +## Goals + +* Provide an intuitive, XAML-friendly way to place a system backdrop anywhere inside application's visual tree. +* Handle connection, disconnection, and sizing so application only have to set a backdrop and position the element. +* Allow to round the hosted backdrop without writing custom composition code. + +## Non-goals + +* Adding a SystemBackdrop property independently on all controls. +* Provide a content container; `SystemBackdropHost` is purely a visual effect surface and does not host child content. + +# Conceptual pages (How To) + +The guidance in the below examples can be followed by developers for adopting +`SystemBackdropHost`. + +# API Pages + +_(Each level-two section below maps to a docs.microsoft.com API page.)_ + +## SystemBackdropHost class + +Use `SystemBackdropHost` to place a SystemBackdrop](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop) anywhere within the XAML layout. + +```csharp +public sealed class SystemBackdropHost : FrameworkElement +``` + +### Examples + +Keep the `SystemBackdropHost` in the bottom of the stack below other contents to achieve the backdrop effect: + +```xml + + + + + + + + + + + + +