Explorer Windows and the UIHierarchy Object


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 ProjectItem 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 desired node is nested more than two 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.

The UIHierarchy.SelectedItems property returns an array of UIHierarchyItem objects for items that are selected within the UI hierarchy tree. As do other arrays returned by the object model when you're using a language supported by .NET, this property returns an array of untyped objects—an 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 two parameters as arguments. 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 a node while holding down the Shift key. EnvDTE.vsUISelectionTypeSetCaret doesn't select a node—it 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 as 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 true if the nodes underneath the UIHierarchyItem collection are shown in the user interface, and false otherwise. 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 time—the 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 an 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 




Working with Microsoft Visual Studio 2005
Working with Microsoft Visual Studio 2005
ISBN: 0735623155
EAN: 2147483647
Year: 2006
Pages: 100

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net