How to: Add Gradients to User Interface Elements
The Visual Studio SDK provides gradient support so developers can create consistent user interfaces that support Windows themes. Developers can query the Visual Studio integrated development environment (IDE) for the correct gradient brush to use for a specific type of element.
The IVsGradient interface supports gradients through the IVsUIShell2 interfaces
The Visual Studio SDK supports two types of gradients, static and non-static.
Static gradients have a single instance of a gradient brush, which is maintained by the IDE.
For this reason, a static gradient's brush size, position, and the containing rectangle that defines it are constant.
The VSGRADIENT_SHELLBACKGROUND gradient is a static gradient, beginning in the top-left corner of the main window and extending to the lower-right corner.
Non-static gradients have individual instances of a gradient brush created when DrawGradient is called and the gradient's brush size, position, and its containing rectangle are defined by the method's arguments.
A gradient brush is cached as long as the length and direction of the DrawGradient operation does not change. If it does then the brush is recalculated at the time of use.
For information, see __GRADIENTTYPE.
To use the gradient support
Obtain an instance of the IVsUIShell2 interface.
For COM-based VSPackages, call QueryService, with a service ID of SID_SVsUIShell and an interface ID of IID_IVsUIShell2
For managed code-based VSPackages, call GetService with an argument of (typeof(SVsUIShell)) and casting to the IVsUIShell2 interface.
Choose a value from the __GRADIENTTYPE enumeration to specify the type of component to be painted with a gradient.
For more information, see User Interface Design Guidelines.
Use the selected member of the __GRADIENTTYPE enumeration as an argument to the CreateGradient method of the IVsUIShell2 interface to obtain an appropriate type of IVsGradient interface.
Use the DrawGradient method to paint gradients on simple user interface (UI) elements.
By design, the DrawGradient method paints rectangular areas. However, by clipping or masking the area to be painted prior to calling the DrawGradient method, it is possible to paint a gradient on a non-rectangular region.
For more information, see Window GDI and Graphics.
For more information about using the IVsGradient interface to paint a Tool Window background in managed code, see Walkthrough: Using the Gradient Service in a Tool Window.
Note
A simple rectangular brush may not be satisfactory in certain circumstance. 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 more information, see the DrawGradient method.
Example
The following C++ example paints a gradient on a rectangular tool tab.
if (pServiceProvider){
CComPtr<IVsUIShell2> pUIShell2;
CComPtr<IVsGradient> pGradient;
pServiceProvider->QueryService(SID_SVsUIShell, IID_IVsUIShell2, (void**)&pUIShell2);
if (pUIShell2){
pUIShell2->CreateGradient(VSGRADIENT_TOOLTAB, &pGradient);
if (pGradient) {
RECT rc;
GetClientRect(hwnd, &rc);
pGradient->DrawGradient(hwnd, (HDC)wParam, &rc, &rc);
return 1;
}
}
}
In the above example, the code:
Obtains an IVsUIShell2 interface.
Obtains an IVsGradient interface that supports tool tabs.
Gets coordinate information about the rectangle to be painted by calling GetClientRect.
Draws the gradient on the tool tab.
In this example, the gradient's rectangle, or containing region, and its slice rectangle within that region are the same. Therefore, the entire containing region, the rectangle returned by GetClientRect, is painted completely.
See Also
Tasks
Walkthrough: Using the Gradient Service in a Tool Window