Identify and Access Rows

• Apr 19, 2019
• 3 minutes to read

Important

This documentation topic describes legacy technology. We no longer develop new functionality for the GridControl and suggest that you use the new DataGridView control instead.

When using GridControl, you may need to perform operations on rows using code. For instance, to focus (select) a specific row in code, you first need to get the corresponding row identifier and assign it to the GridControl.SelectedRowHandle property. Alternatively, you may wish to identify the type of the row or row value that is currently hovered. In these cases, you will need to know how to identify rows within the grid.

Identify Rows - Row Handles

Rows in a GridControl are identified by unique integer values - row handles. A grid associates its rows with these values using the following rules:

• Each row has a row handle which uniquely identifies it, regardless of whether a row is currently visible (a row might not be visible due to scrolling, and it can also be hidden within a collapsed group).
• Data row handles start from zero. The zero row handle is assigned to the first data row within a grid. In this case, “first” implies the visual row order, but does not necessarily refer to the record’s position within the bound data source. Then, successive integer values are assigned to additional data rows. The second data row handle is 1, the third data row handle is 2, etc. Note that modifying the row order changes the handles assigned to rows. This occurs, for example, when grid data is sorted or grouped. As a result, a specific row handle may refer to different rows at different times.
• Group row handles are negative, starting from -1. Again, group row handles change when rows are reordered.

Obtain Row Handles

Member	Description
GridControl.FindRowByValue	Searches for the value in the column and returns the handle of the corresponding row.
GridControl.GetRowHandle	Returns the handle of the row which corresponds to the specified record in the data source.
GridControl.SelectedRowHandle	Gets or sets the selected row handle. This is a bindable property.

Use Row Handles

Row handles are used by GridControl to reference its rows. For instance, the GridControl.SelectedRowHandle property specifies the selected row by its handle. The GridControl.SelectionChanged event passes the currently selected row handle as a parameter. When accessing (GridControl.GetCellValue) or changing (GridControl.SetCellValue) cell values, you need to provide the appropriate row handle.

To obtain information on an individual group of rows, use the GridControl.GetGroupInfo and GridControl.GetGroupRowValue method with the appropriate group row handle passed as a parameter. To collapse or expand a group of rows, call the GridControl.CollapseGroupRow or GridControl.ExpandGroupRow method with the specified group row handle. When collapsing or expanding a group row, the GridControl.GroupRowCollapsing, GridControl.GroupRowCollapsed, GridControl.GroupRowExpanding and GridControl.GroupRowExpanded events also identify the affected group row by its handle.

If you need to programmatically scroll the grid to the specified row or delete a row, pass required row handle to the GridControl.ScrollToRow or GridControl.DeleteRow method, respectively.

Obtain Data Rows and Row Indexes in the Data Source

Row handles reflect the visual order of rows in a grid, and these may change as rows change their positions. In many cases, the best solution for referring to specific rows is to use objects that represent records in the bound data source. To refer to a particular row in a data source, you can use a row’s index in a data source. To obtain a row’s list index by specifying its handle, use the GridControl.GetSourceRowIndex method. To obtain a row object that corresponds to a row with the specified handle, use GridControl.GetRow.