Starting with this article, I am going to devote a series of articles to working with the Microsoft PropertyGrid control from TestComplete scripts.
As you can see from the PropertyGrid reference in the MSDN library, this control does not contain any public members that let you obtain information the grid structure. However, since TestComplete provides access to the objects’ protected, private and internal members as well, it is possible to dig out the PropertyGrid members that can be used to perform desired operations.
In this article, I will explain how to access PropertyGrid rows. This is essential, because in order to perform various operations over the PropertyGrid control you need to obtain the objects corresponding to individual grid rows. I will describe the approaches that can be used to access top-level grid rows, walk down the rows hierarchy and get a grid row by its full label as well as by its visible index within the grid.
See the following sections for details:
Accessing Top-Level Rows
To obtain a collection of PropertyGrid top-level rows, use the grid’s GetPropEntries() method. Which items the returned collection contains depends on the view currently used by the grid. If the grid displays object properties using the categorized view, the GetPropEntries method returns the collection of category rows. Otherwise, if the grid uses the alphabetical view, the GetPropEntries method returns the collection of all top-level properties displayed in the grid.
To get a GridEntry object corresponding to an individual grid row, you can use the following properties and methods of the obtained object:
- The
Item (Index) property and get_Item (Index) method return a grid row by its zero-based index within the collection. The total number of items in the collection is specified by the Count property.
- The
Item_2 (Name) property and get_Item_2 (Name) method return a grid row by its label (for example, “Font” or “Text”).
The following code snippet toggles the expanded state of the grid’s “Appearance” category row. The example requires that the grid displays properties using the categorized view:
Accessing Child Rows
In order to walk down the grid rows hierarchy, you need to get child rows of a particular grid row. To access child rows of a particular category row or a compound property row, use its GridItems property. You can iterate through the returned collection using properties and methods described in the previous section.
The following example illustrates how you can search for a row in the rows hierarchy. It requires that the grid displays properties using the categorized view. The example contains the following routines:
Main is the main routine. It obtains the scripting object corresponding to the PropertyGrid control and calls the GetItem function to get the “Appearance.Font.Name” item. If such an item is not found, it posts the error message to the log; otherwise it posts the property value.
GetItem returns the PropertyGrid row specified by its full label (for example, “Appearance.Font.Name”). This function works as follows: first it splits the full label into labels of individual rows (so we get the “path” to the desired row). Then it walks down the rows hierarchy, at each step obtaining the row with the corresponding label. If at any step the row with the specified label is not found, the function immediately returns with the null result.
IsNullValue is a helper routine that checks if the specified value is the null value (Null, Empty or Nothing). It is used by the GetItem function to determine if the collection item specified by its label exists or not.
Accessing Rows by Visible Indexes
You may need to obtain the PropertyGrid rows not only by their position within the rows hierarchy or their label, by also by their visible position within the grid. You can do this via the grid view.
In the application’s object tree the grid view object appears as the child object of the PropertyGrid control, so you can obtain it using the WinFormsObject method, as follows:
grid.WinFormsObject("PropertyGridView", "PropertyGridView")
The grid view has the GetAllGridEntries() method which is similar to the grid’s GetPropEntries method. However, the GetAllGridEntries method returns the collection of all displayed rows of any level of hierarchy, and does not include the hidden rows, whose parent rows are collapsed. After you have obtained the rows collection, you can use its Item (Index) and Item_2 (Label) properties to access a particular row by its zero-based index or label, respectively.
The following example demonstrates how you can obtain a PropertyGrid row by its visible index within the grid:
Accessing Currently Selected Row
Finally, you can easily access the currently selected row in the PropertyGrid using its SelectedGridItem property. This property lets you obtain as well as set the selected row. For example, the following code snippet selects the first grid row: