XamlCompositionBrushBase
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// This API is not available in Javascript.
- Inheritance
-
XamlCompositionBrushBaseXamlCompositionBrushBaseXamlCompositionBrushBaseXamlCompositionBrushBase
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Inherited Members
Inherited methods
Inherited properties
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>
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.
Constructors
XamlCompositionBrushBase() XamlCompositionBrushBase() XamlCompositionBrushBase() XamlCompositionBrushBase()
Provides base class initialization behavior for XamlCompositionBrushBase derived classes.
protected : XamlCompositionBrushBase()protected XamlCompositionBrushBase()Protected Sub New()// This API is not available in Javascript.
Properties
CompositionBrush 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// This API is not available in Javascript.
The instance of CompositionBrush used by this XAML brush.
FallbackColor 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// This API is not available in Javascript.
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 FallbackColorProperty
Identifies the FallbackColor dependency property.
public : static DependencyProperty FallbackColorProperty { get; }public static DependencyProperty FallbackColorProperty { get; }Public Static ReadOnly Property FallbackColorProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the FallbackColor dependency property.
Methods
OnConnected() 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// This API is not available in Javascript.
OnDisconnected() 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// This API is not available in Javascript.