| -api-id | -api-type |
|---|---|
T:Microsoft.UI.Xaml.Media.RadialGradientBrush |
winrt class |
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.
This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
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.
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.
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.
Brush, SolidColorBrush, LinearGradientBrush, GradientBrush, GradientStop, Use brushes, ResourceDictionary and XAML resource references
Tip
For more info, design guidance, and code examples, see Brushes.
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).
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>