AcrylicBrush Class

Definition

Namespace:

Microsoft.UI.Xaml.Media

Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Microsoft.UI.Xaml.CustomAttributes.MUXHasCustomActivationFactory]
/// [Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallback(enable=true)]
/// [Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodName(value="OnPropertyChanged")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.XamlContract, 65536)]
class AcrylicBrush : XamlCompositionBrushBase

[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Microsoft.UI.Xaml.CustomAttributes.MUXHasCustomActivationFactory]
[Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallback(enable=true)]
[Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodName(value="OnPropertyChanged")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.XamlContract), 65536)]
public class AcrylicBrush : XamlCompositionBrushBase

Public Class AcrylicBrush
Inherits XamlCompositionBrushBase

Inheritance

XamlCompositionBrushBase

AcrylicBrush

Attributes

MarshalingBehaviorAttribute ThreadingAttribute Microsoft.UI.Xaml.CustomAttributes.MUXHasCustomActivationFactoryAttribute Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackAttribute Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodNameAttribute ContractVersionAttribute

Examples

Tip

For more info, design guidance, and code examples, see Acrylic material.

The WinUI 3 Gallery and WinUI 2 Gallery apps include interactive examples of most WinUI 3 and WinUI 2 controls, features, and functionality.

If installed already, open them by clicking the following links: WinUI 3 Gallery or WinUI 2 Gallery.

If they are not installed, you can download the WinUI 3 Gallery and the WinUI 2 Gallery from the Microsoft Store.

You can also get the source code for both from GitHub (use the main branch for WinUI 3 and the winui2 branch for WinUI 2).

To add an acrylic brush, define the three resources for dark, light, and high contrast themes. Note that in high contrast, we recommend using a SolidColorBrush with the same x:Key as the dark/light AcrylicBrush.

Note

If you don't specify a TintLuminosityOpacity value, the system will automatically adjust its value based on your TintColor and TintOpacity.

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
        <AcrylicBrush x:Key="MyAcrylicBrush"
            BackgroundSource="HostBackdrop"
            TintColor="#FFFF0000"
            TintOpacity="0.8"
            TintLuminosityOpacity="0.5"
            FallbackColor="#FF7F0000"/>
    </ResourceDictionary>

    <ResourceDictionary x:Key="HighContrast">
        <SolidColorBrush x:Key="MyAcrylicBrush"
            Color="{ThemeResource SystemColorWindowColor}"/>
    </ResourceDictionary>

    <ResourceDictionary x:Key="Light">
        <AcrylicBrush x:Key="MyAcrylicBrush"
            BackgroundSource="HostBackdrop"
            TintColor="#FFFF0000"
            TintOpacity="0.8"
            TintLuminosityOpacity="0.5"
            FallbackColor="#FFFF7F7F"/>
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

This example shows how to create an AcrylicBrush in code.

Microsoft.UI.Xaml.Media.AcrylicBrush myBrush = new Microsoft.UI.Xaml.Media.AcrylicBrush();
myBrush.BackgroundSource = Microsoft.UI.Xaml.Media.AcrylicBackgroundSource.HostBackdrop;
myBrush.TintColor = Color.FromArgb(255, 202, 24, 37);
myBrush.FallbackColor = Color.FromArgb(255, 202, 24, 37);
myBrush.TintOpacity = 0.6;

grid.Fill = myBrush;

Remarks

You can easily apply acrylic to your app's surfaces using predefined AcrylicBrush theme resources. First, you'll need to decide whether to use in-app or background acrylic. Be sure to review common app patterns described in the Acrylic material article for recommendations.

We've created a collection of brush theme resources for both background and in-app acrylic types that respect the app's theme and fall back to solid colors as needed. For WinUI 2, these theme resources are located in the AcrylicBrush themeresources file, in the microsoft-ui-xaml GitHub repo. Resources that include Background in their names represent background acrylic, while InApp refers to in-app acrylic.

To paint a specific surface, apply one of the WinUI 2 theme resources to element backgrounds just as you would apply any other brush resource.

<Grid Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}">

Constructors

AcrylicBrush()

Initializes a new instance of the AcrylicBrush class. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Properties

AlwaysUseFallback	Gets or sets a value that specifies whether the brush is forced to the solid fallback color. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
AlwaysUseFallbackProperty	Identifies the AlwaysUseFallback dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
BackgroundSource	Gets or sets a value that specifies whether the brush samples from the app content or from the content behind the app window. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
BackgroundSourceProperty	Identifies the BackgroundSource dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintColor	Gets or sets the color tint for the semi-transparent acrylic material. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintColorProperty	Identifies the TintColor dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintLuminosityOpacity	Gets or sets the degree of opacity of the color's luminosity tint. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintLuminosityOpacityProperty	Identifies the TintLuminosityOpacity dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintOpacity	Gets or sets the degree of opacity of the color tint. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintOpacityProperty	Identifies the TintOpacity dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintTransitionDuration	Gets or sets the length of the automatic transition animation used when the TintColor changes. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TintTransitionDurationProperty	Identifies the TintTransitionDuration dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

See also

• AcrylicBackgroundSource
• Acrylic material overview