Summary

---

Manipulating IDE Tool Windows

The Visual Studio .NET environment has a number of tool windows, such as the Task List, Toolbox, Clipboard Ring, Output window, and so forth. Most of these windows can be programmatically manipulated by macro commands and addins. In this section I discuss some of the objects that allow you to control the operation of these windows. I also demonstrate the use of the objects by macro commands. Remember that any code demonstrated here in macros can be converted to run in an add-in by simply changing the keyword DTE to the name of the application object in the add-in.

The TaskList Object

The Task List in Visual Studio .NET is an automated to-do list. Among other things, Visual Studio automatically places an item in the Task List for every line of code that will not compile. The user can add, delete, and check off the Task List items manually. Additionally, add-ins and macros can also manipulate the Task List programmatically using the TaskList object. The TaskList object represents the items in the Task List window in the IDE.

The code in Listing 9-11 adds two items to the Task List and then deletes one of them.

Listing 9-11: TaskListManipulation

 01 Sub TaskListManipulation() 02     Dim win As Window = DTE.Windows.Item(Constants.vsWindowKindTaskList) 03     Dim tskList As TaskList = win.Object 04     Dim tlItem As TaskItem 05 06     ' Add a couple of tasks to the Task List. 07     tlItem = tskList.TaskItems.Add(" ", " ", _ 08        "Test task 1. Delete this by right-  09        clicking and select Delete.",  10        vsTaskPriority.vsTaskPriorityHigh,  11        vsTaskIcon.vsTaskIconUser, True, , 10, , ) 12     tlItem = tskList.TaskItems.Add(" ", " ",  13        "Test task 2. Delete this by right  14        clicking and select Delete.", _ 15        vsTaskPriority.vsTaskPriorityLow, _ 16        vsTaskIcon.vsTaskIconComment, , 20, , ) 17 18     ' List the total number of task list items after adding 19     ' the new task items. 20     MsgBox("Task Item 1 description: " & _ 21        tskList.TaskItems.Item(2).Description) 22     MsgBox("Total number of task items: " &  23          tskList.TaskItems.Count) 24 25          ' Remove the second task item. The items list 26          'in reverse numeric order. 27     MsgBox("Deleting the second task item") 28     tskList.TaskItems.Item(1).Delete() 29     MsgBox("Total number of task items: " &  30              tskList.TaskItems.Count) 31 End Sub 

In lines 02 and 03, the macro command gets an object representing the Task List window. In lines 07 and 12, it uses the TaskItems.Add method to add the two text items to the Task List. Line 20 displays the description of the specified TaskList item. Line 22 simply enumerates the number of TaskItems in the TaskList object. Line 28 deletes the first TaskList item, and line 29 displays the count after the item is deleted.

In order to see items added programmatically, you must set the Task List Show Task options to Show All. You can do this by right-clicking the caption bar of the Task List and selecting Show Tasks → All.

Figure 9-10 shows the Task List after the macro command has been run.

Figure 9-10: Adding items to the Task List programatically

The ToolBox Object

The ToolBox object represents the Toolbox in the Visual Studio .NET environment. The Toolbox is a container for WinForms components when a Forms Designer is the active window. It is also the container for the Clipboard Ring when a code editor is the active window.

A Window object represents the Toolbox's window. The ToolBox contains a collection of ToolBoxTab objects. The tab object is list of Components when the Forms Designer is the active window. The tab object may be the Clipboard Ring when a code editor is the active window. ToolBoxItem objects represent individual items in the ToolBoxTabs collection.

You can programmatically add your own tabs to the Toolbox. For an example of this, you'll create a new tab named "My Code Snippets". You probably have a few sets of code, each of which consists of one to five lines that you use over and over. A simple example of this is code to fill a DataTable from a database. Obviously, you could use the Clipboard Ring for storing these snippets, but because the Clipboard Ring always maintains the last 15 text items cut or copied, your code snippets would soon be pushed off the Ring. Creating your own ToolBox tab for storing your code snippets alleviates the problem of losing them during the session of the IDE.

If you run the code shown in Listing 9-12 in an add-in rather than in a macro command, you could automatically load your snippets each time a new session of the IDE is started. Obviously, if you had a number of code snippets, you would probably read them from a text file and load them into the newly created ToolBox tab.

Listing 9-12: CreateMyCodeSnippets Macro

 Sub CreateMyCodeSnippets()     Dim objToolbox As ToolBox     Dim colTbxTabs As ToolBoxTabs     Dim objTab As ToolBoxTab     Dim colTbxItems As ToolBoxItems     Dim objTbxItem As ToolBoxItem     Const CS1 = "Dim dbCMD as New OledbCommand" & vbCrLf & _             "Dim dt As New DataTable" & vbCrLf & _             "Dim da as New OleDBDataAdapter" & vbCrLf & _             "dbCmd.CommandText = Sql" & vbCrLf & _             "dbCmd.Connection = CurrentConnection" & vbCrLf & _             "da = New OleDBDataAdapter(dbCMD)" & vbCrLf & _             "da.Fill(dt)" & vbCrLf     Const CS2 = "' This code does nothing but demo " &           vbCrLf & _                 "Dim s As String = " & Chr(34) & "ABC" &           Chr(34) & vbCrLf & _                 "Dim i As Integer = 1" & vbCrLf & _                 "s = s & i.ToString()" & vbCrLf    ' Create an object reference to the IDE's ToolBox object.    objToolbox =        DTE.Windows.Item(Constants.        vsWindowKindToolbox).Object    colTbxTabs = objToolbox.ToolBoxTabs    ' Add a new tab to the ToolBox.    objTab = colTbxTabs.Add("My Code Snippets")    colTbxTabs = objToolbox.ToolBoxTabs    ' Use the ToolBoxItems collection to access    ' all the items under a    ' ToolBoxTab.    colTbxItems = objTab.ToolBoxItems    ' Add a couple new ToolboxItem objects to the    ' new tab we added above.    objTbxItem = objTab.ToolBoxItems.Add("Fill Datatable", CS1)    objTbxItem = objTab.ToolBoxItems.Add("Code Item2 ", CS2)    objTbxItem = objTab.ToolBoxItems.Add("Code Item3", _       "Hello world Line2" & vbCrLf & "Hello world Line3" & _       vbCrLf)    objTbxItem = objTab.ToolBoxItems.Add("Code Item4", _       "Hello world Line4" & vbCrLf & "Hello world Line3" & _       vbCrLf)    ' List number of ToolBoxItems in a ToolBoxTab.    MsgBox("Number of items in ToolBox tab: " & _       colTbxItems.Count)    ' Select the fourth item in the ToolBoxItems    ' collection and delete it.    ' the tab is the first item in the collection    colTbxItems.Item(4).Select()    If (MsgBox("Delete second ToolBox item?", vbYesNo) =         vbYes) Then        colTbxItems.SelectedItem.Delete()    End If End Sub 

The code for manipulating the ToolBox is much like the code for manipulating the TaskList object. There is one exception. The new tab itself, "My Code Snippets", is the first item in the collection. Therefore, the first code item (CS1) is actually item 2 in the ToolBox tab. Figure 9-11 shows the Toolbox after the macro has run and created the new code snippets tab. In the picture, I have just rightclicked the first code snippet and I will select the Copy menu option.

Figure 9-11: Copying a code snippet

In Figure 9-12, you will see that I have pasted the code from the My Code Snippets tab of the ToolBox to the code editor window. The code that you see in the window was copied from the code item labeled "Fill DataTable".

Figure 9-12: Pasting the code snippet

The Output Window

Status messages for various features of the IDE are displayed in the Output window. The most prominent of these would be build progress and build errors if aproject has errors when it is compiled. Outputs from the Debug.WriteLine() method are displayed in the Output window. These are just two examples of the many types of output that can be displayed in the Output window.

The Visual Studio .NET automation model offers the following objects for controlling the Output window:

• OutputWindow object: Represents the Output window

• OutputWindowPanes collection: A collection containing all of the Output window panes

• OutputWindowPane object: Represents one pane in the Output window

The Output window displays text output from various IDE processes. It is possible that each process might use a different Output window pane. Panes are selected with a drop-down box at the top of the window. For example, build errors go to the Build Errors pane, and each external command tool potentially goes to its own distinct Output window pane.

The code in Listing 9-13 adds a new pane to the Output Window collection and then adds some text to the new pane.

Listing 9-13: Adding a Pane to the Output Window

 Sub OutputWindowPaneDemo()     ' Create a tool window handle for the Output window.     Dim win As Window = _        DTE.Windows.Item(EnvDTE.Constants.vsWindowKindOutput)     ' Create handles to the Output window and its panes.     Dim ow As OutputWindow = win.Object     Dim owPane As OutputWindowPane     ' Add a new pane to the Output window     Try         owPane = ow.OutputWindowPanes.Add("My New Pane")     Finally     End Try     ' Add a line of text to the new pane.     ow.OutputWindowPanes.Item("My New Pane").Activate()     owPane.OutputString("Some Text")     If MsgBox("Clear the Output Window current pane?", _        MsgBoxStyle.YesNo) = _        MsgBoxResult.Yes Then         owPane.Clear()     End If End Sub 

Note 

Once you add a pane to the OutputWindowPanes collection, it will remain in the collection until the IDE session is terminated. Also, if you add a pane with the same name, it will be duplicated. In other words, the Output window can have multiple panes with the same name.

After you run the macro in Listing 9-13, the Output window will appear as shown in Figure 9-13. If you answer Yes to the message box that prompts you as to whether the Output window is to be cleared, the currently active pane will be cleared.

Figure 9-13: New pane in the Output window

It is possible to place text into a pane of the Output window and into the Task List at the same time using the OutputTaskItemString method. This method adds a corresponding item to the Task List. The code in Listing 9-14 demonstrates this functionality.

Listing 9-14: OutputTaskItemString Example

 Sub OutputTaskItemStringDemo()     ' Create a tool window handle for the Output window.     Dim win As Window = _        DTE.Windows.Item(EnvDTE.Constants.vsWindowKindOutput)     ' Create handles to the Output window and its panes.     Dim ow As OutputWindow = win.Object     Dim owPane As OutputWindowPane     ' Activate previously created pane     Try         owPane = ow.OutputWindowPanes.Item("My New Pane")         owPane.Activate()     Catch e As System.Exception         MsgBox("You must run OutputWindowPaneDemo " & _            "before running this command.")         Exit Sub     End Try     ' Add a line of text to the new pane and to the Task List.     owPane.OutputTaskItemString("Some task", _        vsTaskPriority.vsTaskPriorityHigh, _        vsTaskCategories.vsTaskCategoryMisc, _        vsTaskIcon.vsTaskIconComment, _        "C:\temp", 100, "Some description")     ' You can also use the 'True' flag on the     ' end of OutputTaskItemString     ' rather than using the next line (ForceItemsToTaskList).     owPane.ForceItemsToTaskList() End Sub 

You can also use the "True" flag on the end of the OutputTaskItemString method instead of using the ForceItemsToTaskList method. Figure 9-14 shows the item that was added to the Task List, in addition to placing it in the Output window. Notice the Priority and Icon options that were added to the Task List item by specifying these options on the OutputTaskItemString method.

Figure 9-14: ForceItemsToTaskList example

---