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 XtraGrids internal methods.
- By using the XtraGrids 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 XtraGrids 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 grids
Views collection by zero-based indexes, at that, the 1st element in this collection (with index 0) is always the grids main (top-level) view. The main view is also returned by the grids
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 cells 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
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
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 views
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 viewss
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 grids 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 cells 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: