.NET 4.0+

WPF Brushes - Linear Gradient

by Richard Carr, published at http://www.blackwasp.co.uk/LinearGradientBrush.aspx

The one hundred and thirty-sixth part of the Windows Presentation Foundation Fundamentals tutorial continues the examination of the WPF brushes. This article looks at the first of two gradient brushes.

Gradients

WPF supports two styles of gradient brush. These brushes fill an area with colour. Unlike a solid colour brush, gradients provide a smooth transition between two or more shades. For example, you might create a gradient based upon white and black. The output would give a fade between the two colours, transitioning through many shades of grey. With the inclusion of an alpha channel, you might fade between opaque and transparent colours.

The first style of gradient brush is the linear option. With this type of brush, you define a straight line for the direction of colour change. As the line is traversed, the colour changes. Travelling perpendicular to the line, the colour does not vary. WPF also supports radial gradients, where the colour varies within a circle, based upon the distance from a focal point. This article concentrates on linear gradients. We'll look at radial brushes in the next instalment in the tutorial.

Creating a Simple Linear Gradient

To demonstrate the options available with linear gradients, we need a demo solution. Create a new WPF application in Visual Studio named, "LinearGradientBrushDemo". Once ready, replace the XAML in the main window with the code below. The generated window contains six ellipses in a UniformGrid. We'll apply gradients to the shapes in the examples.

<Window x:Class="LinearGradientBrushDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Brush Demo" Height="280" Width="250">
    <UniformGrid Rows="3">
        <Ellipse Stroke="Black" StrokeThickness="5"/>
        <Ellipse Stroke="Black" StrokeThickness="5"/>
        <Ellipse Stroke="Black" StrokeThickness="5"/>
        <Ellipse Stroke="Black" StrokeThickness="5"/>
        <Ellipse Stroke="Black" StrokeThickness="5"/>
        <Ellipse Stroke="Black" StrokeThickness="5"/>
    </UniformGrid>
</Window>

There are two items that need to be defined to create a linear gradient. The first is the direction of the fade, defined as an imaginary line between two co-ordinate pairs. The second is a collection of gradient stops. These determine the colours that will be used and their position within the gradient. The colour of all points between gradient stops is calculated automatically.

The line is defined using the StartPoint and EndPoint properties of the LinearGradientBrush object. By default, these are defined relative to the corners of the bounding box of the item being filled. The co-ordinates (0,0) indicate the top-left of the bounding box and (1,1) represents the bottom right. These happen to be the default values for StartPoint and EndPoint.

If the bounding box is square, the default options will give a gradient at forty-five degrees to horizontal. However, because the points are relative to the bounding box, if it is not square, the angle will be different.

The gradient stops are added to the GradientStops collection, though in XAML the collection does not need to be defined explicitly. Each has two properties. Color sets the colour to use at the stop's position. Offset specifies the position where the colour will be applied. The Offset property is provided as a fraction of the distance along the line from StartPoint to EndPoint. Zero indicates that the gradient stop is at the start of the line. One specifies the colour is at the end point.

As linear gradient brushes are quite complicated, when you add one using XAML you must use property element syntax. To demonstrate, replace the XAML of the first ellipse with the following code:

<Ellipse Stroke="Black" StrokeThickness="5">
    <Ellipse.Fill>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
            <LinearGradientBrush.GradientStops>
                <GradientStop Color="LightBlue" Offset="0"/>
                <GradientStop Color="DarkBlue" Offset="1"/>
            </LinearGradientBrush.GradientStops>
        </LinearGradientBrush>
    </Ellipse.Fill>
</Ellipse>

The gradient's direction follows the imaginary line from the top-left of the bounding box of the ellipse to the bottom-right. The first colour is light blue and is applied at the top-left. The second colour is dark blue and appears at the bottom-right. This means that there is a smooth transition that includes many shades of blue.

NB: As the two gradient stops specify colours at the extremes of the bounding box and these extremes are outside of the filled area, the standard light blue and dark blue will not actually appear in the ellipse.