dotnet / dotnet/wpf

[API Proposal]: Backdrop switch in WPF

Open
#9,966 7 comments 0 reactions 0 assignees View on GitHub
API suggestion
Dominant language
C#
Stars
7.7k
Forks
1.3k
Avg merge
1d 11h
Merged PRs (30d)
61

Description

### 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

```cs
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
```xaml






```

Setting None and Auto Backdrops
```xaml



```

From code-behind:
```cs
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:
```cpp
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 |
|---|---|---|
| `` | `DWMSBT_MAINWINDOW` | Mica |
| `` | `DWMSBT_TABBEDWINDOW` | Mica-Base |
| `` | `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
```cs
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_

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing BackdropManager and its DwmSetWindowAttribute usage, then compare the proposed API with the listed DWM_SYSTEMBACKDROP_TYPE mappings. Done means the backdrop choices, XAML and code-behind examples, Windows 10 fallback, default None behavior, and high-contrast behavior are covered by the implementation and tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.