Share via


SystemBackdrop Class

Definition

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
Attributes

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

See also