How to: Create a Path Gradient

Article
02/21/2011

The PathGradientBrush class allows you to customize the way you fill a shape with gradually changing colors. For example, you can specify one color for the center of a path and another color for the boundary of a path. You can also specify separate colors for each of several points along the boundary of a path.

Note

In GDI+, a path is a sequence of lines and curves maintained by a GraphicsPath object. For more information about GDI+ paths, see Graphics Paths in GDI+ and Constructing and Drawing Paths.

To fill an ellipse with a path gradient

The following example fills an ellipse with a path gradient brush. The center color is set to blue and the boundary color is set to aqua. The following illustration shows the filled ellipse.

Gradient Path

By default, a path gradient brush does not extend outside the boundary of the path. If you use the path gradient brush to fill a figure that extends beyond the boundary of the path, the area of the screen outside the path will not be filled.

The following illustration shows what happens if you change the FillEllipse call in the following code to e.Graphics.FillRectangle(pthGrBrush, 0, 10, 200, 40).

Gradient Path

        ' Create a path that consists of a single ellipse.
        Dim path As New GraphicsPath()
        path.AddEllipse(0, 0, 140, 70)

        ' Use the path to construct a brush.
        Dim pthGrBrush As New PathGradientBrush(path)

        ' Set the color at the center of the path to blue.
        pthGrBrush.CenterColor = Color.FromArgb(255, 0, 0, 255)

        ' Set the color along the entire boundary 
        ' of the path to aqua.
        Dim colors As Color() = {Color.FromArgb(255, 0, 255, 255)}
        pthGrBrush.SurroundColors = colors

        e.Graphics.FillEllipse(pthGrBrush, 0, 0, 140, 70)

        // Create a path that consists of a single ellipse.
        GraphicsPath path = new GraphicsPath();
        path.AddEllipse(0, 0, 140, 70);

        // Use the path to construct a brush.
        PathGradientBrush pthGrBrush = new PathGradientBrush(path);

        // Set the color at the center of the path to blue.
        pthGrBrush.CenterColor = Color.FromArgb(255, 0, 0, 255);

        // Set the color along the entire boundary 
        // of the path to aqua.
        Color[] colors = { Color.FromArgb(255, 0, 255, 255) };
        pthGrBrush.SurroundColors = colors;

        e.Graphics.FillEllipse(pthGrBrush, 0, 0, 140, 70);

The preceding code example is designed for use with Windows Forms, and it requires the PaintEventArgs e, which is a parameter of PaintEventHandler.

To specify points on the boundary

The following example constructs a path gradient brush from a star-shaped path. The code sets the CenterColor property, which sets the color at the centroid of the star to red. Then the code sets the SurroundColors property to specify various colors (stored in the colors array) at the individual points in the points array. The final code statement fills the star-shaped path with the path gradient brush.

' Put the points of a polygon in an array.
Dim points As Point() = { _
   New Point(75, 0), _
   New Point(100, 50), _
   New Point(150, 50), _
   New Point(112, 75), _
   New Point(150, 150), _
   New Point(75, 100), _
   New Point(0, 150), _
   New Point(37, 75), _
   New Point(0, 50), _
   New Point(50, 50)}

' Use the array of points to construct a path.
Dim path As New GraphicsPath()
path.AddLines(points)

' Use the path to construct a path gradient brush.
Dim pthGrBrush As New PathGradientBrush(path)

' Set the color at the center of the path to red.
pthGrBrush.CenterColor = Color.FromArgb(255, 255, 0, 0)

' Set the colors of the points in the array.
Dim colors As Color() = { _
   Color.FromArgb(255, 0, 0, 0), _
   Color.FromArgb(255, 0, 255, 0), _
   Color.FromArgb(255, 0, 0, 255), _
   Color.FromArgb(255, 255, 255, 255), _
   Color.FromArgb(255, 0, 0, 0), _
   Color.FromArgb(255, 0, 255, 0), _
   Color.FromArgb(255, 0, 0, 255), _
   Color.FromArgb(255, 255, 255, 255), _
   Color.FromArgb(255, 0, 0, 0), _
   Color.FromArgb(255, 0, 255, 0)}

pthGrBrush.SurroundColors = colors

' Fill the path with the path gradient brush.
e.Graphics.FillPath(pthGrBrush, path)

        // Put the points of a polygon in an array.
        Point[] points = {
           new Point(75, 0),
           new Point(100, 50),
           new Point(150, 50),
           new Point(112, 75),
           new Point(150, 150),
           new Point(75, 100),
           new Point(0, 150),
           new Point(37, 75),
           new Point(0, 50),
           new Point(50, 50)};

        // Use the array of points to construct a path.
        GraphicsPath path = new GraphicsPath();
        path.AddLines(points);

        // Use the path to construct a path gradient brush.
        PathGradientBrush pthGrBrush = new PathGradientBrush(path);

        // Set the color at the center of the path to red.
        pthGrBrush.CenterColor = Color.FromArgb(255, 255, 0, 0);

        // Set the colors of the points in the array.
        Color[] colors = {
           Color.FromArgb(255, 0, 0, 0),
           Color.FromArgb(255, 0, 255, 0),
           Color.FromArgb(255, 0, 0, 255), 
           Color.FromArgb(255, 255, 255, 255),
           Color.FromArgb(255, 0, 0, 0),
           Color.FromArgb(255, 0, 255, 0),
           Color.FromArgb(255, 0, 0, 255),
           Color.FromArgb(255, 255, 255, 255),
           Color.FromArgb(255, 0, 0, 0),  
           Color.FromArgb(255, 0, 255, 0)};

        pthGrBrush.SurroundColors = colors;

        // Fill the path with the path gradient brush.
        e.Graphics.FillPath(pthGrBrush, path);

The following example draws a path gradient without a GraphicsPath object in the code. The particular PathGradientBrush constructor in the example receives an array of points but does not require a GraphicsPath object. Also, note that the PathGradientBrush is used to fill a rectangle, not a path. The rectangle is larger than the closed path used to define the brush, so some of the rectangle is not painted by the brush. The following illustration shows the rectangle (dotted line) and the portion of the rectangle painted by the path gradient brush.

Gradient

' Construct a path gradient brush based on an array of points.
Dim ptsF As PointF() = { _
   New PointF(0, 0), _
   New PointF(160, 0), _
   New PointF(160, 200), _
   New PointF(80, 150), _
   New PointF(0, 200)}

Dim pBrush As New PathGradientBrush(ptsF)

' An array of five points was used to construct the path gradient
' brush. Set the color of each point in that array.  
'Point (0, 0) is red
'Point (160, 0) is green
'Point (160, 200) is green
'Point (80, 150) is blue
'Point (0, 200) is red
Dim colors As Color() = { _
   Color.FromArgb(255, 255, 0, 0), _
   Color.FromArgb(255, 0, 255, 0), _
   Color.FromArgb(255, 0, 255, 0), _
   Color.FromArgb(255, 0, 0, 255), _
   Color.FromArgb(255, 255, 0, 0)}
pBrush.SurroundColors = colors

' Set the center color to white.
pBrush.CenterColor = Color.White

' Use the path gradient brush to fill a rectangle.
e.Graphics.FillRectangle(pBrush, New Rectangle(0, 0, 160, 200))

// Construct a path gradient brush based on an array of points.
PointF[] ptsF = {
   new PointF(0, 0), 
   new PointF(160, 0), 
   new PointF(160, 200),
   new PointF(80, 150),
   new PointF(0, 200)};

PathGradientBrush pBrush = new PathGradientBrush(ptsF);

// An array of five points was used to construct the path gradient
// brush. Set the color of each point in that array.
Color[] colors = {
   Color.FromArgb(255, 255, 0, 0),  // (0, 0) red
   Color.FromArgb(255, 0, 255, 0),  // (160, 0) green
   Color.FromArgb(255, 0, 255, 0),  // (160, 200) green
   Color.FromArgb(255, 0, 0, 255),  // (80, 150) blue
   Color.FromArgb(255, 255, 0, 0)}; // (0, 200) red

pBrush.SurroundColors = colors;

// Set the center color to white.
pBrush.CenterColor = Color.White;

// Use the path gradient brush to fill a rectangle.
e.Graphics.FillRectangle(pBrush, new Rectangle(0, 0, 160, 200));

To customize a path gradient

One way to customize a path gradient brush is to set its FocusScales property. The focus scales specify an inner path that lies inside the main path. The center color is displayed everywhere inside that inner path rather than only at the center point.

The following example creates a path gradient brush based on an elliptical path. The code sets the boundary color to blue, sets the center color to aqua, and then uses the path gradient brush to fill the elliptical path.

Next, the code sets the focus scales of the path gradient brush. The x focus scale is set to 0.3, and the y focus scale is set to 0.8. The code calls the TranslateTransform method of a Graphics object so that the subsequent call to FillPath fills an ellipse that sits to the right of the first ellipse.

To see the effect of the focus scales, imagine a small ellipse that shares its center with the main ellipse. The small (inner) ellipse is the main ellipse scaled (about its center) horizontally by a factor of 0.3 and vertically by a factor of 0.8. As you move from the boundary of the outer ellipse to the boundary of the inner ellipse, the color changes gradually from blue to aqua. As you move from the boundary of the inner ellipse to the shared center, the color remains aqua.

The following illustration shows the output of the following code. The ellipse on the left is aqua only at the center point. The ellipse on the right is aqua everywhere inside the inner path.

Gradient

        ' Create a path that consists of a single ellipse.
        Dim path As New GraphicsPath()
        path.AddEllipse(0, 0, 200, 100)

        ' Create a path gradient brush based on the elliptical path.
        Dim pthGrBrush As New PathGradientBrush(path)

        ' Set the color along the entire boundary to blue.
        ' Changed variable name from color
        Dim blueColor As Color() = {Color.Blue}
        pthGrBrush.SurroundColors = blueColor

        ' Set the center color to aqua.
        pthGrBrush.CenterColor = Color.Aqua

        ' Use the path gradient brush to fill the ellipse. 
        e.Graphics.FillPath(pthGrBrush, path)

        ' Set the focus scales for the path gradient brush.
        pthGrBrush.FocusScales = New PointF(0.3F, 0.8F)

        ' Use the path gradient brush to fill the ellipse again.
        ' Show this filled ellipse to the right of the first filled ellipse.
        e.Graphics.TranslateTransform(220.0F, 0.0F)
        e.Graphics.FillPath(pthGrBrush, path)

// Create a path that consists of a single ellipse.
GraphicsPath path = new GraphicsPath();
path.AddEllipse(0, 0, 200, 100);

// Create a path gradient brush based on the elliptical path.
PathGradientBrush pthGrBrush = new PathGradientBrush(path);

// Set the color along the entire boundary to blue.
Color[] color = { Color.Blue };
pthGrBrush.SurroundColors = color;

// Set the center color to aqua.
pthGrBrush.CenterColor = Color.Aqua;

// Use the path gradient brush to fill the ellipse. 
e.Graphics.FillPath(pthGrBrush, path);

// Set the focus scales for the path gradient brush.
pthGrBrush.FocusScales = new PointF(0.3f, 0.8f);

// Use the path gradient brush to fill the ellipse again.
// Show this filled ellipse to the right of the first filled ellipse.
e.Graphics.TranslateTransform(220.0f, 0.0f);
e.Graphics.FillPath(pthGrBrush, path);

To customize with interpolation

Another way to customize a path gradient brush is to specify an array of interpolation colors and an array of interpolation positions.

The following example creates a path gradient brush based on a triangle. The code sets the InterpolationColors property of the path gradient brush to specify an array of interpolation colors (dark green, aqua, blue) and an array of interpolation positions (0, 0.25, 1). As you move from the boundary of the triangle to the center point, the color changes gradually from dark green to aqua and then from aqua to blue. The change from dark green to aqua happens in 25 percent of the distance from dark green to blue.

The following illustration shows the triangle filled with the custom path gradient brush.

Gradient Path

        ' Vertices of the outer triangle
        Dim points As Point() = { _
           New Point(100, 0), _
           New Point(200, 200), _
           New Point(0, 200)}

        ' No GraphicsPath object is created. The PathGradientBrush
        ' object is constructed directly from the array of points.
        Dim pthGrBrush As New PathGradientBrush(points)

        ' Create an array of colors containing dark green, aqua, and  blue.
        Dim colors As Color() = { _
           Color.FromArgb(255, 0, 128, 0), _
           Color.FromArgb(255, 0, 255, 255), _
           Color.FromArgb(255, 0, 0, 255)}

        ' Dark green is at the boundary of the triangle.
        ' Aqua is 40 percent of the way from the boundary to the center point.
        ' Blue is at the center point.
        Dim relativePositions As Single() = { _
           0.0F, _
           0.4F, _
           1.0F}

        Dim colorBlend As New ColorBlend()
        colorBlend.Colors = colors
        colorBlend.Positions = relativePositions
        pthGrBrush.InterpolationColors = colorBlend

        ' Fill a rectangle that is larger than the triangle
        ' specified in the Point array. The portion of the
        ' rectangle outside the triangle will not be painted.
        e.Graphics.FillRectangle(pthGrBrush, 0, 0, 200, 200)

// Vertices of the outer triangle
Point[] points = {
   new Point(100, 0),
   new Point(200, 200),
   new Point(0, 200)};

// No GraphicsPath object is created. The PathGradientBrush
// object is constructed directly from the array of points.
PathGradientBrush pthGrBrush = new PathGradientBrush(points);

Color[] colors = {
   Color.FromArgb(255, 0, 128, 0),    // dark green
   Color.FromArgb(255, 0, 255, 255),  // aqua
   Color.FromArgb(255, 0, 0, 255)};   // blue

float[] relativePositions = {
   0f,       // Dark green is at the boundary of the triangle.
   0.4f,     // Aqua is 40 percent of the way from the boundary
             // to the center point.
   1.0f};    // Blue is at the center point.

ColorBlend colorBlend = new ColorBlend();
colorBlend.Colors = colors;
colorBlend.Positions = relativePositions;
pthGrBrush.InterpolationColors = colorBlend;

// Fill a rectangle that is larger than the triangle
// specified in the Point array. The portion of the
// rectangle outside the triangle will not be painted.
e.Graphics.FillRectangle(pthGrBrush, 0, 0, 200, 200);

To set the center point

By default, the center point of a path gradient brush is at the centroid of the path used to construct the brush. You can change the location of the center point by setting the CenterPoint property of the PathGradientBrush class.

The following example creates a path gradient brush based on an ellipse. The center of the ellipse is at (70, 35), but the center point of the path gradient brush is set to (120, 40).

' Create a path that consists of a single ellipse.
Dim path As New GraphicsPath()
path.AddEllipse(0, 0, 140, 70)

' Use the path to construct a brush.
Dim pthGrBrush As New PathGradientBrush(path)

' Set the center point to a location that is not
' the centroid of the path.
pthGrBrush.CenterPoint = New PointF(120, 40)

' Set the color at the center of the path to blue.
pthGrBrush.CenterColor = Color.FromArgb(255, 0, 0, 255)

' Set the color along the entire boundary 
' of the path to aqua.
Dim colors As Color() = {Color.FromArgb(255, 0, 255, 255)}
pthGrBrush.SurroundColors = colors

e.Graphics.FillEllipse(pthGrBrush, 0, 0, 140, 70)

        // Create a path that consists of a single ellipse.
        GraphicsPath path = new GraphicsPath();
        path.AddEllipse(0, 0, 140, 70);

        // Use the path to construct a brush.
        PathGradientBrush pthGrBrush = new PathGradientBrush(path);

        // Set the center point to a location that is not
        // the centroid of the path.
        pthGrBrush.CenterPoint = new PointF(120, 40);

        // Set the color at the center of the path to blue.
        pthGrBrush.CenterColor = Color.FromArgb(255, 0, 0, 255);

        // Set the color along the entire boundary 
        // of the path to aqua.
        Color[] colors = { Color.FromArgb(255, 0, 255, 255) };
        pthGrBrush.SurroundColors = colors;

        e.Graphics.FillEllipse(pthGrBrush, 0, 0, 140, 70);

The following illustration shows the filled ellipse and the center point of the path gradient brush.

Gradient Path

You can set the center point of a path gradient brush to a location outside the path that was used to construct the brush. The following example replaces the call to set the CenterPoint property in the preceding code.
```
pthGrBrush.CenterPoint = New PointF(145, 35)
```
```
pthGrBrush.CenterPoint = new PointF(145, 35);
```
The following illustration shows the output with this change.

In the preceding illustration, the points at the far right of the ellipse are not pure blue (although they are very close). The colors in the gradient are positioned as if the fill reached the point (145, 35) where the color would be pure blue (0, 0, 255). But the fill never reaches (145, 35) because a path gradient brush paints only inside its path.

Compiling the Code

The preceding examples are designed for use with Windows Forms, and they require PaintEventArgs e, which is a parameter of the Paint event handler.

How to: Create a Path Gradient

To fill an ellipse with a path gradient

To specify points on the boundary

To customize a path gradient

To customize with interpolation

To set the center point

Compiling the Code

See Also

Other Resources

Additional resources