[API Spec] SystemBackdropElement: WinUI3 Background Acrylic Support #10833
Conversation
Spec for the SystemBackdropHost control
Updated the documentation for SystemBackdropHost to improve clarity and consistency. Adjusted wording for better readability and fixed minor grammatical issues.
Revised the background section to clarify the limitations of hosting system backdrops in WinUI3 compared to WinUI2, and improved the explanation of the `SystemBackdropHost` control.
Updated spec notes and clarified usage instructions for SystemBackdropHost.
Clarified limitations of SystemBackdrop in WinUI3 compared to WinUI2 and improved wording for better understanding.
microsoft-github-policy-service
bot
added
the
needs-triage
godlytalias
changed the title
|
After the official release of SystemBackdropHost, can WinUI 3 add SystemBackdrop in some pop-up Windows to maintain the consistency of the background color of WinUI 3 and WinUI 2 controls? For example: TeachingTip, ToolTip, Commandbar SecondaryCommands, Combobox popup menu, etc... @godlytalias @AjitSurana |
|
This sounds like only the first step required to support a truly UWP-like acrylic-based popup. To fix the existing issues, developer effort still seems necessary to manually rewrite existing It's better to just fix all those issues by updating all those existing controls' |
@HO-COOH Thanks for the response, If we update the template of all controls, that would hit hard on the fundamentals as we would be creating containers to hold the |
|
@godlytalias Can we use it in next release? (v2.0-exp2) |
@ghost1372 Yes it will be available in exp2 release |
@godlytalias If that's the case, is there any difference between this and my AcrylicVisual? My existing solution to all these issues also works by finding a place (create one, usually a container if no suitable place), add this acrylic visual. |
@HO-COOH I see you're using |
Updated the documentation for SystemBackdropHost to clarify usage and limitations, including details on backdrop materials and corner radius behavior.
|
I've added this to the public api review process board: https://aka.ms/winappsdk/api-specs-review This PR will be open for feedback for a month from its opening: October 14th – November 14th FYI @godlytalias |
michael-hawker
added
SpecInReview
and removed
needs-triage
specs/SystemBackdropHost Spec.md
Outdated
| <SystemBackdropHost CornerRadius="4"> | ||
| <SystemBackdropHost.SystemBackdrop> | ||
| <DesktopAcrylicBackdrop /> | ||
| </SystemBackdropHost.SystemBackdrop> | ||
| </SystemBackdropHost> |
There was a problem hiding this comment.
I find this approach as a content item to be weird, and it prevents creating styles with this backdrop. My preference would be a form of brush I can just set as a background brush. In the community call it was mentioned it was hard to do with the current infrastructure, but as an alternative I'd suggest doing this as an attached property instead of a content element. That would allow you to create styles that have the backdrop defined.
There was a problem hiding this comment.
This would also make adding Acrylic support for those controls that need it, breaking changes, that will require devs to re-template to insert this new object into the visual tree right?
There was a problem hiding this comment.
If we need to have an attached property on a Control for SystemBackdrop (I guess you mean similar to what we have on Window / Popup), we would need to have a placeholder container added in the control template beneath other parts of the control so that when the backdrop material is applied, the placementVisual can be added to the particular 'placeholder container'. This would affect the fundamentals especially for apps that have very big visual tree, We didn't want to do that on all control templates for supporting a feature that is not very likely to be applied on all instances of the control.
There was a problem hiding this comment.
@godlytalias Are you saying that WinUI itself doesn't have access to the internal rendering engine to inject this at a lower level when needed? If you're saying it requires re-templating, then you're still thinking of this in terms of adding more FrameworkElements into the UI tree, rather than at the rendering tier level.
Not being able to create custom styles with this setting is a huge break from how we generally develop and designs UIs and easily update and reuse styling. I'd like to be able to do:
<Page.Resources>
<Style TargetType="Grid" x:Key="AcrylicGrid">
<Setter Property="SystemBackdrop.Backdrop">
<Setter.Value>
<DesktopAcrylicBackdrop />
</Setter.Value>
</Setter>
</Style>
</Page.Resources>
<Grid Style="{StaticResource AcrylicGrid}">
</Grid>The current proposal completely prevents this and feels like a quick band-aid solution.
There was a problem hiding this comment.
Yes, We wanted to avoid making lot of changes into the rendering stack of WinUI to support SystemBackdrop. We are looking at bringing the support to WinUI3 in the future more similar to the UWP way of using brush. So we came up with this quick and lightweight solution to bridge the gap and to ensure that critical scenarios are unblocked.
There was a problem hiding this comment.
Totally agree with @dotMorten. Since the WinAppSdk v2.0 will introduce the breaking changes, I don't think this
avoid making lot of changes into the rendering stack of WinUI to support SystemBackdrop
is an issue, especially when you guys target this feature for v2.0.
There was a problem hiding this comment.
@dotMorten @d2phap Thanks for the responses, However the cost of introducing rendering stack changes to support backdrop is not trivial and don't fit into the 2.0 release timelines as well. Moreover as I mentioned above, we have the longterm plan related to compositor to make things work similar to the UWP case, Hence putting such a big cost into making changes to rendering stack is not a wise decision.
Considering the risks & cost of such a solution it was put out of scope for 2.0 release.
We're also evaluating the necessity of bringing this solution down-level to 1.* versions as well, based on the requirements of some critical scenarios.
There was a problem hiding this comment.
Discussion: Why it is not same as WinUI2, means use it as brush property? In proc lifted compositor puts restriction on its implementation.
Z-order is currently based on Xaml order. We could have helper for developers to place this control in right z-order. But covering all cases will be challenging. So, keeping the API simple and developer can place it correctly based on use case.
It will go as control. No change required.
|
Can this help to the WebView2 control to get acrylic/mica background so that if the web page rendered is transparent, it can show the acrylic/mica background? (so that it feels more integrated with Windows) |
|
In the current implementation, a change of the SystemBackdrop property (e.g. in a visual state) leads to a crash because changing the SystemBackdrop property of the object implementing ICompositionSupportsSystemBackdrop does not seem to be supported. This limitation should either be fixed in the code or pointed out in the documentation. |
@lhak Whether you're mentioning about a scenario where the |
Clarified the behavior and properties of SystemBackdropHost, including details on CornerRadius and backdrop connection.
I have investigated this issue again and noticed that switching between the mica and acrylic system backdrops worked fine, but using my custom backdrop caused a crash. I have now found the reason: If the SystemBackdrop property has been set once, then future changes require the backdrop implementation to reuse the compositor of the initial backdrop object. Otherwise, an unauthorized exception will be thrown. I think this should be documented, probably in the ICompositionSupportsSystemBackdrop documentation. Open sourcing the implementation of the inbox backdrops (e.g. MicaController) would also be very helpful. |
Corrected grammatical errors and improved clarity in the documentation regarding the SystemBackdropHost and its functionality in WinUI3.
|
|
||
| * _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._ | ||
| * The element have to be placed as first element in the container (for example as the first child inside a | ||
| panel) for having the backdrop below the contents. (First element added to tree gets rendered first and goes in the bottom of stack) |
There was a problem hiding this comment.
What goes wrong if I place it incorrectly?
There was a problem hiding this comment.
Discussion: What happens if this element is not the first element? It is intended to be used as first element for background effect to work.
UIElement has opacity property. But it may not have effect. Check and update description accordingly.
Check transforms and shadow and call out behavior.
Call out clipping behavior which doesn't align with standard Xaml behavior of clipping to parent. Call out any other behavior which doesn't align with standard FrameworkElement behavior.
Recommended: Change the word to recommend as first element. Clarify how opacity of UIElement effect the behavior.
|
|
||
| Gets or sets the `SystemBackdrop` instance that renders in the host area. The default value is `null`. | ||
|
|
||
| * When you assign a non-null backdrop and the host is loaded, it calls `SystemBackdrop.OnTargetConnected` with a |
There was a problem hiding this comment.
Is this stuff implementation detail, or does a developer need to know this to use the SystemBackdrop properly?
There was a problem hiding this comment.
Recommend: Remove OnTargetConnected/Disconnected details as it works same as SystemBackDropHost.
specs/SystemBackdropHost Spec.md
Outdated
| <SystemBackdropHost CornerRadius="4"> | ||
| <SystemBackdropHost.SystemBackdrop> | ||
| <DesktopAcrylicBackdrop /> | ||
| </SystemBackdropHost.SystemBackdrop> | ||
| </SystemBackdropHost> |
There was a problem hiding this comment.
Discussion: Why it is not same as WinUI2, means use it as brush property? In proc lifted compositor puts restriction on its implementation.
Z-order is currently based on Xaml order. We could have helper for developers to place this control in right z-order. But covering all cases will be challenging. So, keeping the API simple and developer can place it correctly based on use case.
It will go as control. No change required.
|
|
||
| * _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._ | ||
| * The element have to be placed as first element in the container (for example as the first child inside a | ||
| panel) for having the backdrop below the contents. (First element added to tree gets rendered first and goes in the bottom of stack) |
There was a problem hiding this comment.
Discussion: What happens if this element is not the first element? It is intended to be used as first element for background effect to work.
UIElement has opacity property. But it may not have effect. Check and update description accordingly.
Check transforms and shadow and call out behavior.
Call out clipping behavior which doesn't align with standard Xaml behavior of clipping to parent. Call out any other behavior which doesn't align with standard FrameworkElement behavior.
Recommended: Change the word to recommend as first element. Clarify how opacity of UIElement effect the behavior.
|
|
||
| Gets or sets the `SystemBackdrop` instance that renders in the host area. The default value is `null`. | ||
|
|
||
| * When you assign a non-null backdrop and the host is loaded, it calls `SystemBackdrop.OnTargetConnected` with a |
There was a problem hiding this comment.
Recommend: Remove OnTargetConnected/Disconnected details as it works same as SystemBackDropHost.
| public Microsoft.UI.Xaml.Media.SystemBackdrop SystemBackdrop { get; set; } | ||
| public static Microsoft.UI.Xaml.DependencyProperty SystemBackdropProperty { get; } | ||
|
|
||
| public Microsoft.UI.Xaml.CornerRadius CornerRadius { get; set; } |
There was a problem hiding this comment.
Discussion: Should it have CornerRadius or it should just clip based on parent? If parent and systembaclkdrophost has different corner radius, corner area becomes interesting.
Image inside border is analogy.
Recommend: Call out interesting corner clipping cases
godlytalias
changed the title
| * _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._ | ||
| * The element have to be placed as first element in the container (for example as the first child inside a | ||
| panel) for having the backdrop below the contents. (First element added to tree gets rendered first and goes in the bottom of stack) | ||
| * The host only connects to a backdrop while it has a `XamlRoot`. If the element is not in the live tree, the backdrop |
There was a problem hiding this comment.
Should see if we can scrub other uses of "host" in the document. For example, here we talk about the host -- is this talking about the variable named host? Or some other host concept? If the variable named host then should say "The SystemBackdropElement only connects to a backdrop while it has a XamlRoot." Similarly "If the host is not yet loaded.." should be "If the SystemBackdropElement is not yet loaded..." etc.
Later, we say "Gets or sets the SystemBackdrop instance that renders in the host area." What is the "host area"?
| * The host applies a `RectangleClip` on the `PlacementVisual` to achieve the rounded corners. | ||
| * This property only affects the backdrop clip. It does not change layout or round other content layered above the | ||
| `SystemBackdropElement`. | ||
| * Default `CornerRadius` value will be 0 aligning with [control templates](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.cornerradius#remarks) |
There was a problem hiding this comment.
This sounds like the normal behavior of CornerRadius on other elements. How is it different? (There must be something different; otherwise why would we call it out?)
|
Feedback gathering date for this PR has passed; what's the status? |
|
Ping @godlytalias |
|
@godlytalias The continued silence on this PR is making it hard for the community to engage productively. Could you weigh in as soon as you can? Thanks! |
|
@pranav-gupta-msft Can you also chime in here? Why is your team so unresponsive/slow? |
This is the API Spec for the proposed SystemBackdropElement control for supporting Acrylic effect in WinUI3 for controls other than Window & Flyouts
PR Type
Please check the type of change your PR introduces:
Description
Current Behavior
New Behavior
Motivation and Context
How Has This Been Tested?
Screenshots (if appropriate):