RadialGradientBrush Class

Definition

Namespace:

Microsoft.UI.Xaml.Media

RadialGradientBrush paints an area with a radial gradient. A center point defines the origin of the gradient, and an ellipse defines the outer bounds of the gradient.

/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.UI.Xaml.Markup.ContentProperty(Name="GradientStops")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.XamlContract, 65536)]
class RadialGradientBrush : XamlCompositionBrushBase

[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="GradientStops")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.XamlContract), 65536)]
public class RadialGradientBrush : XamlCompositionBrushBase

Public Class RadialGradientBrush
Inherits XamlCompositionBrushBase

Inheritance

Object IInspectable DependencyObject Brush XamlCompositionBrushBase RadialGradientBrush

Attributes

MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute ContractVersionAttribute

Examples

Tip

For more info, design guidance, and code examples, see XAML Brushes.

Open the WinUI 3 Gallery app and see the RadialGradientBrush in action.

The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

The following example creates a radial gradient with six gradient stops and uses it to paint a Rectangle.

<Page
  xmlns:media="using:Microsoft.UI.Xaml.Media">

  <Rectangle Width="200" Height="200">
      <Rectangle.Fill>
          <media:RadialGradientBrush>
              <GradientStop Color="Blue" Offset="0.0" />
              <GradientStop Color="Yellow" Offset="0.2" />
              <GradientStop Color="LimeGreen" Offset="0.4" />
              <GradientStop Color="LightBlue" Offset="0.6" />
              <GradientStop Color="Blue" Offset="0.8" />
              <GradientStop Color="LightGray" Offset="1" />
          </media:RadialGradientBrush>
      </Rectangle.Fill>
  </Rectangle>

</Page>

This example creates a radial gradient that uses Absolute mapping mode with custom values for Center, RadiusX, RadiusY and GradientOrigin:

<Page
  xmlns:media="using:Microsoft.UI.Xaml.Media">

  <Rectangle Width="200" Height="200">
      <Rectangle.Fill>
          <media:RadialGradientBrush
            MappingMode="Absolute"
            Center="50,50"
            RadiusX="100"
            RadiusY="100"
            GradientOrigin="100,50"
            >
              <GradientStop Color="Yellow" Offset="0.0" />
              <GradientStop Color="Blue" Offset="1" />
          </media:RadialGradientBrush>
      </Rectangle.Fill>
  </Rectangle>

</Page>

Remarks

Gradient layout

The gradient is drawn within an ellipse that is defined by the Center, RadiusX, and RadiusY properties. Colors for the gradient start at the center of the ellipse and end at the radius.

The colors for the radial gradient are defined by color stops added to the GradientStops collection property. Each gradient stop specifies a color and an offset along the gradient.

The gradient origin defaults to center and can be offset using the GradientOrigin property.

MappingMode defines whether Center, RadiusX, RadiusY and GradientOrigin represent relative or absolute coordinates.

When MappingMode is set to RelativeToBoundingBox, the X and Y values of the three properties are treated as relative to the element bounds, where (0,0) represents the top left and (1,1) represents the bottom right of the element bounds for the Center, RadiusX, and RadiusY properties and (0,0) represents the center for the GradientOrigin property.

When MappingMode is set to Absolute, the X and Y values of the three properties are treated as absolute coordinates within the element bounds.

Windows 10 Version Support

Gradient rendering is supported on Windows 10 version 1903 (v10.0.18362.0) and higher. On previous OS versions the brush will render a solid color specified by the FallbackColor property.

Brushes as XAML resources

Each of the Brush types that can be declared in XAML (SolidColorBrush, LinearGradientBrush, ImageBrush) is intended to be defined as a resource, so that you can reuse that brush as a resource throughout your app. The XAML syntax shown for Brush types is appropriate for defining the brush as a resource. When you declare a brush as a resource, you also need an x:Key attribute that you'll later use to refer to that resource from other UI definitions. For more info on XAML resources and how to use x:Key attribute, see ResourceDictionary and XAML resource references.

The advantage of declaring brushes as resources is that it reduces the number of runtime objects that are needed to construct a UI: the brush is now shared as a common resource that's providing values for multiple parts of the object graph.

If you look at the existing control template definitions for Windows Runtime XAML controls, you'll see that the templates use brush resources extensively (although these are usually SolidColorBrush, not LinearGradientBrush). Many of these resources are system resources, and they use the {ThemeResource} markup extension for the resource reference rather than {StaticResource} markup extension. For more info on how to use system resource brushes in your own control template XAML, see XAML theme resources.

Constructors

RadialGradientBrush()

Initializes a new instance of the RadialGradientBrush class.

Properties

Center	Gets or sets the center of the ellipse that contains the gradient.
CenterProperty	Identifies the Center dependency property.
CompositionBrush	Gets or sets the CompositionBrush used by this XAML brush. (Inherited from XamlCompositionBrushBase)
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)
FallbackColor	The color to use for rendering in case the CompositionBrush can't be rendered. (Inherited from XamlCompositionBrushBase)
GradientOrigin	Gets or sets the gradient's origin (relative to the top left corner).
GradientOriginProperty	Identifies the GradientOrigin dependency property.
GradientStops	Gets or sets the brush's gradient stops.
InterpolationSpace	Gets or sets the color space used to interpolate the gradient's colors.
InterpolationSpaceProperty	Identifies the InterpolationSpace dependency property.
MappingMode	Gets or sets whether the gradient brush's positioning coordinates are absolute or relative to the output area.
MappingModeProperty	Identifies the MappingMode dependency property.
Opacity	Gets or sets the degree of opacity of a Brush. (Inherited from Brush)
RadiusX	Gets or sets the X axis radius of the ellipse that contains the gradient.
RadiusXProperty	Identifies the RadiusX dependency property.
RadiusY	Gets or sets the Y axis radius of the ellipse that contains the gradient.
RadiusYProperty	Identifies the RadiusY dependency property.
RelativeTransform	Gets or sets the transformation that is applied to the brush using relative coordinates. (Inherited from Brush)
SpreadMethod	Gets or sets the type of spread method that specifies how to draw a gradient that starts or ends inside the bounds of the object to be painted.
SpreadMethodProperty	Identifies the SpreadMethod dependency property.
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. (Inherited from XamlCompositionBrushBase)
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. (Inherited from XamlCompositionBrushBase)
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)

See also

• Brush
• SolidColorBrush
• LinearGradientBrush
• GradientBrush
• GradientStop
• XAML brushes
• ResourceDictionary and XAML resource references