Manipulating Tree Views Using UIHierarchy

Some tool windows in Visual Studio .NET, such as Macro Explorer and Solution Explorer, have a tree view; that is, a hierarchical outline-style view. The UIHierarchy object represents these windows and allows you to view and manipulate their tree views.

Object Name	Description
UIHierarchy Object	Represents the tree view in the tool window.
UIHierarchyItems Collection	Represents all of the nodes in the tree view.
UIHierarchyItem Object	Represents a single node in the tree view.

Using these objects and collections, you can:

• Select, view, multiply select, expand, and collapse nodes in the tree view.
• Move the node up or down in the tree view.
• Return the selected item or have it perform its default action.

UIHierarchy Example

Since the UIHierarchy object represents any tree view-type window, such as Solution Explorer or Macro Explorer, it is a Window object. Its UIHierarchyItems property returns the collection of top-level nodes in the specified window. In Solution Explorer, there is only a single top-level node (the solution), and in Macro Explorer, there is also only one top-level node (the Macros node). This means that the project nodes are not in the window's UIHierarchyItems collection, but rather in the top-level node's collection.

Bearing this in mind, there are two ways to access a particular node (UIHierarchyItem):

• Using the GetItem method to directly reference the desired node.
• Using UIHierarchyItems.Item.UIHierarchyItems... (a collection/item/collection... pattern). To navigate deeper into a node nesting, just keep using this pattern. For example, to navigate to the second node under the top-level node, you would use UIHierarchy.UIHierarchyItems.Item(1).UIHierarchyItems.Item(2).

Examples of how to use both techniques to access a lower-level node are demonstrated below.

The VSMacro examples below demonstrates how to reference and use the various members of the UIHierarchy automation model to list all of the macros under the Samples node of Macro Explorer.

The first example uses the GetItem method strategy of accessing a node in an UIHierarchy.

Sub ListMacroSamples1()
   ' Reference the UIHierarchy, UIHierarchyItem, and OutputWindow objects.
   Dim UIH As UIHierarchy = _
     DTE.Windows.Item(Constants.vsWindowKindMacroExplorer).Object
   Dim samples As UIHierarchyItem = UIH.GetItem("Macros\Samples")
   Dim OWPane As OutputWindowPane = GetOutputWindowPane("List Macros")
   Dim file As UIHierarchyItem

   OWPane.Clear()
   For Each file In samples.UIHierarchyItems
      OWPane.OutputString(file.Name & _
        Microsoft.VisualBasic.Constants.vbCrLf)
      Dim macro As UIHierarchyItem
      For Each macro In file.UIHierarchyItems
         OWPane.OutputString("   " & macro.Name & _
           Microsoft.VisualBasic.Constants.vbCrLf)
      Next
   Next
End Sub

Function GetOutputWindowPane(ByVal Name As String, Optional ByVal show As Boolean = True) As OutputWindowPane
   ' This is a support function for ListMacroSamples(). It provides the 
   ' Output window to list the contents of the Sample node.
   Dim win As Window = _
     DTE.Windows.Item(EnvDTE.Constants.vsWindowKindOutput)
   If show Then win.Visible = True
   Dim OW As OutputWindow = win.Object
   Dim OWPane As OutputWindowPane
   Try
      OWPane = OW.OutputWindowPanes.Item(Name)
   Catch e As System.Exception
      OWPane = OW.OutputWindowPanes.Add(Name)
   End Try
   OWPane.Activate()
   Return OWPane
End Function

This example uses the UIHierarchyItems.Item.UIHierarchyItems strategy for accessing a node in a UIHierarchy.

Sub ListMacroSamples2()
   Dim UIH As UIHierarchy = _
     DTE.Windows.Item(Constants.vsWindowKindMacroExplorer).Object
     ' Set a reference to the "Samples" node in Macro Explorer. The 
     ' collections are one-based.
     Dim UIHItem As UIHierarchyItem = _
     UIH.UIHierarchyItems.Item(1).UIHierarchyItems.Item(2)
   Dim file As UIHierarchyItem
   Dim OWPane As OutputWindowPane = GetOutputWindowPane("List Macros")
   For Each file In UIHItem.UIHierarchyItems
      OWPane.OutputString(file.Name & _
        Microsoft.VisualBasic.Constants.vbCrLf)
      Dim macro As UIHierarchyItem
      For Each macro In file.UIHierarchyItems
         OWPane.OutputString("   " & macro.Name & _
           Microsoft.VisualBasic.Constants.vbCrLf)
      Next
   Next
End Sub

See Also

Changing Window Characteristics | Creating and Controlling Environment Windows | Creating Add-Ins and Wizards | Creating an Add-In | Creating a Wizard | Automation and Extensibility Reference | Automation Object Model Chart