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 grids
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:
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
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 grids 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 (
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 applications 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:
The grid view has the
GetAllGridEntries() method which is similar to the grids
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: