Master-detail

GridControl

Two grids, one selection: pick a row in the first and the second shows what belongs to it.

Overview

A master-detail screen is two ordinary grids and one event. The master grid raises RowSelected (a GridControlEvents callback passed through EventsRef) with the selected row in args.Data; the page filters its detail list by that row's key and binds the result to the second grid's DataSource. SelectionSettings with SelectionType.Single keeps one master row selected, and AutoSelectFirstRow selects the first row as soon as the grid has rows and raises RowSelected for it, so the detail fills on arrival. RowSelecting can refuse a move while the detail has unsaved edits; the Unsaved-row lock page shows that.

Examples

#Security groups and their members

Seven groups on the left, 126 users on the right. Click a group and the right grid shows its members; the Users column of the group row, the member grid's footer and the line under the grids count the same people. The member grid sorts on its own and marks inactive accounts.

Example

Razor

Groups

Group	Admin	Users

Executive Management	True	6
Project Managers	False	24
Estimating Specialists	False	12
Purchasing & Subcontracts	False	18
Accounting & Payroll	False	15
Field Superintendents	False	42
Customer Care & Warranty	False	9

Members of Executive Management

Login	Name	Email	Active

asmith	Alex Smith	asmith@enterprise.local	True
bharris	Bradley Harris	bharris@enterprise.local	True
cortiz	Catherine Ortiz	cortiz@enterprise.local	True
dvargas	David Vargas	dvargas@enterprise.local	True
eclark	Elena Clark	eclark@enterprise.local	False
fjones	Frank Jones	fjones@enterprise.local	True

6 rows

6 members of Executive Management, 1 inactive.

Documentation

GridControl selection parameters

Parameter	Type	Default	Description
`AllowSelection`	`bool`	`true`	False makes the grid cursor-only: clicks and keys still move the active cell, editing and the click events still work, but nothing is ever selected and no selection event fires.
`AutoSelectFirstRow`	`bool`	`false`	Selects the first visible row when a selectable grid first receives rows, and again after a sort changes the order. Raises `RowSelected` but not `RowSelecting`. Skipped in Cell mode and with `CheckboxOnly`.
`InitialSelectedRowIndex`	`int?`	`null`	Displayed-row index to select before the first paint, for pickers that already know their value. Applied again when the data source or the index changes.
`HighlightSelectedRows`	`bool`	`true`	False keeps the selection and its events but does not paint the selected rows.
`SelectionSettingsRef`	`SelectionSettings?`	`null`	The settings object below. Null behaves as single row selection.
`EventsRef`	`GridControlEvents<TValue>?`	`null`	The object that holds the callbacks; the grid has no separate parameters for the selection events.

SelectionSettings

Property	Type	Default	Description
`Type`	`SelectionType`	`SelectionType.Single`	`Single` keeps one row; Ctrl or Shift with a click or an arrow still extends it unless `ModifierKeysExtendSelection` is off. `Multiple`: a plain click still collapses to the clicked row; Ctrl toggles a row, Shift selects the visible range from the last selected row.
`Mode`	`SelectionMode`	`SelectionMode.Row`	`Row` or `Cell`. In Cell mode the selected set is cells, `SelectionChanged` counts cells, and `AutoSelectFirstRow` is skipped.
`ShowCheckboxes`	`bool`	`false`	Adds the selection checkbox column while ordinary clicks still select.
`CheckboxOnly`	`bool`	`false`	Only the checkboxes change the selection; a click on a cell does not, and `AutoSelectFirstRow` is skipped.
`ModifierKeysExtendSelection`	`bool`	`true`	With `Single`, Ctrl or Shift plus a click or Shift plus an arrow add rows. False keeps exactly one row: a modifier click selects the clicked row alone. Ignored for `Multiple` and for Cell mode.
`MultiSelectBehavior`	`GridMultiSelectBehavior`	`GridMultiSelectBehavior.FullMultiSelect`	With `BatchEditBehavior = MultiRow` and several rows selected, `FullMultiSelect` keeps the selection when a plain click lands on an editable, template or command cell inside it, so a bulk edit stays armed; `VBMultiSelect` lets that click collapse to the clicked row. Ctrl, Shift and drag build multi-row selections in both.
`EnableToggle`	`bool`	`true`	Declared, but `GridControl` never reads it.
`PersistSelection`	`bool`	`false`	Declared, but `GridControl` never reads it.

GridControlEvents, selection

Event	Payload	Description
`RowSelecting`	`RowSelectEventArgs<TValue>`	Before a row is selected by mouse, keyboard or checkbox toggle. Set `Cancel` to refuse. Not raised by `AutoSelectFirstRow`, type-ahead moves or the selection methods.
`RowSelected`	`RowSelectEventArgs<TValue>`	After a row is selected by mouse, keyboard, checkbox toggle, type-ahead search or `AutoSelectFirstRow`. Not raised during drag-select or by the selection methods.
`SelectionChanged`	`int`	After any change to the selected set: click, drag-select, Select All, Clear, the selection methods. The payload is the selected count, rows or cells by `Mode`.
`SelectionChangedDetailed`	`GridSelectionChangedArgs`	Same timing, with `Count` and `Source`: Pointer, MouseDrag, Keyboard, Programmatic or Unknown.
`RowDeselecting / RowDeselected`	`RowSelectEventArgs<TValue>`	Declared, but `GridControl` never raises them. `TreeGridControl` raises `RowDeselected`.

RowSelectEventArgs<TValue>

Property	Type	Default	Description
`Data`	`TValue?`	`null`	The row.
`RowIndex`	`int`	`0`	The row's index in the grid's current display order.
`Cancel`	`bool`	`false`	Set in `RowSelecting` to keep the current selection. Ignored by `RowSelected`.

Selection methods

Method	Inputs	Returns	Description
`GetSelectedRecords()`	—	`IEnumerable<TValue>`	The selected rows, in selection order.
`GetSelectedRecordsAsync()`	—	`Task<List<TValue>>`	The same as a list.
`SelectRow()`	`int rowIndex`	`void`	Selects the displayed row at that index; with `Single` it replaces the selection, otherwise it adds.
`SelectRowIndexAsync()`	`int rowIndex`	`Task`	`SelectRow` as a task.
`SelectAndRevealRowAsync()`	`TValue item bool clearExistingSelection = false`	`Task`	Selects the row and scrolls it into view when it is off-screen, in one paint.
`ClearSelection()`	—	`void`	Clears rows and cells.
`ClearSelectionAsync()`	—	`Task`	`ClearSelection` as a task.

GridControlEvents also carries the sorting, filtering, paging, editing, grouping, resizing, reordering and cell events; those belong with the pages that use them. The methods above change the selection without raising RowSelecting or RowSelected; they raise SelectionChanged with the source Programmatic.