[API Proposal]: Backdrop switch in WPF

[harshit7962]

Background and motivation

Since the introduction of Fluent Theme, the fluent applications are defaulted to use Mica as their backdrop. The option to choose from other backdrop types is not supported currently, which can restrict design flexibility. Although, an opt-out switch is provided to remove the default backdrop, it is more of a temporary solution and does not offer a complete flexibility that one might desire.

API Proposal

namespace System.Windows
{
    public abstract class WindowBackdrop() 
    {
        private protected WindowBackdrop() { }
    }

    public static class BackdropTypes
    {
        public static WindowBackdrop None { get; }
        public static WindowBackdrop Auto { get; }

        private sealed class NoneBackdrop : WindowBackdrop { }
        private sealed class AutoBackdrop : WindowBackdrop { }
    }

    public sealed class DesktopAcrylicBackdrop : WindowBackdrop { }

    public sealed class MicaBackdrop : WindowBackdrop
    {
        private MicaKind _kind = MicaKind.Base;

        public MicaKind Kind
        {
            get => _kind;
            set
            {
                if (value != MicaKind.Base && value != MicaKind.Alt)
                {
                    throw new ArgumentException("Invalid MicaKind value.");
                }

                _kind = value;

                // Update the backdrop
            }
        }
    }

    public enum MicaKind
    {
        Base = 0,
        Alt = 1
    }

    public class Window
    {
        public static readonly DependencyProperty BackdropProperty = DependencyProperty.Register(
            nameof(Backdrop), 
            typeof(WindowBackdrop), 
            typeof(Window), 
            new PropertyMetadata(BackdropTypes.None, OnBackdropChanged, CoerceBackdrop));

        public WindowBackdrop Backdrop
        {
            get => (WindowBackdrop)GetValue(BackdropProperty);
            set
            {
                if (value == null)
                {
                    throw new ArgumentNullException(nameof(value));
                }

                SetValue(BackdropProperty, value);
            }
        }
    }
}

API Usage

From Xaml
Setting Mica and Acrylic Backdrops

<Window x:Class="SampleApplication.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:local="clr-namespace:SampleApplication" mc:Ignorable="d" 
    Title="Main Window" Height="500" Width="800">
    <Window.Backdrop>
        <MicaBackdrop Kind="Alt" /> <!--Or <DesktopAcrylicBackdrop />-->
    </Window.Backdrop>
    <Grid>
        <Button Content="Click Me" Click="Button_Click" />
    </Grid>
</Window>

Setting None and Auto Backdrops

<Window x:Class="SampleApplication.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:local="clr-namespace:SampleApplication" mc:Ignorable="d" 
    Title="Main Window" Height="500" Width="800" Backdrop="{x:Static BackdropTypes.None}"> <!--Or BackdropTypes.Auto-->
    <Grid>
        <Button Content="Click Me" Click="Button_Click" />
    </Grid>
</Window>

From code-behind:

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();

        // Setting Mica Base Backdrop
        this.Backdrop = new MicaBackdrop();

        // Setting Mica Alt Backdrop
        this.Backdrop = new MicaBackdrop
        {
            Kind = MicaKind.Alt
        };

        // Setting Acrylic Backdrop
        this.Backdrop = new DesktopAcrylicBackdrop();

        // Having no Backdrop
        this.Backdrop = BackdropTypes.None;

        // Setting Auto Backdrop
        this.Backdrop = BackdropTypes.Auto;
    }
}

Remarks

The current infra of BackdropManager relies on DWM_SYSTEMBACKDROP_TYPE and Win32s DwmSetWindowAttribute. This, at the moment does not allow us to configure the various properties of different backdrops. To have future scope of changing this infra and supporting the properties as discussed in the comment below, we have decided to have backdrop classes which would allow us to add the required properties when needed.

DWM_SYSTEMBACKDROP_TYPE enum:

typedef enum DWM_SYSTEMBACKDROP_TYPE {
  DWMSBT_AUTO,
  DWMSBT_NONE,
  DWMSBT_MAINWINDOW,
  DWMSBT_TRANSIENTWINDOW,
  DWMSBT_TABBEDWINDOW
};

Behavior of the APIs

1. Irrespective of the Backdrop, applications on windows 10, or earlier, will not support any backdrop.
2. The default Backdrop of a window is None.
3. Application on High Contrast themes will not have any backdrop, that is, None.

Mapping of current Backdrops with DWM_SYSTEMBACKDROP_TYPE

Current Usage	DWM_SYSTEMBACKDROP_TYPE	Behaviour
<MicaBackdrop Kind="Base" />	DWMSBT_MAINWINDOW	Mica
<MicaBackdrop Kind="Alt" />	DWMSBT_TABBEDWINDOW	Mica-Base
<DesktopAcrylicBackdrop />	DWMSBT_TRANSIENTWINDOW	Acrylic
Backdrop="{x:Static BackdropTypes.None}"	DWMSBT_NONE	No Backdrop
Backdrop="{x:Static BackdropTypes.Auto}"	DWMSBT_Auto	Based on System Settings

Alternative Designs

The previous design

  namespace System.windows
  {
      public class Application
      {
          public BackdropType Backdrop { get; set; }
      }

      public class Window
      {
          public BackdropType Backdrop { get; set; }
      }

      public enum BackdropType
      {
          None,
          Auto,
          MainWindow,
          TransientWindow,
          TabbedWindow
      }
  }

Risks

No response

[miloush]

These should be brushes and/or backdrops, not a predefined enum property. They have parameters, such as TintColor, TintOpacity, TintLuminosityOpacity, FallbackColor which should be settable by developers. I believe at least acrylic can be applied in-app on selected areas.

As such, for windows they should be set application-wide or window-wide using styles in resources, not by adding properties. I also don't think that these effects should be activated by default.

[h3xds1nz]

I fully agree with miloush here, once again, haha. I also believe using the actual names such as Mica, Acrylic, Smoke would make more sense.

[harshit7962]

Based on the discussion above, we have updated the proposal.

cc:/ @dotnet/dotnet-wpf-triage, @RaphProductions

[miloush]

Thanks @harshit7962 that is an improvement.

What the reasoning behind having MicaBackdrop.Kind rather than MicaBackdrop and MicaAltBackdrop? Do you need the backdrops to have a dispatcher affinity? Is there an extensibility story, what does the base abstract class do?

[h3xds1nz]

I wonder whether it should be "System" rather than "Auto".
If we wanted any parity with e.g. ThemeMode, then System would be the way to go imho.

@miloush I believe "Remarks" answer your question with the abstract class.

[harshit7962]

Thank you @miloush and @h3xds1nz for looking into it.

What the reasoning behind having MicaBackdrop.Kind rather than MicaBackdrop and MicaAltBackdrop?

Base and Alt are the variations of MicaBackdrop, even the documentation does not have two different types and they lie under the umbrella of Mica Material. Also, this keeps things somewhat in parity with WinUI syntax, where user can configure the MicaController and choose between Base and BaseAlt. So all in all this avoids any confusion that may suggest MicaBackdrop and MicaAltBackdrop are two completely different types of Backdrop.
Having mentioned that, to keep things in complete parity we can also discuss about MicaKind having BaseAlt instead of Alt.

Is there an extensibility story, what does the base abstract class do?

The extensibility story is the driving idea of having this type of API, although, it is not yet drafted or proposed. The abstract base class is there for two simple reasons. One it signifies that MicaBackdrop and DesktopAcrylicBackdrop are of that family, and second is that it can be used as a blueprint to implement functions/methods that are common to the other classes, again this is keeping the extensibility story in mind.

I wonder whether it should be "System" rather than "Auto".

Yeah, we can have that discussion, although parity with ThemeMode is not being considered here. My thoughts were to keep it in alignment with DWM_SYSTEMBACKDROP_TYPE's DWMSBT_Auto.

[h3xds1nz]

I get the alignment with the enum from definitions, but unless exact semantics of the naming are kept altogether (which we're not doing), I'd be inclined here to go with the "System" as its imho more expressive.