PathGradientBrush::GetSurroundColors method

The PathGradientBrush::GetSurroundColors method gets the surround colors currently specified for this path gradient brush.


Status GetSurroundColors(
  Color *colors,
  INT   *count



Type: Color*

Pointer to an array that receives the surround colors.


Type: INT*

Pointer to an integer that, on input, specifies the number of colors requested. If the method succeeds, this parameter, on output, receives the number of colors retrieved. If the method fails, this parameter does not receive a value.

Return Value

Type: 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.


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.


The following example creates a PathGradientBrushobject based on a triangular path that is defined by an array of three points. The code calls the PathGradientBrush::SetSurroundColors method of the PathGradientBrushobject to specify a color for each of the points that define the triangle. The PathGradientBrush::GetSurroundColorCount method determines the current number of surround colors (the colors specified for the brush's boundary path). Next, the code allocates a buffer large enough to receive the array of surround colors and calls PathGradientBrush::GetSurroundColors to fill that buffer. Finally the code fills a small square with each of the brush's surround colors.

VOID Example_GetSurColors(HDC hdc)
   Graphics graphics(hdc);

   // Create a path gradient brush and set its surround colors.
   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);
   // Obtain information about the path gradient brush.
   INT colorCount = pthGrBrush.GetSurroundColorCount();
   Color* colors = new Color[colorCount];
   pthGrBrush.GetSurroundColors(colors, &colorCount);

   // Fill a small square with each of the surround colors.
   SolidBrush solidBrush(Color(255, 255, 255, 255));

   for(INT j = 0; j < colorCount; ++j)
      graphics.FillRectangle(&solidBrush, 15*j, 0, 10, 10);

   delete [] colors;


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

See Also

Brushes and Filled Shapes


Creating a Path Gradient

Filling a Shape with a Color Gradient