Quickstart: Brushes for Windows Phone

  • Article

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

In Windows Phone, to draw objects to the screen you paint them with Brush objects. This Quickstart introduces the different brushes in Windows Phone and how to use them.

This topic contains the following sections.

Introduction to Brushes

You use Brush objects to paint an area with a solid color, a gradient, or an image. If you're familiar with how brushes work in Windows Phone apps running in the browser, then you'll be glad to know that brushes work exactly the same way on the Windows Phone. The one exception is that VideoBrush isn't supported on the Windows Phone.

To paint an object on the screen, such as a Shape or a Control, you use a Brush. You set the Fill property of the Shape or the Background and Foreground properties of a Control to the desired Brush.

The different types of brushes in Windows Phone are SolidColorBrush, LinearGradientBrush, RadialGradientBrush, and ImageBrush.

Solid Color Brushes

A SolidColorBrush paints an area with a single Color, such as red or blue. There are three ways in XAML to define a SolidColorBrush and the color it specifies. You can use predefined color names, hexadecimal color values, or the property element syntax.

Predefined Color Names

You can use a predefined color name, such as Yellow or SlateBlue, to set either the Fill property of a Shape or the Background and Foreground properties of a Control. The XAML parser converts the color name to a Color structure with the correct color channels.

Note

For a chart with all the predefined color names and their corresponding hexadecimal values, see the Color structure.

The following example sets the Fill property of a Rectangle to the predefined color Red.

<StackPanel>
    <Rectangle Width="100" Height="100" Fill="Red" />
</StackPanel>

Hexadecimal Color Values

You can use the hexadecimal value of the color to set either the Fill property of a Shape or the Background and Foreground properties of a Control. The structure of the hexadecimal value is alpha channel (opacity), red channel, green channel, and blue channel. For example, the hexadecimal value #FFFF0000 defines fully opaque red (alpha=FF, red=FF, green=00, and blue=00).

The following example sets the Fill property of a Rectangle to the hexadecimal value #FFFF0000.

<StackPanel>
    <Rectangle Width="100" Height="100" Fill="#FFFF0000" />
</StackPanel>

Property Element Syntax

You can use property element syntax to define a SolidColorBrush. This syntax is more verbose than the previous methods, but it enables you to specify additional settings, such as the brush's Opacity. For more information on XAML syntax, including property element syntax, see Quickstart: Creating a user interface with XAML for Windows Phone 8.

The following example creates a Rectangle and explicitly creates the SolidColorBrush for the Fill property. The Color of the SolidColorBrush is set to Blue and the Opacity is set to 0.5.

<Grid>
    <Rectangle Width="200" Height="150">
        <Rectangle.Fill>
            <SolidColorBrush Color="Blue" Opacity="0.5" />
        </Rectangle.Fill>
    </Rectangle>
</Grid>

Linear Gradient Brushes

A LinearGradientBrush paints an area with a gradient that is defined along a line, called the gradient axis. You specify the gradient's colors and their location along the gradient axis by using GradientStop objects. You can also modify the gradient axis, which enables you to create horizontal and vertical gradients, and to reverse the gradient direction.

The GradientStop is the basic building block of a gradient brush. A gradient stop specifies a Color at an Offset along the gradient axis.

The gradient stop's Color property specifies the color of the gradient stop. You can set the color by using a predefined color name or by specifying the hexadecimal ARGB values.

The gradient stop's Offset property specifies the position of the gradient stop's color on the gradient axis. The Offset is a Double that ranges from 0 to 1. The closer a gradient stop's offset value is to 0, the closer the color is to the start of the gradient. The closer the gradient's offset value is to 1, the closer the color is to the end of the gradient.

The following example creates a linear gradient with four colors and uses it to paint a Rectangle.

<StackPanel>
    <!-- This rectangle is painted with a diagonal linear gradient. -->
    <Rectangle Width="400" Height="200">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
                <GradientStop Color="Yellow" Offset="0.0" />
                <GradientStop Color="Red" Offset="0.25" />
                <GradientStop Color="Blue" Offset="0.75" />
                <GradientStop Color="LimeGreen" Offset="1.0" />
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</StackPanel>

The following image shows how the gradient looks on a Windows Phone.

The color of each point between gradient stops is linearly interpolated as a combination of the color specified by the two bounding gradient stops. The following illustration highlights the gradient stops in the previous example. The circles mark the position of the gradient stops, and the dashed line shows the gradient axis.

You can change the line at which the gradient stops are positioned by setting the brush's StartPoint and EndPoint properties. By manipulating the brush's StartPoint and EndPoint, you can create horizontal and vertical gradients, reverse the gradient direction, condense the gradient spread, and more.

The following example creates a Rectangle that has a LinearGradientBrush as a Fill. The LinearGradientBrush creates two GradientStops, one red and one blue. The red GradientStops is set to an Offset of 0 and the blue GradientStops is set to an Offset of .75. The StartPoint is set to (0,0) and the EndPoint is set to (1,1) which are the default values. The GradientSpreadMethod specifies different ways that the gradient can be drawn. Use the sliders in this example to experiment with the different property values.

Radial Gradient Brushes

Like a LinearGradientBrush, a LinearGradientBrush paints an area with colors that blend together along an axis. A radial gradient brush's axis is defined by a circle; its colors radiate outward from its origin. Use the GradientOrigin, Center, RadiusX, and RadiusY properties, to define the radial gradient.

<StackPanel>
    <!-- This rectangle is painted with a radial gradient. -->
    <Rectangle Width="400" Height="200">
        <Rectangle.Fill>
            <RadialGradientBrush GradientOrigin="0.5,0.5" Center="0.5,0.5" RadiusX="0.5" RadiusY="0.5">
                <GradientStop Color="Yellow" Offset="0" />
                <GradientStop Color="Red" Offset="0.25" />
                <GradientStop Color="Blue" Offset="0.75" />
                <GradientStop Color="LimeGreen" Offset="1" />
            </RadialGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</StackPanel>

The following example creates a radial gradient with four GradientStop settings.

The following illustration shows the gradient created in the previous example. The brush's gradient stops have been highlighted. Notice that even though the results are different, the gradient stops in this example are identical to the gradient stops in the previous linear gradient brush examples.

The following illustration shows several radial gradients with different GradientOrigin, Center, RadiusX, and RadiusY settings.

The following example creates a Rectangle that has a RadialGradientBrush as a Fill. The RadialGradientBrush creates two GradientStops, one red and one blue. The red GradientStops is set at on Offset of 0 and the blue GradientStops is set at on Offset of .75. The GradientOrigin and Center are all set to (0.5, 0.5) and the RadiusX and RadiusY are set to 0.5, which are the default values. Use the sliders in this example to experiment with the different property values.

Image Brushes

An ImageBrush paints an area with an image. It paints the area with a JPEG or PNG image specified by its ImageSource property. You set the ImageSource property with the path of the image to load.

By default, an ImageBrush stretches its image to completely fill the area being painted, possibly distorting the image if the painted area has a different aspect ratio than the image. You can change this behavior by changing the Stretch property from its default value of Fill to None, Uniform, or UniformToFill.

The following example creates an ImageBrush and sets the ImageSource to an image named flower.jpg, which is included as a resource in the app.

See Also

Other Resources

Quickstart: Shapes for Windows Phone