How to: Manipulate Tree Views by Using UIHierarchy

Some tool windows in Visual Studio, such as the Solution Explorer, do not have explicit automation objects that you can use to manipulate their contents. These tool windows do, however, have a tree view — that is, a hierarchical, outline-style, node view — that you can programmatically access. The UIHierarchy object represents the tree views in these tool windows and enables you to iterate through them and view the contents of their nodes.

By using these objects and collections, you can:

• Select (singly or multiply) and view nodes in the tree view.

• Move the insertion point up or down in the tree view.

• Return the value of the selected item or have it perform its default action.

The ToolWindows object (which is also returned from ToolWindows) allows easier referencing of the various tool windows in Visual Studio. For example, rather than using _applicationObject.Windows.Item(EnvDTE.Constants.vsWindowKindOutput), you can now use _applicationObject.ToolWindows.OutputWindow.

Example

Although the UIHierarchy object represents the contents of nearly any tool window that has a tree view, such as Solution Explorer, the tool window itself is still a Window object. The UIHierarchyItems property returns the collection of top-level nodes in the specified tool window. In Solution Explorer, there is only a single top-level node (the solution). Consequently, the project node for this particular window is in the top-level node's collection rather than in the window's UIHierarchyItems collection.

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

• By using the GetItem method to directly reference the desired node using a solution/project/item pattern.

• By using UIHierarchyItems.Item.UIHierarchyItems... (a collection/item/collection pattern).

  To navigate deeper into a node nesting, just keep using this pattern. For example, to go to a node subordinate to 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 in the examples below.

These add-in examples demonstrate how to reference and use the various members of the UIHierarchy automation model to list all of the items in Solution Explorer.

The first example uses the GetItem method strategy of accessing the contents of the References node in Solution Explorer. For more information about how to run the add-in code, see How to: Compile and Run the Automation Object Model Code Examples.

Imports System.Text

Public Sub OnConnection(ByVal application As Object, ByVal  _
connectMode As ext_ConnectMode, ByVal addInInst As Object,  _
ByRef custom As Array) Implements IDTExtensibility2.OnConnection
    _applicationObject = CType(application, DTE2)
    _addInInstance = CType(addInInst, AddIn)
    listSlnExpNodes(_applicationObject)
End Sub

Sub listSlnExpNodes(dte as DTE2)
    ' Requires reference to System.Text for StringBuilder.
    Dim UIH As UIHierarchy = dte.ToolWindows.SolutionExplorer
    ' Set a reference to the first level nodes in Solution Explorer. 
    ' Automation collections are one-based.
    Dim UIHItem As UIHierarchyItem = _
      UIH.GetItem("MyAddin1\MyAddin1\References")
    Dim file As UIHierarchyItem
    Dim sb As New StringBuilder

    ' Iterate through first level nodes.
    For Each file In UIHItem.UIHierarchyItems
        sb.AppendLine(file.Name)
        ' Iterate through second level nodes (if they exist).
        Dim subitem As UIHierarchyItem
        For Each subitem In file.UIHierarchyItems
            sb.AppendLine("   " & subitem.Name)
        Next
    Next
    MsgBox(sb.ToString)
End Sub

using System.Text;

public void OnConnection(object application, ext_ConnectMode _
  connectMode, object addInInst, ref Array custom)
{
    _applicationObject = (DTE2)application;
    _addInInstance = (AddIn)addInInst;
    listSlnExpNodes(_applicationObject);
}

public void listSlnExpNodes(DTE2 dte)
{
    // Requires reference to System.Text for StringBuilder.
    UIHierarchy UIH = dte.ToolWindows.SolutionExplorer;
    // Set a reference to the first level nodes in Solution Explorer. 
    // Automation collections are one-based.
    UIHierarchyItem UIHItem = 
      UIH.GetItem("MyAddin1\\MyAddin1\\References");
    StringBuilder sb = new StringBuilder();

   // Iterate through first level nodes.
   foreach ( UIHierarchyItem file in UIHItem.UIHierarchyItems )
   {
       sb.AppendLine(file.Name);
       // Iterate through second level nodes (if they exist).
       foreach ( UIHierarchyItem subitem in file.UIHierarchyItems )
       {
           sb.AppendLine("   "+subitem.Name);
       }
   }
   MessageBox.Show(sb.ToString());
}

The following example illustrates how to use UIHierarchy to list the contents of the tree view of the Solution Explorer window.

Sub cvTreeView()
    Dim uih As UIHierarchy = DTE.ToolWindows.SolutionExplorer
    Dim uihItem As UIHierarchyItem
    Dim uihItems As UIHierarchyItems = uih.UIHierarchyItems
    Dim msg As String
    For Each uihItem In uihItems
        msg += uihItem.Name & vbCr
    Next
    MsgBox(msg)
End Sub

See Also

Tasks

How to: Control Solution Explorer

How to: Change Window Characteristics

Concepts

Automation Object Model Chart

Other Resources

Creating and Controlling Environment Windows

Creating Add-ins and Wizards

Automation and Extensibility Reference