Walkthrough: Using the Gradient Service in a Tool Window
This walkthrough demonstrates how to use the Visual Studio Integration Package Wizard to create a VSPackage that includes a tool window. The walkthrough then demonstrates how to obtain an interface from a service and how to fill the background of a tool window with a color gradient.
A VSPackage can request a specific interface from a service to access a particular feature. For example, the gradient service lets you fill a region of a window with a particular gradient type. Typically, a VSPackage requests a primary interface from a service and then uses that interface to obtain other interfaces that are associated with that service. With the gradient service, the VSPackage must ask the SVsUIShell service for an IVsUIShell interface, obtain the IVsUIShell2 interface from the IVsUIShell interface, and finally call the CreateGradient method in the IVsUIShell2 interface to obtain the gradient service.
For more information, see Services.
Prerequisites
To complete this walkthrough you need:
- Visual Studio SDK
Creating a VSPackage
This section of the walkthrough demonstrates how to use the Visual Studio Integration Package Wizard to create a VSPackage that includes a tool window.
To create a VSPackage
Start Visual Studio. On the File menu, point to New, and then click Project.
In the New Project dialog box, expand Other Project Types and then click Extensibility.
In the Templates pane, click Visual Studio Integration Package.
Type MyTWGradientPackage in the name box and select a location.
Click OK to start the Visual Studio Integration Package Wizard.
Read the Welcome to the Visual Studio Integration Package Wizard page and then click Next.
On the Select a Programming Language page, select Visual C#, accept the default for the key file and then click Next.
On the Select VSPackage Options page, select Tool Window, and then click Next.
On the Tool Window Options page, type My Gradient Tool Window in the Window Name box, accept the default Command ID, and then click Finish.
The wizard builds the project.
Using the Gradient Service
To use the gradient service, you must obtain an instance of the IVsGradient interface. You use the IVsGradient interface to paint the background of the tool window.
To use the gradient service
In Solution Explorer, right-click MyControl.cs, and then click View Code.
MyControl.cs opens in the text editor.
At the top of the file, add the following lines after the last using statement if not already present:
using Microsoft.VisualStudio; using Microsoft.VisualStudio.Shell.Interop; using Microsoft.VisualStudio.OLE.Interop; using System; using System.Drawing;Before the MyControl class constructor, add a private variable named backgroundGradient with the type, IVsGradient.
private IVsGradient backgroundGradient;At the bottom of the MyControl class, add the GetGradient method.
This method obtains the IVsUIShell2 interface and uses the CreateGradient method to access the gradient service. Notice how the SVsUIShell service obtains the IVsUIShell2 interface.
private IVsGradient GetGradient(__GRADIENTTYPE gradientType) { IVsGradient gradient = null; IVsUIShell uiShell = this.GetService(typeof(SVsUIShell)) as IVsUIShell; if (null != uiShell) { IVsUIShell2 uiShell2 = uiShell as IVsUIShell2; if (null != uiShell2) { uiShell2.CreateGradient((uint)gradientType, out gradient); } } return gradient; }After the GetGradient method that you just added, add the SetBackgroundGradient method.
This method sets the background gradient to the FileTab gradient type.
private void SetBackgroundGradient() { this.backgroundGradient = GetGradient(__GRADIENTTYPE. VSGRADIENT_TOOLWIN_ACTIVE_TITLE_BAR); }After the SetBackgroundGradient method that you just added, add the DoPaintBackground method.
This method uses the gradient to fill the control's background which corresponds to the background of the tool window.
private bool DoPaintBackground(IntPtr hdc, Rectangle clipRectangle) { bool isPainted = false; if (null == this.backgroundGradient) { // Make sure ther is a gradient to work with! SetBackgroundGradient(); } if (null != this.backgroundGradient) { RECT[] gradientRect = new RECT[1]; gradientRect[0].left = clipRectangle.Left; gradientRect[0].top = clipRectangle.Top; gradientRect[0].right = clipRectangle.Right; gradientRect[0].bottom = clipRectangle.Bottom; int hr = this.backgroundGradient.DrawGradient(this.Handle, hdc, gradientRect, gradientRect); isPainted = ErrorHandler.Succeeded(hr); } return isPainted; }Override the OnPaintBackground method and replace the contents with the following lines. Put this new method after the DoPaintBackground method that you added earlier.
注意
In Visual C#, you can type override to see a list of methods that can be overridden. When you select OnPaintBackground from the list, the method is automatically created.
protected override void OnPaintBackground(PaintEventArgs e) { bool isPainted = DoPaintBackground(e.Graphics.GetHdc(), e.ClipRectangle); e.Graphics.ReleaseHdc(); if (!isPainted) { // Gradient did not work, use the default. base.OnPaintBackground(e); } }On the Build menu, click Build Solution to compile the code.
Make sure there are no errors. This step registers the VSPackage and its tool window with Visual Studio.
Press F5 to start an instance of the experimental build of Visual Studio.
This runs the experimental build of Visual Studio under the debugger.
In the experimental build of Visual Studio, on the View menu, point to Other Windows, and then click My Gradient Tool Window.
This displays your tool window.
Notice that the background of your tool window has a subtle blue gradient that moves from light to dark, top to bottom. You can try other __GRADIENTTYPE values, but you must exit the experimental build of Visual Studio, recompile your VSPackage, and then open the experimental build of Visual Studio to see the changes.