IVsGradient.DrawGradient(IntPtr, IntPtr, RECT[], RECT[]) Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Draws a given gradient at a specified location.

public:
 int DrawGradient(IntPtr hwnd, IntPtr hdc, cli::array <Microsoft::VisualStudio::OLE::Interop::RECT> ^ gradientRect, cli::array <Microsoft::VisualStudio::OLE::Interop::RECT> ^ sliceRect);

public int DrawGradient (IntPtr hwnd, IntPtr hdc, Microsoft.VisualStudio.OLE.Interop.RECT[] gradientRect, Microsoft.VisualStudio.OLE.Interop.RECT[] sliceRect);

abstract member DrawGradient : nativeint * nativeint * Microsoft.VisualStudio.OLE.Interop.RECT[] * Microsoft.VisualStudio.OLE.Interop.RECT[] -> int

Public Function DrawGradient (hwnd As IntPtr, hdc As IntPtr, gradientRect As RECT(), sliceRect As RECT()) As Integer

Parameters

hwnd

IntPtr

nativeint

[in] Handle of a window containing the region to be painted with a gradient.

hdc

IntPtr

nativeint

[in] Handle of the device context used in drawing the gradient.

gradientRect

RECT[]

[in] The gradient rectangle or containing region, defining the full extent and geometry over which the gradient could be applied.

sliceRect

RECT[]

[in] The slice rectangle, defining the region over which a gradient is actually painted.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell80.idl:

HRESULT IVsGradient::DrawGradient(  
   [in] HWND hwnd,  
   [in] HDC hdc,  
   [in] RECT * gradientRect,  
   [in] RECT * sliceRect  
);  

Both gradientRect and sliceRect must be defined in the coordinate system defined by the window specified by the handle, hwnd.

The Environment SDK supports two type of gradients static and non-static.

For information as to which gradients are static and which are non-static and the implications of this, see __GRADIENTTYPE.

For static gradients, the environment maintains a permanent definition of the gradient rectangle and the gradientRect parameter is ignored.

The slice rectangle specified by the sliceRect parameter should always be contained within the rectangle defined by the rectangle specified by the gradientRect parameter.

The two rectangular regions gradientRect and sliceRect define how the DrawGradient method paints a gradient on a UI element.

The gradientRect rectangle is called the gradient rectangle or containing region. It specifies the full extent and location over which a gradient could be applied.

The sliceRect rectangle is called the slice rectangle and spec specifies the region where the gradient is actually painted.

Masking of gradients can be accomplished by using differently sized gradient and slice rectangles, where the slice rectangle is contained in the gradient rectangle. In this case, only part of a UI element is painted with a gradient, but the gradient pattern is preserved as if the entire gradient rectangle was painted.

For instance, painting a 10 pixel wide frame on a 100 by 100 pixel wide region could be done by

1. defining a gradient rectangle with a RECT structure with corners with an upper-left corner at (0,0) and a lower-right corner at (100,100).

2. defining four 10 pixel wide slice RECT structures,

   • one with an upper-left corner at (0,0) and a lower-right corner at (100,10)

   • one with an upper-left corner at (0,0) and a lower-right corner at (10,100)

   • one with an upper-left corner at (90,0) and a lower-right corner at (100,100)

   • one with an upper-left corner at (0,90) and a lower-right corner at (100,10)

3. calling IVsGradient.DrawGradient four times, once for each slice rectangle and always using the same gradient rectangle.

In addition, rectangular painting may not be satisfactory in certain circumstance, for instance when painting a control with rounded corners, a shark-fin tab or a non rectangular region that is not easily clipped or masked.

In these cases, VSPackages should create the brush for painting a given gradient based on the array or vector of colors returned by the GetGradientVector method.

For instance, complicated file tabs could be drawn by constructing the three components for the tab -- the fin, the text area and the end -- where the components would be drawn through color replacement, and stretching. Each pixel of a particular color would be replaced by the element in the array returned by GetGradientVector corresponding its position on the horizontal axis.

For a more information, see How to: Use Visual Studio Gradient Support.