PathGradientBrush::SetSurroundColors method (gdipluspath.h)

Article
10/13/2021

The PathGradientBrush::SetSurroundColors method sets the surround colors of this path gradient brush. The surround colors are colors specified for discrete points on the brush's boundary path.

Syntax

Status SetSurroundColors(
  [in]      const Color *colors,
  [in, out] INT         *count
);

Parameters

[in] colors

Type: const Color*

Pointer to an array of Color objects that specify the surround colors.

[in, out] count

Type: INT*

Pointer to an integer that, on input, specifies the number of Color objects in the colors array. If the method succeeds, this parameter, on output, receives the number of surround colors set. If the method fails, this parameter does not receive a value.

Return value

Type: Status

If the method succeeds, it returns Ok, which is an element of the Status enumeration.

If the method fails, it returns one of the other elements of the Status enumeration.

Remarks

A path gradient brush has a boundary path and a center point. The center point is set to a single color, but you can specify different colors for several points on the boundary. For example, suppose you specify red for the center color, and you specify blue, green, and yellow for distinct points on the boundary. Then as you move along the boundary, the color will change gradually from blue to green to yellow and back to blue. As you move along a straight line from any point on the boundary to the center point, the color will change from that boundary point's color to red.

Examples

The following example creates a PathGradientBrush object based on an array of three points that defines a triangular path. The code also initializes an array of three Color objects. The call to the PathGradientBrush::SetSurroundColors method associates each color in the color array with the corresponding (same index) point in the point array. After the surround colors of the path gradient brush have been set, the Graphics::FillRectangle method uses the path gradient brush to paint a rectangle that includes the triangular path.

One edge of the rendered triangle changes gradually from red to green. The next edge changes gradually from green to black, and the third edge changes gradually from black to red. The code does not set the center color, so the center color has the default value of black. As you move along a straight line from any point on the boundary path (triangle) to the center point, the color changes gradually from that boundary point's color to black.

VOID Example_SetSurColor(HDC hdc)
{
   Graphics graphics(hdc);

   Point pts[] = {
      Point(20, 20), 
      Point(100, 20), 
      Point(100, 100)};

   Color cols[] = {
      Color(255, 255, 0, 0),  // red
      Color(255, 0, 255, 0),  // green
      Color(255, 0, 0, 0)};   // black

   INT count = 3;
   PathGradientBrush pthGrBrush(pts, 3);
   pthGrBrush.SetSurroundColors(cols, &count);
   
   graphics.FillRectangle(&pthGrBrush, 0, 0, 200, 200);
}

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	gdipluspath.h (include Gdiplus.h)
Library	Gdiplus.lib
DLL	Gdiplus.dll