Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Explorer Windows and the UIHierarchy Object

User interface hierarchy (or UI hierarchy) windows are tool windows that use a tree-like structure to display their data. Examples include the Solution Explorer, Server Explorer, and Macro Explorer windows. The UIHierarchy object and its associated objects UIHierarchyItems and UIHierarchyItem are so named because they represent a hierarchy of objects displayed in a tool window. The UIHierarchy object is used extensively by the macro recorder, allowing it to record the correct code to modify the selection within a UI hierarchy window; you can also use the UIHierarchy object as a valuable source of information about what is contained within these tool windows.

The UIHierarchy Object Tree

The UIHierarchy, UIHierarchyItems, and UIHierarchyItem objects work recursively. The UIHierarchy object is used to find the UIHierarchyItems collection, which contains all the root items of the tree within a UI hierarchy window. Each root tree item is represented by a UIHierarchyItem object within the UIHierarchyItems collection, and because all of these tree items can themselves contain subitems, the UIHierarchyItem.UIHierarchyItems property returns a UIHierarchyItems collection. This pattern of tree nodes returning a collection of other nodes continues until that branch of the tree ends. The following macro uses the UIHierarchy object to find and display the name of the top-level node of Macro Explorer:

Sub GetTopLevelUIHierItems()
Dim macroExplWin As Window
Dim uiHierarchy As EnvDTE.UIHierarchy
Dim uiHierarchyItems As EnvDTE.UIHierarchyItems
'Find the macro explorer window, and the UIHierarchy
' object for this window:
macroExplWin = DTE.Windows.Item(Constants.vsWindowKindMacroExplorer)
uiHierarchy = macroExplWin.Object
'Get the top level collection of items:
uiHierarchyItems = uiHierarchy.UIHierarchyItems
'Display the name of the first node in this collection:
MsgBox(uiHierarchyItems.Item(1).Name)
End Sub

Here, Macro Explorer's UIHierarchy object is found and the collection of UIHierarchyItems is retrieved. The name displayed is that of the first item in the collection, which in this case is Macros because the top-level node in Macro Explorer is always the Macros node.

Continuing with our example, the Macros node in the Macro Explorer window contains a number of macro projects. Because this node can have subitems, it is a container of UIHierarchyItem objects, so the UIHierarchyItem.UIHierarchyItems property returns a collection object. This UIHierarchyItems collection contains a list of all the macro projects, and if we modify the earlier macro, we can walk the list of the macro projects:

Sub WalkMacroProjects()
Dim macroExplWin As Window
Dim uiHierarchy As EnvDTE.UIHierarchy
Dim uiHierarchyItems As EnvDTE.UIHierarchyItems
Dim uiHierarchyItem As EnvDTE.UIHierarchyItem
Dim uiHierarchyItem2 As EnvDTE.UIHierarchyItem
'Find the Macro Explorer window, and the UIHierarchy
' object for this window:
macroExplWin = DTE.Windows.Item(Constants.vsWindowKindMacroExplorer)
uiHierarchy = macroExplWin.Object
'Get the first node in this collection, the Macros node:
uiHierarchyItem = uiHierarchy.UIHierarchyItems.Item(1)
'Walk all the items in this collection, which is
' the list of macro projects:
For Each uiHierarchyItem2 In uiHierarchyItem.UIHierarchyItems
MsgBox(uiHierarchyItem2.Name)
Next
End Sub

These sample macros show how to walk the hierarchy shown in the Macro Explorer window. To use this code to look at what is contained in the Solution Explorer and Server Explorer windows, you can simply change the value passed to the Windows.Item method to Constants.vsWindowKindSolutionExplorer or Constants.vsWindowKindServerExplorer.

Note

Do the UIHierarchy objects seem familiar? Walking the UIHierarchy, UIHierarchyItems, and UIHierarchyItem objects to find an item in a UI hierarchy window is similar to using ProjectItems and Project­Item to walk a project to find a project item. The reason for this similarity is that the UIHierarchy objects were designed to reflect how you would use the ProjectItem and ProjectItems objects.

The UIHierarchy Object

Finding a specific node within a UI hierarchy window can involve a great deal of code, especially if the node is nested more than a couple levels deep. Using the UIHierarchy.GetItem method, you can directly find a UIHierarchyItem object of a node rather than writing a lot of code to traverse the tree of nodes. For example, if you want to get to the UIHierarchyItem object of the InsertDate macro located in the VSEditor module of the Samples macro project, you can write code such as this:

Sub FindUIHierItemForInsertDateMacro()
Dim macroExplWin As Window
Dim uiHierarchy As EnvDTE.UIHierarchy
Dim uiHierarchyItem As EnvDTE.UIHierarchyItem
Dim uiHierarchyItems As EnvDTE.UIHierarchyItems
macroExplWin = DTE.Windows.Item(Constants.vsWindowKindMacroExplorer)
uiHierarchy = macroExplWin.Object
uiHierarchyItems = uiHierarchy.UIHierarchyItems
uiHierarchyItem = uiHierarchyItems.Item("Macros")
uiHierarchyItems = uiHierarchyItem.UIHierarchyItems
uiHierarchyItem = uiHierarchyItems.Item("Samples")
uiHierarchyItems = uiHierarchyItem.UIHierarchyItems
uiHierarchyItem = uiHierarchyItems.Item("VSEditor")
uiHierarchyItems = uiHierarchyItem.UIHierarchyItems
uiHierarchyItem = uiHierarchyItems.Item("InsertDate")
MsgBox(uiHierarchyItem.Name)
End Sub

This bit of code is quite verbose, however, and we can shorten it by using the UIHierarchy.GetItem method:

Sub FindUIHierItemForInsertDateMacro2()
Dim macroExplWin As Window
Dim uiHierarchy As EnvDTE.UIHierarchy
Dim uiHierarchyItem As EnvDTE.UIHierarchyItem
macroExplWin = DTE.Windows.Item(Constants.vsWindowKindMacroExplorer)
uiHierarchy = macroExplWin.Object
uiHierarchyItem = _ 
uiHierarchy.GetItem("Macros\Samples\VSEditor\InsertDate")
MsgBox(uiHierarchyItem.Name)
End Sub

UIHierarchy.GetItem accepts a string, which is the path to an item that pinpoints a node within the hierarchy. This path is calculated by taking the names of each node in the branch to the tree node that you want to find, separated by the forward slash character. Although the UIHierarchy.GetItem method finds nodes within the Macro Explorer and Solution Explorer windows, a bug in Visual Studio .NET doesn't allow you to find a UIHierarchyItem object in the Server Explorer window.

The UIHierarchy.SelectedItems property returns an array of UIHierarchyItem objects for items that are selected within the UI hierarchy tree. Like other arrays returned by the object model when you're using a language supported by .NET, this property returns an array of untyped objectsan array of System.Object.

Sub GetUIHierSelectedItems()
Dim macroExplWin As Window
Dim uiHierarchy As EnvDTE.UIHierarchy
Dim selectedItems As Object()
Dim uiHierarchyItem As EnvDTE.UIHierarchyItem
macroExplWin = DTE.Windows.Item(Constants.vsWindowKindMacroExplorer)
uiHierarchy = macroExplWin.Object
selectedItems = uiHierarchy.SelectedItems
For Each uiHierarchyItem In selectedItems
MsgBox(uiHierarchyItem.Name)
Next
End Sub

To help the macro recorder record the movement of selections in a UI hierarchy window, the UIHierarchy object has two methods, SelectUp and SelectDown, that simulate the user selecting nodes within the tree. Both methods take as arguments two parameters. The first parameter is of type EnvDTE.vsUISelectionType, which denotes how nodes should be selected and closely reflects how the keyboard and mouse can be used to select particular nodes. EnvDTE.vsUISelectionTypeSelect selects a single node within the tree, causing any other selected node or nodes to lose their selection state. EnvDTE.vsUISelectionTypeExtend selects from the last selected node to the chosen node, much as if the user had clicked on a node while holding down the Shift key. EnvDTE.vsUISelectionTypeSetCaret doesn't select a nodeit moves the caret within the tree to the specified node. Lastly, EnvDTE.vsUISelectionTypeToggle swaps the selection state of a node, setting the selection if the node isn't selected or clearing the selection if it is selected. The second parameter of the SelectUp and SelectDown methods is a count parameter. By default, only one item is selected in either the up or down direction, but you can supply a different value so more than one node can be selected at one time.

The UIHierarchy object also has a method named DoDefaultAction. This method simulates the user pressing the Enter key with one or more nodes selected in the tree. For example, if a macro node is selected in Macro Explorer and the UIHierarchy.DoDefaultAction method is called, that macro runs.

The UIHierarchyItems Object

The EnvDTE.UIHierarchyItems object is a collection of EnvDTE.UIHierarchyItem objects and works like any other collection object in the Visual Studio object model. This object supports one property that is not part of the standard set of methods and properties of other collection objects: the Expanded property. This property is of type Boolean and returns whether the nodes underneath the UIHierarchyItem collection are shown in the user interface. Setting this property to True has the same effect as the user clicking the plus symbol next to a tree view item; setting it to False is the same as the user clicking the minus symbol.

The UIHierarchyItem Object

The EnvDTE.UIHierarchyItem, being a collection item, supports the standard collection item methods and properties, such as Collection and Name. It also supports a method named Select. This method is similar to the UIHierarchy.SelectUp and UIHierarchy.SelectDown methods, except that it works on only one node at a timethe UIHierarchyItem that the Select method was called on. Because the Select method modifies only the current UIHierarchyItem, it doesn't accept a number of items to select.

Calling the UIHierarchyItem.Object property returns the extensibility object, if one is available, for that node. For example, when you're using Solution Explorer, you can retrieve a EnvDTE.Project or EnvDTE.ProjectItem object behind that node by using the Object property. The following code finds the UIHierarchyItem for the first project and second item within that project (the second item is searched for because the first item, when a .NET project is loaded, is the References node) and gets the EnvDTE.Project and EnvDTE.ProjectItem objects for those nodes:

Sub GetUIHierItemObject()
Dim uihier As EnvDTE.UIHierarchy
Dim uihierProj As EnvDTE.UIHierarchyItem
Dim uihierProjItem As EnvDTE.UIHierarchyItem
Dim project As EnvDTE.Project
Dim projItem As EnvDTE.ProjectItem
uihier = DTE.Windows.Item( _ 
Constants.vsWindowKindSolutionExplorer).Object
uihierProj = uihier.UIHierarchyItems.Item(1).UIHierarchyItems.Item(1)
project = uihierProj.Object
uihierProjItem = uihierProj.UIHierarchyItems.Item(2)
projItem = uihierProjItem.Object
End Sub