The Toolbox Window

The Toolbox stores controls and code snippets that you can drag onto the Forms Designer window, text editor windows, and nearly anything else that can be a drag-and-drop target. The Toolbox is made up of a set of pages, or tabs, where items can be stored and grouped into related categories.

Tabs and Items

To find the Toolbox window, you can pass the constant vsWindowKindToolbox to the Windows.Item method, which returns a Window object. The ToolBox object is then found by calling the returned object's Window.Object property, as shown here:

 Sub FindTheToolBox()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object End Sub 

Because the Toolbox can contain more than one tab, a collection is available to enumerate all these tabs. You find this collection, the ToolBoxTabs object, by calling the ToolBox. ToolBoxTabs property. Using the ToolBoxTabs collection, you can enumerate each ToolBoxTab object in the Toolbox and even create new tabs to house components or text fragments of your choosing. To create a new tab, you use the ToolBoxTabs.Add method, which takes as an argument the name of the new tab to create and returns a ToolBoxTab object for the newly created tab. The following macro adds a new Toolbox tab:

 Sub AddNewToolBoxTab()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object     toolBox.ToolBoxTabs.Add("My commonly used items").Activate() End Sub 

This code creates a new tab called My Commonly Used Items, and the Activate method of the ToolBoxTab object makes sure it's the selected tab.

Not only is the Toolbox a collection of tabs, but each tab is also a collection of items. Each collection item is represented in the object model by a ToolBoxItem object and can be enumerated by using the ToolBoxItems object, which is found by calling the ToolBoxTab. ToolBoxItems property. You can walk the entire contents of the Toolbox by using the EnumerateToolBoxContents macro, shown here:

 Sub EnumerateToolBoxContents()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     Dim toolBoxTab As ToolBoxTab     Dim outputWindow As New _         InsideVSNET.Utilities.OutputWindowPaneEx(DTE, "Toolbox contents")     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object     For Each toolBoxTab In toolBox.ToolBoxTabs         Dim toolBoxItem As ToolBoxItem         outputWindow.WriteLine(toolBoxTab.Name)         For Each toolBoxItem In toolBoxTab.ToolBoxItems             outputWindow.WriteLine(vbTab + toolBoxItem.Name)         Next     Next End Sub 

Once you find a ToolBoxItem object, you'll see that you can't do much with it. You can call the Select method to make sure it's the active item in the Toolbox, you can remove the item by using the Delete method, and you can find the label that's displayed in the user interface by using the Name property. Although the object model of a ToolBoxItem is a functional dead end, the real power that the Toolbox object model offers you is the ability to create new items.

Adding Items to the Toolbox

The Toolbox can hold different types of objects, such as text, HTML, COM components, and .NET components. You can add your own items by using the ToolBoxTab.Add method, which takes three parameters. The first parameter, Name, is the display name of the item added; this string is the text that will be displayed within the Toolbox user interface. The second parameter, Data, defines the information stored in the Toolbox for the item. How this data is formatted depends on the third parameter, Format, which is of type vsToolBoxItemFormat.

The simplest data type that can be stored is raw text. The string passed to the Data parameter is copied verbatim into the Toolbox item, and when the text is dragged onto a window that supports drag-and-drop with a Clipboard format of type text (such as a text editor window), it is copied into that window. To add a text fragment, you can use code like this:

     Sub AddTextToTheToolBox()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     Dim toolBoxTab As EnvDTE.ToolBoxTab     Dim toolBoxItems As EnvDTE.ToolBoxItems     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object     toolBoxTab = toolBox.ToolBoxTabs.Item("General")     toolBoxItems = toolBoxTab.ToolBoxItems     toolBoxItems.Add("My Text", "This is some text", _         vsToolBoxItemFormat.vsToolBoxItemFormatText) End Sub 

This code starts by walking the object model and finding the General tab of the Toolbox. It ends by calling the ToolBoxItems.Add method and adding an item labeled My Text with the text This is some text that has the Clipboard format of type text.

Adding text in the HTML format is similar to adding plain text—the differences are that rather than passing raw text, you need to pass a fragment of HTML code, and the format of the data is marked as HTML by using vsToolBoxItemFormatHTML:

 Sub AddHTMLToTheToolBox()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     Dim toolBoxTab As EnvDTE.ToolBoxTab     Dim toolBoxItems As EnvDTE.ToolBoxItems     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object     toolBoxTab = toolBox.ToolBoxTabs.Item("General")     toolBoxItems = toolBoxTab.ToolBoxItems     toolBoxItems.Add("My HTML", "<b>This is bold HTML</b>", _         vsToolBoxItemFormat.vsToolBoxItemFormatHTML) End Sub 

After you run this code, a fragment of HTML is placed onto the Toolbox; if you drag that Toolbox item into the HTML designer, text will appear in bold style.

Note 

Remember that HTML is really just an application of XML that follows a particular schema. Because HTML is XML, you can also store XML fragments as HTML on the Toolbox. Visual Studio not only lets you drag-and-drop these HTML/XML fragments into an HTML document, but it also allows you to drag them into an XML document. In fact, a better name for the vsToolBoxItemFormatHTML value would have been vsToolBoxItemFormatXML.

Along with these two text formats, the Toolbox can also store ActiveX® controls, which can be dragged into HTML-designer or Win32® applications (such as a Microsoft Foundation Classes [MFC] dialog box) that support hosting ActiveX controls. To add an ActiveX control, supply the vsToolBoxItemFormatGUID data type. The format of the Data argument is the Class Identifier (CLSID) GUID of the ActiveX control or (despite the name of the format type) the ProgID of the control. The following macro adds two copies of the Windows Media® Player control to the Toolbox. The first one is added by using the CLSID of the control, and the second is added based on its ProgID:

 Sub AddCOMObjectToTheToolBox()     Dim toolBoxWindow As EnvDTE.Window     Dim toolBox As EnvDTE.ToolBox     Dim toolBoxTab As EnvDTE.ToolBoxTab     Dim toolBoxItems As EnvDTE.ToolBoxItems     toolBoxWindow = DTE.Windows.Item(Constants.vsWindowKindToolbox)     toolBox = toolBoxWindow.Object     toolBoxTab = toolBox.ToolBoxTabs.Item("General")     toolBoxItems = toolBoxTab.ToolBoxItems     toolBoxItems.Add("Name", "{22D6F312-B0F6-11D0-94AB- 0080C74C7E95}", _         vsToolBoxItemFormat.vsToolBoxItemFormatGUID)     toolBoxItems.Add("Name", "MediaPlayer.MediaPlayer.1", _         vsToolBoxItemFormat.vsToolBoxItemFormatGUID) End Sub 

When you run this code, you'll notice that the Name parameter is ignored. This is because the Toolbox extracts the name from the control.

Note 

.NET User Controls can be added to the toolbox by using the vsToolBoxItemFormat. vsToolBoxItemFormatDotNETComponent enumerated value. However, this method has been deprecated in favor of using the Content Installer to install controls, as we discussed in Chapter 4. The Content Installer gives you much better control over where items are installed into the toolbox and makes installing and uninstalling controls much easier.