Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function fills rectangular regions with a background color that is interpolated from color values specified at the vertices.

Syntax 

BOOL GradientFill(
  HDC 
hdc,
  PTRIVERTEX 
pVertex,
  ULONG 
nVertex,
  PVOID 
pMesh,
  ULONG 
nCount,
  ULONG 
ulMode
);

Parameters

hdc

[in] Handle to the destination device context.

pVertex

[in] Pointer to an array of TRIVERTEXstructures, each of which defines a triangle vertex.

nVertex

[in] The number of vertices in pVertex.

pMesh

[in] Array of GRADIENT_RECTstructures in rectangle mode.

nCount

[in] The number of rectangles in pMesh.

ulMode

[in] Specifies gradient fill mode. The following table shows the possible values for ulMode.

Value Description

GRADIENT_FILL_RECT_H

In this mode, two endpoints describe a rectangle.

The rectangle is defined to have a constant color (specified by the TRIVERTEXstructure) for the left and right edges.

GDI interpolates the color from the left-to-right edge and fills the interior.

GRADIENT_FILL_RECT_V

In this mode, two endpoints describe a rectangle.

The rectangle is defined to have a constant color (specified by the TRIVERTEXstructure) for the top and bottom edges.

GDI interpolates the color from the top-to-bottom edge and fills the interior.

GRADIENT_FILL_TRIANGLE

Not supported.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

To get extended error information, call GetLastError. If the display driver does not support the DrvGradientFillentry point, then GetLastErrorreturns ERROR_NOT_SUPPORTED.

Remarks

To add smooth shading to a rectangle, call GradientFillwith the upper-left and lower-right coordinates of the rectangle.

There are two shading modes used when drawing a rectangle:

  • In horizontal mode, the rectangle is shaded from left to right.

  • In vertical mode, the rectangle is shaded from top to bottom.

The GradientFillfunction uses a mesh method to specify the endpoints of the object to draw. All vertices are passed to GradientFillin the pVertexarray. The pMeshparameter specifies how these vertices are connected to form an object. Each GRADIENT_RECTstructure specifies the index of two vertices in the pVertexarray. These two vertices form the upper left and lower right boundary of one rectangle.

For example, to draw a shaded rectangle from [0,0] to [100,32], define a TRIVERTEXarray with two elements and a single GRADIENT_RECTstructure.

The following example shows a horizontal GradientFillrectangle call.

Note:
To make the following code example easier to read, error checking is not included. This code example should not be used in a release configuration unless it has been modified to include secure error handling.
Copy Code 
TRIVERTEX		vert[2] ;
GRADIENT_RECT	gRect;
vert [0] .x	= 0;
vert [0] .y	= 0;
vert [0] .Red	= 0x0000;
vert [0] .Green  = 0x0000;
vert [0] .Blue   = 0x0000;
vert [0] .Alpha  = 0x0000;
vert [1] .x	= 100;
vert [1] .y	= 32; 
vert [1] .Red	= 0x0000;
vert [1] .Green  = 0x0000;
vert [1] .Blue   = 0xff00;
vert [1] .Alpha  = 0x0000;
gRect.UpperLeft  = 0;
gRect.LowerRight = 1;
GradientFill(hdc,vert,2,&gRect,1,GRADIENT_FILL_RECT_H);

If hdcspecifies a mirrored device context, the horizontal coordinates increase from right to left rather than from left to right.

Requirements

Header windows.h
Library coredll.lib
Windows Embedded CE Windows CE .NET 4.2 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also