| 1 Test

Working With Developer Express QuantumGrid - Searching for Records

April 16, 2007

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.

' [TestComplete VBScript] Sub Main Set p = Sys.Process("Project1") Set Grid = p.VCLObject("Form1").VCLObject("cxGrid1") ' Search for a cell r = SearchCellByValue(Grid, Nothing, "VendorName", "Dive Time") ' Process result If r <> -1 Then Log.Message("Found: " + VarToStr(r)) Else Log.Message("Not found.") End If End Sub ' Search by iterating through grid rows Function SearchCellByValue(grid, view, columnId, searchString) Dim CellValue, i SearchCellByValue = -1 ' Obtain the view object If view Is Nothing Then Set view = grid.ActiveView End If ' Iterate through rows For i = 0 To GetRowCount(grid, view) - 1 ' Obtain cell value CellValue = GetCellValue(grid, view, i, columnId) ' Check cell value If CellValue = searchString Then SearchCellByValue = i Exit For End If Next End Function ' Obtain the number of rows Function GetRowCount(grid, view) ' Obtain the view If view Is Nothing Then Set view = grid.ActiveView End If ' Get the number of rows GetRowCount = view.ViewData.RowCount End Function ' Obtain cell value Function GetCellValue(grid, view, rowIndex, columnId) Dim column ' Obtain the view If view Is Nothing Then Set view = grid.ActiveView End If ' Get the column object Set column = GetColumn(grid, view, columnId) ' Get the row object Set row = view.ViewData.Rows(rowIndex) ' Get the cell text GetCellValue = view.DataController.DisplayTexts(row.RecordIndex, column.Index) End Function ' Obtain column object Function GetColumn(grid, view, columnId) Dim Columns, i ' Get the view If view Is Nothing Then Set view = grid.ActiveView End If ' Check type of the columnId parameter If VarType(columnId) = varOleStr Then ' If columnId is a string, ' then search for column by its caption For i = 0 to view.ColumnCount - 1 If view.Columns(i).Caption = columnId Then Set GetColumn = view.Columns(i) Exit For End If Next Else ' If columnId is an integer, ' then search for column by its index For i = 0 to view.ColumnCount - 1 If view.Columns(i).VisibleIndex = columnId Then Set GetColumn = view.Columns(i) Exit For End If Next End If End Function

' [TestComplete JScript] function MyTest() { var p, Grid, r; p = Sys.Process("Project1"); Grid = p.VCLObject("Form1").VCLObject("cxGrid1"); // Set Grid = GetGrid1 // Search for a cell r = SearchCellByValue(Grid, null, "VendorName", "Dive Time"); // Process result if(r != -1) Log.Message("Found: " + VarToStr(r)); else Log.Message("Not found."); } // Search by iterating through grid rows function SearchCellByValue(grid, view, columnId, searchString) { var Column, CellValue, i, r; r = -1; // Obtain the view object if(view == null) view = grid.ActiveView; // Iterate through rows for(i = 0; i < GetRowCount(grid, view); i++) { // Obtain cell value CellValue = GetCellValue(grid, view, i, columnId); // Check cell value if(CellValue == searchString) { r = i; break; } } return r; } // Obtain the number of rows function GetRowCount(grid, view) { // Obtain the view if (view == null) view = grid.ActiveView; // Get the number of rows return view.ViewData.RowCount; } // Obtain cell value function GetCellValue(grid, view, rowIndex, columnId) { var column, row; // Obtain the view if (view == null) view = grid.ActiveView; // Get the column object column = GetColumn(grid, view, columnId); // Get the row object row = view.ViewData.Rows(rowIndex); // Get the cell text return view.DataController.DisplayTexts(row.RecordIndex, column.Index); } // Obtain column object function GetColumn(grid, view, columnId) { var i; // Get the view if (view == null) view = grid.ActiveView; // Check type of the columnId parameter if (VarType(columnId) == varOleStr) { // If columnId is a string, // then search for column by its caption for (i = 0; i < view.ColumnCount; i++) if (view.Columns(i).Caption == columnId) return view.Columns(i); } else { // If columnId is an integer, // then search for column by its index for (i = 0; i < view.ColumnCount; i++) if (view.Columns(i).VisibleIndex == columnId) return view.Columns(i); } }

' [TestComplete DelphiScript] function SearchCellByValue(grid, view, columnId, searchString): Variant; forward; function GetRowCount(grid, view): Variant; forward; function GetCellValue(grid, view, rowIndex, columnId): Variant; forward; function GetColumn(grid, view, columnId): Variant; forward; procedure Main; var p, Grid, r : OleVariant; begin p := Sys.Process('Project1'); Grid := p.VCLObject('Form1').VCLObject('cxGrid1'); // Search for a cell r := SearchCellByValue(Grid, nil, 'VendorName', 'Dive Time'); // Process result if r <> -1 then Log.Message('Found: ' + VarToStr(r)) else Log.Message('Not found.'); end; // Search by iterating through grid rows function SearchCellByValue(grid, view, columnId, searchString): Variant; var CellValue, i : Variant; begin Result := -1; // Obtain the view object if view = nil then view := grid.ActiveView; // Iterate through rows for i := 0 to GetRowCount(grid, view) - 1 do begin // Obtain cell value CellValue := GetCellValue(grid, view, i, columnId); // Check cell value if CellValue = searchString then begin Result := i; Exit; end; end; end; // Obtain the number of rows function GetRowCount(grid, view): Variant; begin // Obtain the view if view = nil then view := grid.ActiveView; // Get the number of rows Result := view.ViewData.RowCount; end; // Obtain cell value function GetCellValue(grid, view, rowIndex, columnId): Variant; var column, row: Variant; begin // Obtain the view if view = nil then view := grid.ActiveView; // Get the column object column := GetColumn(grid, view, columnId); // Get the row object row := view.ViewData.Rows(rowIndex); // Get the cell text Result := view.DataController.DisplayTexts(row.RecordIndex, column.Index); end; // Obtain column object function GetColumn(grid, view, columnId): Variant; var i: Variant; begin // Get the view if view = nil then view := grid.ActiveView; // Check type of the columnId parameter if VarType(columnId) = varOleStr then begin // If columnId is a string, // then search for column by its caption for i := 0 to view.ColumnCount - 1 do if view.Columns[i].Caption = columnId then Result := view.Columns[i]; end else // If columnId is an integer, // then search for column by its index for i := 0 to view.ColumnCount - 1 do if view.Columns[i].VisibleIndex = columnId then Result := view.Columns[i]; end;

' [TestComplete C++Script, C#Script] function Main() { var p, Grid, r; p = Sys["Process"]("Project1"); Grid = p["VCLObject"]("Form1")["VCLObject"]("cxGrid1"); // Set Grid = GetGrid1 // Search for a cell r = SearchCellByValue(Grid, null, "VendorName", "Dive Time"); // Process result if(r != -1) Log["Message"]("Found: " + VarToStr(r)); else Log["Message"]("Not found."); } // Search by iterating through grid rows function SearchCellByValue(grid, view, columnId, searchString) { var Column, CellValue, i, r; r = -1; // Obtain the view object if(view == null) view = grid["ActiveView"]; // Iterate through rows for(i = 0; i < GetRowCount(grid, view); i++) { // Obtain cell value CellValue = GetCellValue(grid, view, i, columnId); // Check cell value if(CellValue == searchString) { r = i; break; } } return r; } // Obtain the number of rows function GetRowCount(grid, view) { // Obtain the view if (view == null) view = grid["ActiveView"]; // Get the number of rows return view["ViewData"]["RowCount"]; } // Obtain cell value function GetCellValue(grid, view, rowIndex, columnId) { var column, row; // Obtain the view if (view == null) view = grid["ActiveView"]; // Get the column object column = GetColumn(grid, view, columnId); // Get the row object row = view["ViewData"]["Rows"](rowIndex); // Get the cell text return view["DataController"]["DisplayTexts"](row["RecordIndex"], column["Index"]); } // Obtain column object function GetColumn(grid, view, columnId) { var i; // Get the view if (view == null) view = grid["ActiveView"]; // Check type of the columnId parameter if (VarType(columnId) == varOleStr) { // If columnId is a string, // then search for column by its caption for (i = 0; i < view["ColumnCount"]; i++) if (view["Columns"](i)["Caption"] == columnId) return view["Columns"](i); } else { // If columnId is an integer, // then search for column by its index for (i = 0; i < view["ColumnCount"]; i++) if (view["Columns"](i)["VisibleIndex"] == columnId) return view["Columns"](i); } }

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.

' [TestComplete VBScript] Sub Main Set p = Sys.Process("Project1") Set Grid = p.VCLObject("Form1").VCLObject("cxGrid1") 'Set Grid = GetGrid1 ' Search for a cell r = SearchCellWithIncremental(Grid, Nothing, "VendorName", "Dive Time") ' Process result If r <> -1 Then Log.Message("Found: " + VarToStr(r)) Else Log.Message("Not found.") End If End Sub ' Search by using the incremental search functionality Function SearchCellWithIncremental(grid, view, columnId, searchString) Dim Column, CellValue, i ' Obtain the view object If view Is Nothing Then Set view = grid.ActiveView End If ' Activates the first row view.DataController.GotoFirst ' Move focus to the desired column Set Column = GetColumn(grid, view, columnId) Column.Focused = true ' Search using the incremental search view.Controller.IncSearchingText = searchString view.DataController.Search.LocateNext(true) ' Cancels the incremental search mode view.Controller.CancelIncSearching ' Returns the result SearchCellWithIncremental = view.DataController.FocusedRowIndex End Function ' Obtain column object Function GetColumn(grid, view, columnId) Dim Columns, i ' Get the view If view Is Nothing Then Set view = grid.ActiveView End If ' Check type of the columnId parameter If VarType(columnId) = varOleStr Then ' If columnId is a string, ' then search for column by its caption For i = 0 to view.ColumnCount - 1 If view.Columns(i).Caption = columnId Then Set GetColumn = view.Columns(i) Exit For End If Next Else ' If columnId is an integer, ' then search for column by its index For i = 0 to view.ColumnCount - 1 If view.Columns(i).VisibleIndex = columnId Then Set GetColumn = view.Columns(i) Exit For End If Next End If End Function

' [TestComplete JScript] function Main() { var p, Grid, r; p = Sys.Process("Project1"); Grid = p.VCLObject("Form1").VCLObject("cxGrid1"); // Set Grid = GetGrid1 // Search for a cell r = SearchCellWithIncremental(Grid, null, "VendorName", "Dive Time") // Process result if(r != -1) Log.Message("Found: " + VarToStr(r)); else Log.Message("Not found."); } // Search by using the incremental search functionality function SearchCellWithIncremental(grid, view, columnId, searchString) { var Column, i; // Obtain the view object if (view == null) view = grid.ActiveView; // Activates the first row view.DataController.GotoFirst(); // Move focus to the desired column Column = GetColumn(grid, view, columnId); Column.Focused = true; // Search using the incremental search view.Controller.IncSearchingText = searchString; view.DataController.Search.LocateNext(true); // Cancels the incremental search mode view.Controller.CancelIncSearching(); // Returns the result return view.DataController.FocusedRowIndex; } // Obtain column object function GetColumn(grid, view, columnId) { var i; // Get the view if (view == null) view = grid.ActiveView; // Check type of the columnId parameter if (VarType(columnId) == varOleStr) { // If columnId is a string, // then search for column by its caption for (i = 0; i < view.ColumnCount; i++) if (view.Columns(i).Caption == columnId) return view.Columns(i); } else { // If columnId is an integer, // then search for column by its index for (i = 0; i < view.ColumnCount; i++) if (view.Columns(i).VisibleIndex == columnId) return view.Columns(i); } }

' [TestComplete DelphiScript] function SearchCellWithIncremental(grid, view, columnId, searchString): Variant; forward; function GetColumn(grid, view, columnId): Variant; forward; procedure Main; var p, Grid, r : OleVariant; begin p := Sys.Process('Project1'); Grid := p.VCLObject('Form1').VCLObject('cxGrid1'); // Search for a cell r := SearchCellWithIncremental(Grid, nil, 'VendorName', 'Dive Time'); // Process result if r <> -1 then Log.Message('Found: ' + VarToStr(r)) else Log.Message('Not found.'); end; ' Search by using the incremental search functionality Function SearchCellWithIncremental(grid, view, columnId, searchString) Dim Column, i ' Obtain the view object If view Is Nothing Then Set view = grid.ActiveView End If ' Activates the first row view.DataController.GotoFirst ' Move focus to the desired column Set Column = GetColumn(grid, view, columnId) Column.Focused = true ' Search using the incremental search view.Controller.IncSearchingText = searchString view.DataController.Search.LocateNext(true) ' Cancels the incremental search mode view.Controller.CancelIncSearching ' Returns the result SearchCellWithIncremental = view.DataController.FocusedRowIndex End Function // Obtain column object function GetColumn(grid, view, columnId): Variant; var i: Variant; begin // Get the view if view = nil then view := grid.ActiveView; // Check type of the columnId parameter if VarType(columnId) = varOleStr then begin // If columnId is a string, // then search for column by its caption for i := 0 to view.ColumnCount - 1 do if view.Columns[i].Caption = columnId then Result := view.Columns[i]; end else // If columnId is an integer, // then search for column by its index for i := 0 to view.ColumnCount - 1 do if view.Columns[i].VisibleIndex = columnId then Result := view.Columns[i]; end;

' [TestComplete C++Script, C#Script] function Main() { var p, Grid, r; p = Sys["Process"]("Project1"); Grid = p["VCLObject"]("Form1")["VCLObject"]("cxGrid1"); // Set Grid = GetGrid1 // Search for a cell r = SearchCellWithIncremental(Grid, null, "VendorName", "Dive Time") // Process result if(r != -1) Log["Message"]("Found: " + VarToStr(r)); else Log["Message"]("Not found."); } // Search by using the incremental search functionality function SearchCellWithIncremental(grid, view, columnId, searchString) { var Column, i; // Obtain the view object if (view == null) view = grid["ActiveView"]; // Activates the first row view["DataController"]["GotoFirst"](); // Move focus to the desired column Column = GetColumn(grid, view, columnId); Column["Focused"] = true; // Search using the incremental search view["Controller"]["IncSearchingText"] = searchString; view["DataController"]["Search"]["LocateNext"](true); // Cancels the incremental search mode view["Controller"]["CancelIncSearching"](); // Returns the result return view["DataController"]["FocusedRowIndex"]; } // Obtain column object function GetColumn(grid, view, columnId) { var i; // Get the view if (view == null) view = grid["ActiveView"]; // Check type of the columnId parameter if (VarType(columnId) == varOleStr) { // If columnId is a string, // then search for column by its caption for (i = 0; i < view["ColumnCount"]; i++) if (view["Columns"](i)["Caption"] == columnId) return view["Columns"](i); } else { // If columnId is an integer, // then search for column by its index for (i = 0; i < view["ColumnCount"]; i++) if (view["Columns"](i)["VisibleIndex"] == columnId) return view["Columns"](i); } }

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.

Working With Developer Express QuantumGrid - Searching for Records

Searching by Iterating Through Grid Rows

Searching by Using the Incremental Search Feature

Which Approach to Choose

Products

Additional Links