[API Spec] SystemBackdropElement: WinUI3 Background Acrylic Support

[godlytalias]

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:

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

Description

Current Behavior

New Behavior

Motivation and Context

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):

[Gaoyifei1011]

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

[HO-COOH]

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 ControlTemplate.

It's better to just fix all those issues by updating all those existing controls' ControlTemplate so that no developer effort is needed.

[godlytalias]

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 ControlTemplate.

It's better to just fix all those issues by updating all those existing controls' ControlTemplate so that no developer effort is needed.

@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 placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

[ghost1372]

@godlytalias Can we use it in next release? (v2.0-exp2)

[godlytalias]

@godlytalias Can we use it in next release? (v2.0-exp2)

@ghost1372 Yes it will be available in exp2 release

[HO-COOH]

@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 placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

@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.

[godlytalias]

@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 placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

@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 ContentExternalBackdropLink, so conceptually it would be same. However, ContentExternalBackdropLink API is experimental and so apps won't be able to publish by using it. There is some concerns around making ContentExternalBackdropLink stable in current shape. Hence providing this control in WinUI layer for achieving backdrops. Moreover I see you're trying to achieve backdrop behavior in combobox, Better way to achieve that may be to apply a custom style of combobox where a SystemBackdrop would be applied on the Popup in the control template. There is a known issue in positioning of backdrop in that way which would get addressed in upcoming release.

[michael-hawker]

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

[Diegorro98]

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)

[lhak]

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.

[godlytalias]

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 SystemBackdrop property getting updated for the control? I've tested this scenario and didn't see a crash. Could you please clarify more on the repro steps? Thanks

[lhak]

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 SystemBackdrop property getting updated for the control? I've tested this scenario and didn't see a crash. Could you please clarify more on the repro steps? Thanks

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.

[riverar]

Feedback gathering date for this PR has passed; what's the status?

[riverar]

Ping @godlytalias

[riverar]

@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!

[riverar]

@pranav-gupta-msft Can you also chime in here? Why is your team so unresponsive/slow?