XamlCompositionBrushBase XamlCompositionBrushBase XamlCompositionBrushBase Class

Definition

Provides a base class used to create XAML brushes that paint an area with a CompositionBrush.

public class XamlCompositionBrushBase : Brush, IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtectedpublic class XamlCompositionBrushBase : Brush, IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtectedPublic Class XamlCompositionBrushBase Inherits Brush Implements IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtected
Inheritance
XamlCompositionBrushBaseXamlCompositionBrushBaseXamlCompositionBrushBase
Attributes
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Inherited Members

Inherited methods

Inherited properties

Remarks

You can use XamlCompositionBrushBase to create custom brushes.

For example, it can be used to create a brush that applies effects to XAML UIElements using a CompositionEffectBrush, or a SceneLightingEffect that controls the reflective properties of elements when being lit by a XamlLight, or a whole series of effects chained together to produce something more complex.

When creating a brush, it's usually a good practice to delay creating a CompositionBrush and any related resources until the brush is being used. The OnConnected method is called when a brush is first used on screen to paint an element, so you can override OnConnected to safely create resources only when they're needed. This means you can create an instance of a brush in a ResourceDictionary then reference that brush resource later from other parts of UI definitions and only pay the cost of creating composition resources when the brush is actually in use.

It's also a good practice to dispose of composition resources when they're no longer in use. The OnDisconnected method is called when a brush instance is no longer in use anywhere on the screen, so you can override OnDisconnected to safely dispose of resources. If the brush is later used again after being disconnected then OnConnected will be called again.

Examples

This example shows the definition for a custom brush that draws a blurred copy of whatever is behind a UIElement where the brush is applied using a Win2D blur effect and a CompositionBackdropBrush:

public sealed class BackdropBlurBrush : XamlCompositionBrushBase
{
    public static readonly DependencyProperty BlurAmountProperty = DependencyProperty.Register(
        "BlurAmount",
        typeof(double),
        typeof(BackdropBlurBrush),
        new PropertyMetadata(0.0, new PropertyChangedCallback(OnBlurAmountChanged)
        )
    );

    public double BlurAmount
    {
        get { return (double)GetValue(BlurAmountProperty); }
        set { SetValue(BlurAmountProperty, value); }
    }

    private static void OnBlurAmountChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        var brush = (BackdropBlurBrush)d;
        // Unbox and set a new blur amount if the CompositionBrush exists.
        brush.CompositionBrush?.Properties.InsertScalar("Blur.BlurAmount", (float)(double)e.NewValue);            
    }

    public BackdropBlurBrush()
    {
    }

    protected override void OnConnected()
    {
        // Delay creating composition resources until they're required.
        if (CompositionBrush == null)
        {
            var backdrop = Window.Current.Compositor.CreateBackdropBrush();                

            // Use a Win2D blur affect applied to a CompositionBackdropBrush.
            var graphicsEffect = new GaussianBlurEffect
            {
                Name = "Blur",
                BlurAmount = (float)this.BlurAmount,
                Source = new CompositionEffectSourceParameter("backdrop")
            };

            var effectFactory = Window.Current.Compositor.CreateEffectFactory(graphicsEffect, new[] { "Blur.BlurAmount" });
            var effectBrush = effectFactory.CreateBrush();

            effectBrush.SetSourceParameter("backdrop", backdrop);

            CompositionBrush = effectBrush;
        }
    }

    protected override void OnDisconnected()
    {
        // Dispose of composition resources when no longer in use.
        if (CompositionBrush != null)
        {
            CompositionBrush.Dispose();
            CompositionBrush = null;
        }
    }
}
Public NotInheritable Class BackdropBlurBrush
    Inherits XamlCompositionBrushBase

    Public Shared ReadOnly BlurAmountProperty As DependencyProperty = DependencyProperty.Register(
            "BlurAmount",
            GetType(Double),
            GetType(BackdropBlurBrush),
            New PropertyMetadata(0.0, New PropertyChangedCallback(AddressOf OnBlurAmountChanged)
            )
        )

    Public Property BlurAmount As Double
        Get
            Return DirectCast(GetValue(BlurAmountProperty), Double)
        End Get
        Set
            SetValue(BlurAmountProperty, Value)
        End Set
    End Property

    Private Shared Sub OnBlurAmountChanged(d As DependencyObject, e As DependencyPropertyChangedEventArgs)
        Dim brush = DirectCast(d, BackdropBlurBrush)
        ' Unbox And set a New blur amount if the CompositionBrush exists.
        brush.CompositionBrush?.Properties.InsertScalar("Blur.BlurAmount", Convert.ToSingle(DirectCast(e.NewValue, Double)))
    End Sub

    Protected Overrides Sub OnConnected()
        If Me.CompositionBrush Is Nothing Then

            Dim backdrop As CompositionBackdropBrush = Window.Current.Compositor.CreateBackdropBrush()

            ' Use a Win2D blur affect applied to a CompositionBackdropBrush.
            Dim graphicsEffect As GaussianBlurEffect = New GaussianBlurEffect()
            graphicsEffect.Name = "Blur"
            graphicsEffect.BlurAmount = Me.BlurAmount
            graphicsEffect.Source = New CompositionEffectSourceParameter("backdrop")

            Dim effectFactory As CompositionEffectFactory = Window.Current.Compositor.CreateEffectFactory(graphicsEffect, New String() {"Blur.BlurAmount"})
            Dim effectBrush As CompositionEffectBrush = effectFactory.CreateBrush()

            effectBrush.SetSourceParameter("backdrop", backdrop)

            CompositionBrush = effectBrush
        End If
    End Sub

    Protected Overrides Sub OnDisconnected()
        ' Dispose of composition resources when no longer in use.
        If CompositionBrush IsNot Nothing Then
            CompositionBrush.Dispose()
            CompositionBrush = Nothing
        End If
    End Sub
End Class
// WindowBlurBrush.h:
public ref class BackdropBlurBrush sealed :
    public Windows::UI::Xaml::Media::XamlCompositionBrushBase
{
public:
    BackdropBlurBrush();

    static property Windows::UI::Xaml::DependencyProperty^ BlurAmountProperty
    {
        Windows::UI::Xaml::DependencyProperty^ get() { return m_blurAmountProperty; }
    };

    property double BlurAmount
    {
        double get() 
        {
            return static_cast<double>(GetValue(BlurAmountProperty));
        }
        void set(double value) 
        {
            SetValue(BlurAmountProperty, value);
        }
    };

protected:
    virtual void OnConnected() override;
    virtual void OnDisconnected() override; 
    private:
    static Windows::UI::Xaml::DependencyProperty^ m_blurAmountProperty;
    static void OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject^ d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs^ e);
};

// WindowBlurBrush.cpp:
DependencyProperty^ BackdropBlurBrush::m_blurAmountProperty = DependencyProperty::Register(
    "BlurAmount",
    Platform::String::typeid,
    BackdropBlurBrush::typeid,
    ref new PropertyMetadata(0.0, ref new PropertyChangedCallback(OnBlurAmountChanged))
);

BackdropBlurBrush::BackdropBlurBrush()
{
}

void BackdropBlurBrush::OnBlurAmountChanged(DependencyObject^ d, DependencyPropertyChangedEventArgs^ e)
{
    auto brush = static_cast<BackdropBlurBrush^>(d);
    // Unbox and set a new blur amount if the CompositionBrush exists
    if (brush->CompositionBrush != nullptr)
    {
        brush->CompositionBrush->Properties->InsertScalar("Blur.BlurAmount", (float)static_cast<double>(e->NewValue));
    }
}

void BackdropBlurBrush::OnConnected()
{
    // Delay creating composition resources until they're required
    if (CompositionBrush == nullptr)
    {
        auto backdrop = Window::Current->Compositor->CreateBackdropBrush();

        // Use a Win2D blur affect applied to a CompositionBackdropBrush
        auto graphicsEffect = ref new GaussianBlurEffect();
        graphicsEffect->Name = "Blur";
        graphicsEffect->BlurAmount = static_cast<float>(this->BlurAmount);
        graphicsEffect->Source = ref new CompositionEffectSourceParameter("backdrop");

        auto animatableProperties = ref new Platform::Collections::Vector<Platform::String^>();
        animatableProperties->Append("Blur.BlurAmount");

        auto effectFactory = Window::Current->Compositor->CreateEffectFactory(graphicsEffect, animatableProperties);
        auto effectBrush = effectFactory->CreateBrush();

        effectBrush->SetSourceParameter("backdrop", backdrop);

        CompositionBrush = effectBrush;
    }
}

void BackdropBlurBrush::OnDisconnected()
{
    // Dispose of composition resources when no longer in use
    if (CompositionBrush != nullptr)
    {
        delete CompositionBrush;
        CompositionBrush = nullptr;
    }
}

The above brush can then be used like any other XAML brush type to paint UIElements, for example:

<Ellipse Width="100" Height="100">
    <Ellipse.Fill>
        <local:BackdropBlurBrush BlurAmount="10" />
    </Ellipse.Fill>
</Ellipse>

Constructors

XamlCompositionBrushBase() XamlCompositionBrushBase() XamlCompositionBrushBase()

Provides base class initialization behavior for XamlCompositionBrushBase derived classes.

protected XamlCompositionBrushBase()protected XamlCompositionBrushBase()Protected Sub New()
Attributes

Properties

CompositionBrush CompositionBrush CompositionBrush

Gets or sets the CompositionBrush used by this XAML brush.

protected CompositionBrush CompositionBrush { get; set; }protected CompositionBrush CompositionBrush { get; set; }Protected ReadWrite Property CompositionBrush As CompositionBrush
Value
CompositionBrush CompositionBrush CompositionBrush

The instance of CompositionBrush used by this XAML brush.

Attributes

FallbackColor FallbackColor FallbackColor

The color to use for rendering in case the CompositionBrush can't be rendered.

public Color FallbackColor { get; set; }public Color FallbackColor { get; set; }Public ReadWrite Property FallbackColor As Color
Value
Color Color Color

The color to use for rendering in place of the composition brush.

Attributes

Remarks

Some cases where the CompositionBrush can't be rendered include:

  • in the Visual Studio visual designer
  • when printing
  • in software rendering mode

FallbackColorProperty FallbackColorProperty FallbackColorProperty

Identifies the FallbackColor dependency property.

public static DependencyProperty FallbackColorProperty { get; }public static DependencyProperty FallbackColorProperty { get; }Public Static ReadOnly Property FallbackColorProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the FallbackColor dependency property.

Attributes

Methods

OnConnected() OnConnected() OnConnected()

Invoked when a brush is first used on screen to paint an element.

When implemented in a derived class, you can create a CompositionBrush instance and provide it to the framework by setting the CompositionBrush property.

OnDisconnected will be called when the brush is no longer being used to paint any elements.

protected virtual void OnConnected()protected virtual void OnConnected()Protected Overridable Function OnConnected() As void
Attributes

OnDisconnected() OnDisconnected() OnDisconnected()

Invoked when the brush is no longer being used to paint any elements.

When implemented in a derived class, you can safely dispose of the compostion brush and other composition resources.

OnConnected will be called again if the brush is later used to paint any elements after being disconnected.

protected virtual void OnDisconnected()protected virtual void OnDisconnected()Protected Overridable Function OnDisconnected() As void
Attributes