IVsGradient.DrawGradient Method

Article
05/06/2010

Draws a given gradient at a specified location.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)

Syntax

'Déclaration
Function DrawGradient ( _
    hwnd As IntPtr, _
    hdc As IntPtr, _
    gradientRect As RECT(), _
    sliceRect As RECT() _
) As Integer
'Utilisation
Dim instance As IVsGradient
Dim hwnd As IntPtr
Dim hdc As IntPtr
Dim gradientRect As RECT()
Dim sliceRect As RECT()
Dim returnValue As Integer

returnValue = instance.DrawGradient(hwnd, _
    hdc, gradientRect, sliceRect)

int DrawGradient(
    IntPtr hwnd,
    IntPtr hdc,
    RECT[] gradientRect,
    RECT[] sliceRect
)

int DrawGradient(
    [InAttribute] IntPtr hwnd, 
    [InAttribute] IntPtr hdc, 
    [InAttribute] array<RECT>^ gradientRect, 
    [InAttribute] array<RECT>^ sliceRect
)

abstract DrawGradient : 
        hwnd:IntPtr * 
        hdc:IntPtr * 
        gradientRect:RECT[] * 
        sliceRect:RECT[] -> int

function DrawGradient(
    hwnd : IntPtr, 
    hdc : IntPtr, 
    gradientRect : RECT[], 
    sliceRect : RECT[]
) : int

Parameters

hwnd
Type: System.IntPtr
[in] Handle of a window containing the region to be painted with a gradient.

hdc
Type: System.IntPtr
[in] Handle of the device context used in drawing the gradient.

gradientRect
Type: array<Microsoft.VisualStudio.OLE.Interop.RECT[]
[in] The gradient rectangle or containing region, defining the full extent and geometry over which the gradient could be applied.

sliceRect
Type: array<Microsoft.VisualStudio.OLE.Interop.RECT[]
[in] The slice rectangle, defining the region over which a gradient is actually painted.

Return Value

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

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).
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)
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: Add Gradients to User Interface Elements.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Partager via