Working With Developer Express QuantumGrid - Searching for Records
To simulate user actions over the QuantumGrid control, you may need to locate the row that contains the data that you are going to work with. This article describes several approaches that can be used to locate records in the TcxGrid control (TcxGrid is the class name of Developer Express QuantumGrid).
You can locate the desired record by iterating through grid rows and comparing cell values, or by using the incremental search feature. Both approaches use internal methods and properties of the QuantumGrid object. In order for TestComplete to be able to access these methods and properties, the tested application must be compiled as an Open Application with debug information.
Searching by Iterating Through Grid Rows
Quite often, users search for records by iterating through grid records and examining cell values. You can create a script that will emulate these user actions. Below is the sample script that demonstrates how you can do this. The sample contains the following routines:
Main - The “main” routine of the sample. It obtains the scripting object that corresponds to the tested grid, passes this object to the
SearchCellByValue routine that performs the search and, finally, checks the results.
SearchCellByValue - This routine searches for a value that is displayed in cells of the specified grid column. The routine uses the following parameters:
- grid - The scripting object that corresponds to the tested grid.
- view - The view in which the search is performed (the QuantumGrid control can contain several levels of rows. Each level has a view that defines how the data is displayed). If this parameter is Nothing (VBScript), null (JScript, C++Script, C#Script) or nil (DelphiScript), the routine assumes that you are working with the view associated with the root level.
- columnId - Either caption of the desired column, or column index (zero-based) among other visible columns.
- searchString - The value, for which the routine will search in grid cells. Since the routine compares searchString with the cell text, the searchString parameter must contain a value of the string type, not integer, date, boolean or some other.
The routine performs the following actions:
- If the view parameter is
null (JScript, C++Script, C#Script),
Nothing (VBScript) or
nil (DelphiScript), the routine uses the internal
ActiveView property of the grid control to obtain the view that corresponds to the grid’s root level.
- Then, the routine iterates through grid rows. It obtains the value of a cell and then compares this value with the searchString parameter. If the comparison is successful, the routine exits the loop and returns the row index.
To obtain the number of grid rows in a view, we use the
GetRowCount function (see below).
To obtain the cell value, we use the
GetCellValue function (see below).
GetRowCount - Returns the number of grid rows. The function uses two parameters that specify the desired grid control and the desired view. If view is not specified, the function assumes you are working with the root level’s view.
To obtain the number of rows, the function uses the
ViewData.RowCount property of the specified view object.
GetCellValue - Returns the text displayed in a cell. The function uses four parameters that specify the grid control, view, row index and the desired column. The column can be specified by the caption or by the index (zero-based) among other visible columns.
GetColumn - Helper routine that returns the TcxGridColumn object that represents a grid column.
Note that the
SearchCellByValue function searches for a row by checking the text of cells. So, the value specified by the searchString must have the string type, not integer, date, or any other type. If a column, displays check boxes, the cell text can be True or False. If a column displays radio buttons, the cell text coincides with the caption of the selected button.
Searching by Using the Incremental Search Feature
QuantumGrid controls include the incremental search functionality. When it is active, you can search for a row by focusing the desired column and typing the desired text. The grid will automatically locate the row containing the text you entered.
If the tested grid supports incremental search, then to search for a record, you can simulate user actions that will focus the desired column and then simulate keystrokes over the grid. The sample below demonstrates this approach.
Note: The incremental search feature is activated by the
OptionsBehavior.IncSearch property of a grid view. To enable the incremental search for a view, set the
ViewObj.OptionsBehavior.IncSearch to True. If the tested grid only contains one level, you can use the
The sample contains the following routines:
Which Approach to Choose
We described two variants of the searching procedure. One of these variants iterates through the rows of the grid and the other uses the incremental search functionality.
In general, the incremental-search approach provides a faster search. However, it cannot determine if the search fails. If the grid does not contain a row holding the specified text, the search will not be successful and the search routine will return the index of the current focused row (in our example, it will return 0). So, you can use the incremental search if you are sure that the grid contains a row that holds the sought-for value.
The sample that iterates through rows is able to determine whether the search is successful. However, it functions slower than the incremental search. You can use it in cases when the incremental-search approach cannot be used.