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 GridObj.ActiveView.OptionsBehavior.IncSearch property.

The sample contains the following routines:

  • Main - The “main” routine of the sample. It obtains the scripting object that corresponds to the tested grid and then calls the SearchCellWithIncremental function that performs the search.
  • SearchCellWithIncremental - Searches for a row containing a cell with the specified text. If the row is found, the function returns the row’s index (zero-based). If the row was not found, the function will return the index of the current row.

    The routine uses the following parameters:

    • grid - The scripting object that corresponds to the tested QuantumGrid object.
    • 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 - The caption or the index of the column, in which the search will be performed. The column index is zero-based. It indicates the column position among other visible columns.
    • searchString - The text to be searched with the incremental search feature.

    The SearchCellWithIncremental routine performs the following actions:

    • If the view object is not specified, the routine obtains the view object that corresponds to the root level.
    • Calls the DataController.GotoFirst method of the view object. This method activates the first row in the view and thus guarantees that the search is performed from the first row.
    • Calls the GetColumn function to obtain the object that corresponds to the specified column.
    • Assigns True to the the column’s Focused property to move the insertion point to that column.
    • Assigns the specified search value (the searchString parameter) to the Controller.IncSearchingText property of the view object. This will specify the sought-for text for the grid.
    • Initiates the search by calling the DataController.Search.LocateNext(true) method of the view object. The True value passed to the LocateNext method specifies the forward direction of the search. If you passed False, the grid would search backward.
    • To cancel the incremental search mode, the script routine calls the Controller.CancelIncSearching method of the view object.
    • Finally, the SearchCellWithIncremental routine returns the index of the focused row by using the DataController.FocusedRowIndex property of the view object. If the desired row was not found, the current row will remain the same, so the routine will return the index of the current row.
  • GetColumn - Helper routine that returns the TcxGridColumn object that represents a grid column.

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.


Close

Add a little SmartBear to your life

Stay on top of your Software game with the latest developer tips, best practices and news, delivered straight to your inbox

By submitting this form, you agree to our
Terms of Use and Privacy Policy

Thanks for Subscribing

Keep an eye on your inbox for more great content.

Continue Reading