Working with Microsoft Visual Studio 2005

As you know, most of the windows in Visual Studio have an object model that you can use to program the contents and present data that your code generates. However, at times you might need to display data in a way that the existing tool windows cannot handle. To allow you to display data in a way that is most suitable for your add-in, the Visual Studio object model allows creation of custom tool windows.

There are two ways to create a tool window—one way is with an ActiveX control, and the other is with a .NET User Control. To create a tool window, all you need is an ActiveX control and an add-in that makes a call to the Windows.CreateToolWindow method. CreateToolWindow has the following method signature:

public EnvDTE.Window CreateToolWindow(EnvDTE.AddIn AddInInst, string ProgID, string Caption, string GuidPosition, ref object DocObj)

This method returns a Window object that behaves as any tool window that Visual Studio creates. Here are the arguments for this method:

To demonstrate the use of the CreateToolWindow method, the sample files that accompany this book include an add-in project called VSMediaPlayer. This sample creates a tool window hosting the ActiveX control for Windows Media Player and then, by using the programmable object of the control, plays an audio file. The code that does the work of creating the tool window looks like this:

void CreateMediaPlayerToolWindow() { EnvDTE.Windows windows; EnvDTE.Window mediaPlayerWindow; object controlObject = null; string mediaPlayerProgID = "MediaPlayer.MediaPlayer"; string toolWindowCaption = "Windows Media Player"; string toolWindowGuid = "{}"; //Create and show a tool window that hosts the // Windows Media Player control: windows = applicationObject.Windows; mediaPlayerWindow = windows.CreateToolWindow(addInInstance, mediaPlayerProgID, toolWindowCaption, toolWindowGuid, ref controlObject); mediaPlayerWindow.Visible = true; //Play the Windows "Tada" sound: //Can get only the system directory (Eg: C:\windows\system32), // need to change this to the Windows install dir string mediaFile = System.Environment.GetFolderPath( System.Environment.SpecialFolder.System); mediaFile += "\\..\\media\\tada.wav"; MediaPlayer.IMediaPlayer2 mediaPlayer = (MediaPlayer.IMediaPlayer2)controlObject; mediaPlayer.AutoStart = true; mediaPlayer.FileName = mediaFile; }

The CreateMediaPlayerToolWindow method is called in two places in the sample add-in—once in the OnConnection method and once in the OnStartupComplete method. It must be called twice because of the way add-ins are loaded by Visual Studio. If an add-in is set to load on startup, when Visual Studio starts, the add-in starts loading. This loading process includes calling the OnConnection method. But the OnConnection method is called just before the Visual Studio main window is created and shown. If you call the CreateToolWindow method within OnConnection before the main window is shown, creating the tool window will fail because creating an ActiveX control requires its parent window to be visible. You can check to make sure that the main window has been created by examining the connectMode argument passed to the OnConnection method. If this is set to ext_cm_AfterStartup, the add-in was loaded through the Add-in Manager or by means other than the load on startup flag being set and Visual Studio being started. Therefore, the tool window can be shown when an add-in is loaded by using an OnConnection implementation such as this:

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) { applicationObject = (_DTE)application; addInInstance = (AddIn)addInInst; //If the add-in is loaded from the Add-in Manager dialog, then // create and show the tool window: if(connectMode == Extensibility.ext_ConnectMode.ext_cm_AfterStartup) { CreateMediaPlayerToolWindow(); } }

If the load on startup flag is set and you want to show the tool window when an add-in is loaded, you can create the window in the OnStartupComplete method. This method is called when initialization of Visual Studio is complete, which includes creating and showing the main window. It's as simple as this code snippet:

public void OnStartupComplete(ref System.Array custom) { //If the add-in is loaded at startup, then // create and show the tool window: CreateMediaPlayerToolWindow(); }

To create a tool window by using a .NET user control, you will need to call the Windows2.CreateToolWindow2 method. This method has a signature that is similar to the Windows.CreateToolWindow method, but rather than taking a COM ProgID to identify a control, CreateToolWindow2 takes both a name of a .NET assembly and the full name of a class within that assembly that derives from the .NET Framework's System. Windows.Forms.UserControl class. The signature of the CreateToolWindow2 method is:

public EnvDTE.Window CreateToolWindow2(EnvDTE.AddIn AddInInst, string Assembly, string Class, string Caption, string GuidPosition, ref object DocObj)

The arguments that differ from the CreateToolWindow method are:

Note 

Note When using the CreateToolWindow or CreateToolWindow2 method, you should not use code such as Guid.NewGuid().ToString("B") to pass the GUID string. This code will create a new GUID each time the method is called. Rather, you should declare a variable at class scope such as string toolWindowGuid = "{}"; to create one GUID for each window type. If you ever need to find the Window object for the tool window again, you can locate that window directly with the DTE.Windows. Item(toolWindowGuid) method. Using the same GUID each time also will allow Visual Studio to save the position of the tool window wherever the user has placed the window, so the next time you create the tool window it can be placed back in the same position. You should use this GUID only for a tool window of the same type, and you should never use the same GUID to create multiple or different tool windows.

The Form Layout sample uses the CreateToolWindow2 method to create its user interface. Because the user control implementing the user interface is contained within the same assembly as the add-in code, the assembly name can be found by using the Location property of the System.Reflection.Assembly class. This Assembly class is found with the GetExecutingAssembly static method, and Location returns the full path, with the file:/// protocol. Lastly, because the user control to be hosted is named FormLayoutCtl, and is contained within the FormLayout assembly, the class name passed to CreateToolWindow2 is FormLayout.FormLayoutCtl.

You can also create a programmable object for a tool window created from a .NET User Control. This will allow the users of your add-in to program your tool window, just as they program the Task List window or Toolbox. To expose a programmable object, all you need to do is to define an interface, and then implement that interface on the class that derives from System.Windows.Forms.UserControl. This bit of code shows an interface named IProgrammableObject, providing a programmable object on a control named UserControl1.

public interface IProgrammableObject { void Method(); } public partial class UserControl1 : UserControl, IProgrammableObject { public UserControl1() { InitializeComponent(); } public void Method() { System.Windows.Forms.MessageBox.Show("Method"); } }

With this code to implement a programmable object, you can create the tool window and call Method like this:

object obj = null; EnvDTE80.Windows2 window2 = (EnvDTE80.Windows2)applicationObject.Windows; string thisAssembly = System.Reflection.Assembly.GetExecutingAssembly().Location; EnvDTE.Window win = window2.CreateToolWindow2 (addInInstance, thisAssembly, "MyAddin.UserControl1", "Window Caption", "{}", ref obj); win.Visible = true; IProgrammableObject programmableObj = (IProgrammableObject)obj; programmableObj.Method();

Setting the Tab Picture of a Custom Tool Window

When two or more tool windows are tab-linked together, an image is displayed so the user can quickly recognize the tool windows that are linked together. To set the tab picture for a tool window that's created by an add-in, you use the Window.SetTabPicture method. SetTabPicture takes as its argument a COM IPictureDisp type, a bitmap handle, or a path to a bitmap file (a file with the extension .bmp) such as C:\somebitmap.bmp. To create an IPictureDisp object, you can use the same technique described earlier of calling the OleLoadPictureFile method and then passing the returned IPictureDisp object to the SetTabPicture method. Bitmap handles can be retrieved by loading a bitmap file by using any of the various ways that an image can be loaded into an instance of the .NET Framework's Bitmap class (such as from a resource embedded within the add-in's assembly), then the Bitmap.Handle property is called to retrieve the handle.

The bitmap to place onto a tool window tab must have one of two specific formats, and any deviation from these formats can cause the bitmap to appear with incorrect colors or not appear at all. The first format is for a 16-color bitmap, and it must be 16 by 16 pixels. If any portion of the bitmap is to appear transparent, the transparent pixels must have the RGB value 0,254,0. The format for this bitmap is the same format used for displaying custom pictures on command bar buttons; a bitmap can be shared for these two uses. The other format is for high-color bitmaps; it must use 24-bit color, and it, too, needs to be 16 by 16 pixels. If any portion of this bitmap is to appear transparent, the color to use is to have the RGB value 255,0,255.

You can call the Window.SetTabPicture method only on a tool window created by using the Windows.CreateToolWindow method. Windows defined by Visual Studio already have their bitmaps set; if you try to change them, an exception will be generated. If you want to set the bitmap for your own tool window, you should set it before setting the Visible property of your window to true; otherwise, the picture might not be displayed immediately. Lastly, if a custom picture is not set, Visual Studio uses a default picture—the Visual Studio logo.

Setting the Selection Object

As you select different windows in Visual Studio, you see the Properties window update itself with properties available for those windows. For example, if you select a file in Solution Explorer, a set of properties is made available—such as the file path, when the file was modified, or how the file should be built. When you create a tool window, you might also want to have properties for your tool window appear in the Properties window. You set items to appear in the Properties window by using the Window.SetSelectionContainer method, which takes as a parameter an array of type System.Object. These items are displayed in the Properties window when the window that has this method called on it becomes the active window. The sample VSMediaPlayerAdv, an extension to the VSMediaPlayer sample, displays a property set in the Properties window by calling the SetSelectionContainer method with the programmable object of Windows Media Player, which was returned through the DocObj parameter of the CreateToolWindow method. This portion of code shows how this is done:

object []propertiesWindowObjects = {mediaPlayer}; mediaPlayerWindow.SetSelectionContainer(ref propertiesWindowObjects);

You can call the SetSelectionContainer method only on tool windows that you create. If you call this method on a Window object for, say, the Solution Explorer tool window, an exception will be generated.

Related

Категории