SystemBackdrop Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Media

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Base class for custom system backdrops used to render materials like Mica and Acrylic.

public ref class SystemBackdrop : DependencyObject

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 262144)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class SystemBackdrop : DependencyObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 262144)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class SystemBackdrop : DependencyObject

Public Class SystemBackdrop
Inherits DependencyObject

Inheritance: Object Platform::Object IInspectable DependencyObject SystemBackdrop

Derived: Microsoft.UI.Xaml.Media.DesktopAcrylicBackdrop

Microsoft.UI.Xaml.Media.MicaBackdrop

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

This example shows a custom system backdrop class that's implemented using MicaController.

Calling the base OnTargetConnected method initializes the default configuration object returned by GetDefaultSystemBackdropConfiguration to reflect environment changes that affect this SystemBackdrop instance (specified by connectedTarget, XamlRoot).

Although the example on this page does not support sharing MicaSystemBackdrop instances (for example, Window1.SystemBackdrop = Window2.SystemBackdrop = myMicaSystemBackdrop), such sharing is possible and is supported by the built-in MicaBackdrop and DesktopAcrylicBackdrop materials. To implement sharing in a custom material, vectorize the backing ISystemBackdropController storage to keep a separate instance for each usage context (for example, via a map keyed on connectedTarget). Note that SystemBackdrop similarly vectorizes the associated default configuration objects returned by GetDefaultSystemBackdropConfiguration, ensuring the configuration reflects each usage context when SystemBackdrop is shared.

<Window
    ... >
    <Window.SystemBackdrop>
        <local:MicaSystemBackdrop/>
    </Window.SystemBackdrop>

    <!-- XAML content -->

</Window>

public class MicaSystemBackdrop : SystemBackdrop
{
    MicaController micaController;

    protected override void OnTargetConnected(ICompositionSupportsSystemBackdrop connectedTarget, XamlRoot xamlRoot)
    {
        // Call the base method to initialize the default configuration object.
        base.OnTargetConnected(connectedTarget, xamlRoot);

        // This example does not support sharing MicaSystemBackdrop instances.
        if (micaController is not null)
        {
            throw new Exception("This controller cannot be shared");
        }

        micaController = new MicaController();
        // Set configuration.
        SystemBackdropConfiguration defaultConfig = GetDefaultSystemBackdropConfiguration(connectedTarget, xamlRoot);
        micaController.SetSystemBackdropConfiguration(defaultConfig);
        // Add target.
        micaController.AddSystemBackdropTarget(connectedTarget);
    }

    protected override void OnTargetDisconnected(ICompositionSupportsSystemBackdrop disconnectedTarget)
    {
        base.OnTargetDisconnected(disconnectedTarget);

        micaController.RemoveSystemBackdropTarget(disconnectedTarget);
        micaController = null;
    }
}

Remarks

Use this class to create a custom system backdrop. You don't create this class directly (note the protected constructor). Instead, subclass it in order to add your custom support. You can also use one of the built-in derived classes, MicaBackdrop and DesktopAcrylicBackdrop.

Generally, the custom material overrides OnTargetConnected to create and configure a backing ISystemBackdropController, which will manage the CompositionBrush used to fill the backdrop region. The brush's ultimate pixel rendering is affected by:

the environment/policy set via SystemBackdropConfiguration
the material's appearance parameters, exposed via general properties like ISystemBackdropControllerWithTargets.State (Active/Fallback/HighContrast) and material-specific properties like MicaController.Kind (Base/BaseAlt).

The built-in controllers (MicaController and DesktopAcrylicController) support the following parameters for customizing their appearance: FallbackColor, LuminosityOpacity, TintColor, and TintOpacity. The built-in system backdrops (MicaBackdrop and DesktopAcrylicBackdrop) do not expose FallbackColor or the material customization properties (TintOpacity, etc). Instead, they rely on the default Light/Dark configurations of the underlying MicaController and DesktopAcrylicController. To customize these properties, create a custom material class that derives from SystemBackdrop and expose the desired properties.

Constructors

SystemBackdrop()

Initializes a new instance of the SystemBackdrop class.

Properties

Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetDefaultSystemBackdropConfiguration(ICompositionSupportsSystemBackdrop, XamlRoot)	Retrieves a default `SystemBackdropConfiguration` object that can be passed to `ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration`.
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
OnDefaultSystemBackdropConfigurationChanged(ICompositionSupportsSystemBackdrop, XamlRoot)	Override this method to be called when the object returned by `GetDefaultSystemBackdropConfiguration` changes. This is useful if you're using a custom `SystemBackdropConfiguration`.
OnTargetConnected(ICompositionSupportsSystemBackdrop, XamlRoot)	Called when this object is attached to a valid container; for example, when set on `Window.SystemBackdrop`.
OnTargetDisconnected(ICompositionSupportsSystemBackdrop)	Called when this object is cleared from its container.
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to