XamlCompositionBrushBase Class
Definition
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.
Provides a base class used to create XAML brushes that paint an area with a CompositionBrush.
public ref class XamlCompositionBrushBase : Brush
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class XamlCompositionBrushBase : Brush
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class XamlCompositionBrushBase : Brush
Public Class XamlCompositionBrushBase
Inherits Brush
- Inheritance
- Derived
- Attributes
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;
}
}
}
For the C++/WinRT code example below, you'll need to add a Midl File (.idl) file to your project.
// BackdropBlurBrush.idl
namespace MyApp
{
[default_interface]
runtimeclass BackdropBlurBrush : Windows.UI.Xaml.Media.XamlCompositionBrushBase
{
BackdropBlurBrush();
static Windows.UI.Xaml.DependencyProperty BlurAmountProperty{ get; };
Double BlurAmount;
}
}
// pch.h
// You'll need to install the Microsoft Win2D NuGet package for this code example.
#include <winrt/Microsoft.Graphics.Canvas.Effects.h>
#include <winrt/Windows.Graphics.Effects.h>
// BackdropBlurBrush.h.
struct BackdropBlurBrush : BackdropBlurBrushT<BackdropBlurBrush>
{
BackdropBlurBrush() = default;
static Windows::UI::Xaml::DependencyProperty BlurAmountProperty() { return m_blurAmountProperty; }
double BlurAmount()
{
return winrt::unbox_value<double>(GetValue(m_blurAmountProperty));
}
void BlurAmount(double value)
{
SetValue(m_blurAmountProperty, winrt::box_value(value));
}
void OnConnected();
void OnDisconnected();
static void OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject const& d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs const& e);
private:
static Windows::UI::Xaml::DependencyProperty m_blurAmountProperty;
};
// WindowBlurBrush.cpp.
Windows::UI::Xaml::DependencyProperty BackdropBlurBrush::m_blurAmountProperty =
Windows::UI::Xaml::DependencyProperty::Register(
L"BlurAmount",
winrt::xaml_typename<double>(),
winrt::xaml_typename<MyApp::BackdropBlurBrush>(),
Windows::UI::Xaml::PropertyMetadata{ winrt::box_value(0.), Windows::UI::Xaml::PropertyChangedCallback{ &BackdropBlurBrush::OnBlurAmountChanged } }
);
void BackdropBlurBrush::OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject const& d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs const& e)
{
auto brush{ d.as<MyApp::BackdropBlurBrush>() };
// Unbox and set a new blur amount if the CompositionBrush exists.
if (brush.CompositionBrush() != nullptr)
{
brush.CompositionBrush().Properties().InsertScalar(L"Blur.BlurAmount", (float)winrt::unbox_value<double>(e.NewValue()));
}
}
void BackdropBlurBrush::OnConnected()
{
// Delay creating composition resources until they're required.
if (!CompositionBrush())
{
auto backdrop{ Windows::UI::Xaml::Window::Current().Compositor().CreateBackdropBrush() };
// Use a Win2D blur affect applied to a CompositionBackdropBrush.
Microsoft::Graphics::Canvas::Effects::GaussianBlurEffect graphicsEffect{};
graphicsEffect.Name(L"Blur");
graphicsEffect.BlurAmount(this->BlurAmount());
graphicsEffect.Source(Windows::UI::Composition::CompositionEffectSourceParameter(L"backdrop"));
auto effectFactory{ Windows::UI::Xaml::Window::Current().Compositor().CreateEffectFactory(graphicsEffect, { L"Blur.BlurAmount" }) };
auto effectBrush{ effectFactory.CreateBrush() };
effectBrush.SetSourceParameter(L"backdrop", backdrop);
CompositionBrush(effectBrush);
}
}
void BackdropBlurBrush::OnDisconnected()
{
// Dispose of composition resources when no longer in use.
if (CompositionBrush())
{
CompositionBrush(nullptr);
}
}
// 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:
For C++/WinRT, also add #include "BackdropBlurBrush.h"
to MainPage.h
.
<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() |
Provides base class initialization behavior for XamlCompositionBrushBase derived classes. |
Properties
CompositionBrush |
Gets or sets the CompositionBrush used by this XAML brush. |
Dispatcher |
Always returns |
DispatcherQueue |
Gets the |
FallbackColor |
The color to use for rendering in case the CompositionBrush can't be rendered. |
FallbackColorProperty |
Identifies the FallbackColor dependency property. |
Opacity |
Gets or sets the degree of opacity of a Brush. (Inherited from Brush) |
RelativeTransform |
Gets or sets the transformation that is applied to the brush using relative coordinates. (Inherited from Brush) |
Transform |
Gets or sets the transformation that is applied to the brush. (Inherited from Brush) |
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) |
GetValue(DependencyProperty) |
Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject) |
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. |
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. |
PopulatePropertyInfo(String, AnimationPropertyInfo) |
Defines a property that can be animated. (Inherited from Brush) |
PopulatePropertyInfoOverride(String, AnimationPropertyInfo) |
When overridden in a derived class, defines a property that can be animated. (Inherited from Brush) |
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) |