Searching for Records in Developer Express XtraGrid

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:

  • Main is the main routine. It obtains the scripting object corresponding to the XtraGrid control, and locates two grid records using the FindRowByCellText and FindRowByCellValue functions. If the rows are found, it selects them and posts their indexes to the test log. Note that to pass the sought-for value to the FindRowByCellValue function, we need to convert it to the .NET object corresponding to the cell’s data type. In the given case, we use the CreateDecimal routine to create a System.Decimal object, because the grid column in which the search is performed (“Unit Price”) holds values of this .NET type.
  • CreateDecimal is a helper function that creates a .NET System.Decimal object with the specified value.
  • FindRowByCellValue locates a grid row (card) by the value in the specified column (card field). If the row (card) was found, FindRowByCellValue returns the zero-based index of the row (card); otherwise returns the special InvalidRowHandle value that does not correspond to a row (card).

    The function has the following parameters:

    • Grid - The tested XtraGrid control.
    • View - The grid view that contains the sought-for row (card). If this parameter has the null value (Nothing in VBScript, nil in DelphiScript, null in JScript, C++Script and C#Script), it means that the row (card) belongs to the grid’s main view.
    • ColumnId - The column caption or the column’s visible index within the grid.
    • Value - The “native” .NET object (for example, Decimal, DateTime and others) that holds the sought-for value.
  • FindRowByCellText locates a grid row (card) by the text displayed in the specified column (card field). If the row (card) was found, FindRowByCellText returns the zero-based index of the row (card); otherwise returns the special InvalidRowHandle value that does not correspond to a row (card). This function has the same parameters as the FindRowByCellValue function, except for the last parameter - Text that specified the sought-for text.
  • GetColumn is a helper function that returns the column object specified by its caption or position in the grid.

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:

  • Main is the main routine. It obtains the scripting object corresponding to the grid control, calls FindRowByMultipleCellText to locate a grid row and then modifies row cell values.
  • FindRowByMultipleCellText locates a grid row (card) by text displayed in multiple columns (card fields). The function returns the index (zero-based) of the first matching row (card). If a row (card) does not match the specified criteria, it returns the special InvalidRowHandle value that does not correspond to a row (card).

    The function has the following parameters:

    • Grid - The tested XtraGrid control.
    • View - The grid view that contains the sought-for row (card). If this parameter has the null value (Nothing in VBScript, nil in DelphiScript, null in JScript, C++Script and C#Script), it means that the row (card) belongs to the grid’s main view.
    • Columns - An array containing columns’ captions, or the columns’ visible indexes within the grid.
    • Strings - An array of strings sought in the corresponding columns specified by Columns parameter.
  • GetColumnObjects - a helper function that returns an array containing column objects specified by their captions or positions in the grid.
  • GetColumn is a helper function that returns the column object specified by its caption or position in the grid.


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