In order to simulate various user actions over the Developer Express XtraGrid control, you first need to locate the grid row (card) that contains the data that you are going to work with. This article describes several approaches that you can use to search for records in the XtraGrid control.
There are several ways to locate the desired record:
- By using the XtraGrid’s internal methods.
- By using the XtraGrid’s incremental search feature.
- By iterating through the grid rows and comparing cell values.
In your test scripts, you can use the approach that suits your needs better. All these approaches use internal methods and properties of the XtraGrid control. In order for TestComplete to access them, the .NET Open Applications plug-in must be installed and enabled.
Searching By Using XtraGrid’s Internal Methods
The XtraGrid control has built-in methods that you can use to search for a desired grid record. To use these methods, first, you need to obtain the grid view in which the record resides. The XtraGrid control can display data of multiple nested tables; data of each table is displayed in a separate view. A view is an object that holds information about the data displayed in it, the number of rows and columns, appearance and behavior settings. The currently visible views can be accessed via the grid’s Views collection by zero-based indexes, at that, the 1st element in this collection (with index 0) is always the grid’s main (top-level) view. The main view is also returned by the grid’s MainView property.
After you have obtained the view object, you can locate the desired record using one of the following methods:
view.LocateByValue (StartRowHandle, ColumnObj, Value) - Locates the row (card) containing the specified value in the specified column.view.LocateByDisplayText (StartRowHandle, ColumnObj, Text) - Locates the row (card) containing the specified text in the specified column. You can use this method, for example, if cell values are displayed with a specific formatting applied.
The StartRowHandle parameter of these methods is the zero-based index of the row (card) from which the search starts. ColumnObj is the object corresponding to the grid column (card field) in which the sought-for value or text is contained. The last parameter is the value or text that is sought-for. Note that the XtraGrid control can display the data with special formatting, so the actual value of a particular cell can be significantly different from the cell’s display text. The grid can also contain columns that use lookup combo boxes to display values different from the ones that are actually stored in the column cells. You should keep this in mind when specifying the sought-for value in the LocateByValue method.
Both methods return the index (zero-based) of the found row (card). If the row is not found, they return the special InvalidRowHandle value that does not correspond to no row (card).
The following example demonstrates how you can use the LocateByValue and LocateByDisplayText methods to search for the desired record in the grid. This example works with the GridTutorials sample application that is shipped with Developer Express XtraGrid Suite. The script contains the following routines:
Searching By Using Incremental Search
The XtraGrid control supports the incremental search feature. When the user starts typing into the grid, the first cell matching the inputted text becomes selected in the grid. You can use the incremental search to quickly locate and select a record with the desired cell text in the grid. Note that this feature is enabled in a particular grid view only if the view’s OptionsBehavior.AllowIncrementalSearch property is True.
To perform an incremental search, you can simulate inputting the sought-for string into the grid using the Keys action, or use the grid views’s StartIncrementalSearch method with the sought-for string as a parameter (in this case, the search will be performed internally, that is, no input will be passed to the grid control). In the example below, we use the StartIncrementalSearch method to avoid inputting data into the grid.
This example works with the same GridTutorials application. It contains the following routines:
Main is the main routine. It obtains the scripting object corresponding to the grid control, calls SelectCellByIncremental to select a grid cell with the text and then modifies the cell data.
SelectCellByIncSearch uses the incremental search feature to locate and select a grid cell with the specified display text. The function has the following parameters:
- Grid - The tested XtraGrid control.
- View - The grid view in which the search is performed. If this parameter has the null value (
Nothing in VBScript, nil in DelphiScript, null in JScript, C++Script and C#Script), the search will be performed in the grid’s main view.
- ColumnId - The caption of the zero-based visible index of the column that contains the cell with the sought-for text.
- Text - The search string.
If the sought-for text is found, the function selects this cell that contains this text and returns the zero-based index of the cell’s row (card). If the text is not found, the function selects the topmost cell in the specified column and returns the InvalidRowHandle value that does not correspond to any row (card).
GetColumn - A helper function that returns the column object specified by its caption or position in the grid.
Implementing Custom Search
Sometimes the approaches described in the previous sections may not suit your needs. For example, you may want to search for a record by values or text in multiple columns, search for a particular group row, and so on. In this case, you will need to implement the search procedure yourself. The general approach implies that you iterate through grid rows (cards) and on each iteration check whether the current row matches the search condition.
Below is an example that demonstrates how you can locate a particular row by iterating through the grid rows. It searches for a grid ow (card) by text displayed in multiple cells. The example contains the following routines: