windowsforms-711-controls-and-libraries-data-grid-focus-and-selection-handling-multiple-row-and-cell-selection.md
The DevExpress Grid control supports the following selection options:
In multiple row/card selection mode, a user can select multiple rows/cards:
Multiple row/card selection is supported by the following Views:
To enable multiple row/card selection, set the View’s OptionsSelection.MultiSelect property to true :
gridView1.OptionsSelection.MultiSelect = true;
gridView1.OptionsSelection.MultiSelect = True
//Enable multiple row selection.
gridView1.OptionsSelection.MultiSelect = true;
//Select the second, third, and fourth rows.
gridView1.SelectRows(1, 3);
'Enable multiple row selection.
gridView1.OptionsSelection.MultiSelect = True
'Select the second, third, and fourth rows.
gridView1.SelectRows(1, 3)
The GridView supports Web style row selection. In this mode, the GridView displays a column with check boxes:
Watch Video: Web Style Row Selection
Set the GridView’s OptionsSelection.MultiSelectMode property to GridMultiSelectMode.CheckBoxRowSelect to enable Web style row selection:
using DevExpress.XtraGrid.Views.Grid;
//...
gridView1.OptionsSelection.MultiSelect = true;
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CheckBoxRowSelect;
Imports DevExpress.XtraGrid.Views.Grid
'...
gridView1.OptionsSelection.MultiSelect = True
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CheckBoxRowSelect
Tip
You can bind selected state of rows to a data source field.
Read the following topic for additional information and examples: Web Style Row Selection and Selection Binding.
|
API Member
|
Description
| | --- | --- | |
|
Selects the specified row/card.
| |
|
Selects specified rows/cards.
| |
|
Deselects the specified row/card.
| |
|
Clears the selection.
| |
|
Gets the number of selected rows.
| |
|
Returns an integer array that contains handles of selected rows.
| |
|
Occurs after selection has been changed.
| |
|
These methods prevent excessive updates when doing several selection-related operations in code.
|
Run Demo: Obtain Selected Rows
Each time you select or deselect a row, the View raises the SelectionChanged event. Sequential calling of selection-related APIs may slow down application performance. Enclose sequential selection-related modifications within BeginSelection() and EndSelection() method calls:
using System.ComponentModel;
using DevExpress.Data;
using DevExpress.XtraEditors;
using DevExpress.XtraGrid.Views.Grid;
namespace DXApplication {
public partial class Form1 : XtraForm {
public Form1() {
InitializeComponent();
BindGridControl();
//Enable multiple row selection.
gridView1.OptionsSelection.MultiSelect = true;
gridView1.SelectionChanged += GridView1_SelectionChanged;
simpleButton1.Click += SimpleButton1_Click;
}
void SimpleButton1_Click(object sender, System.EventArgs e) {
//Select rows based on a condition.
SelectRoles("Guest", gridView1);
}
void GridView1_SelectionChanged(object sender, SelectionChangedEventArgs e) {
memoEdit1.AppendText("The GridView's SelectionChanged event raised.\r\n");
}
void SelectRoles(string role, GridView gridView) {
int rowHandle;
gridView.BeginSelection();
for(int i = 0; i < gridView1.RowCount; i++) {
rowHandle = gridView.GetVisibleRowHandle(i);
if (gridView.GetRowCellValue(gridView.GetVisibleRowHandle(i), "Role").ToString() == role)
gridView.SelectRow(rowHandle);
}
gridView.EndSelection();
}
void BindGridControl(){
gridControl1.DataSource = new BindingList<DataItem>() {
new DataItem(){ Role = "Admin", FullName = "Mike Spirit" },
new DataItem(){ Role = "Guest", FullName = "Nathan White" },
new DataItem(){ Role = "Guest", FullName = "Amanda Lee" },
new DataItem(){ Role = "Moderator", FullName = "Jason Norton" },
new DataItem(){ Role = "Moderator", FullName = "Mike Morris" },
};
}
}
public class DataItem {
public string Role { get; set; }
public string FullName { get; set; }
}
}
Imports Microsoft.VisualBasic
Imports System.ComponentModel
Imports DevExpress.Data
Imports DevExpress.XtraEditors
Imports DevExpress.XtraGrid.Views.Grid
Namespace DXApplication
Partial Public Class Form1
Inherits XtraForm
Public Sub New()
InitializeComponent()
BindGridControl()
'Enable multiple row selection.
gridView1.OptionsSelection.MultiSelect = True
AddHandler gridView1.SelectionChanged, AddressOf GridView1_SelectionChanged
AddHandler simpleButton1.Click, AddressOf SimpleButton1_Click
End Sub
Private Sub SimpleButton1_Click(ByVal sender As Object, ByVal e As System.EventArgs)
'Select rows based on a condition.
SelectRoles("Guest", gridView1)
End Sub
Private Sub GridView1_SelectionChanged(ByVal sender As Object, ByVal e As SelectionChangedEventArgs)
memoEdit1.AppendText("The GridView's SelectionChanged event raised." & vbCrLf)
End Sub
Private Sub SelectRoles(ByVal role As String, ByVal gridView As GridView)
Dim rowHandle As Integer
gridView.BeginSelection()
For i As Integer = 0 To gridView1.RowCount - 1
rowHandle = gridView.GetVisibleRowHandle(i)
If gridView.GetRowCellValue(gridView.GetVisibleRowHandle(i), "Role").ToString() = role Then
gridView.SelectRow(rowHandle)
End If
Next i
gridView.EndSelection()
End Sub
Private Sub BindGridControl()
gridControl1.DataSource = New BindingList(Of DataItem)() From {
New DataItem() With {
.Role = "Admin",
.FullName = "Mike Spirit"
},
New DataItem() With {
.Role = "Guest",
.FullName = "Nathan White"
},
New DataItem() With {
.Role = "Guest",
.FullName = "Amanda Lee"
},
New DataItem() With {
.Role = "Moderator",
.FullName = "Jason Norton"
},
New DataItem() With {
.Role = "Moderator",
.FullName = "Mike Morris"
}
}
End Sub
End Class
Public Class DataItem
Public Property Role() As String
Public Property FullName() As String
End Class
End Namespace
Read the following topic for additional information: Batch Modifications.
In multiple cell selection mode, users can select multiple cells within different rows:
Multiple cell selection is supported by the following views:
To enable multiple cell selection mode, set the View’s OptionsSelection.MultiSelect property to true and the OptionsSelection.MultiSelectMode property to GridMultiSelectMode.CellSelect:
using DevExpress.XtraGrid.Views.Grid;
//...
gridView1.OptionsSelection.MultiSelect = true;
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CellSelect;
Imports DevExpress.XtraGrid.Views.Grid
'...
gridView1.OptionsSelection.MultiSelect = True
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CellSelect
using DevExpress.XtraGrid.Views.Base;
using DevExpress.XtraGrid.Views.Grid;
//...
gridView1.OptionsSelection.MultiSelect = true;
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CellSelect;
gridView1.SelectCell(0, gridView1.Columns["Role"]);
gridView1.SelectCells(new GridCell(1, gridView1.Columns["FullName"]), new GridCell(3, gridView1.Columns["FullName"]));
Imports DevExpress.XtraGrid.Views.Base
Imports DevExpress.XtraGrid.Views.Grid
'...
gridView1.OptionsSelection.MultiSelect = True
gridView1.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CellSelect
gridView1.SelectCell(0, gridView1.Columns("Role"))
gridView1.SelectCells(New GridCell(1, gridView1.Columns("FullName")), New GridCell(3, gridView1.Columns("FullName")))
The image below shows the result:
The following table lists related APIs:
| API Member | Description |
|---|---|
| SelectCell | Selects the specified cell. |
| SelectCells | Selects a range of cells. |
| SelectAll() | Selects all cells within the View. |
| UnselectCell | Deselects the specified cell. |
| UnSelectCells | Deselects a range of cells. |
| ClearSelection() | Clears selection. |
| GetSelectedCells | Returns selected cells. |
| GetSelectedRows() | Returns handles of rows that contain selected cells. |
Multiple row/cell selection is disabled by default. A user can select (focus) only one row/card at the same time.
The focused row (or a card in the CardView) is the row that accepts input from a user. There can only be one focused row in a View, regardless of the selection mode. Multiple row selection is a visual feature that highlights specific rows.
Note
When multiple row selection is enabled and the user focuses a new row, the row is selected (highlighted). When you focus a row in code, the row is not automatically selected (highlighted).
The following images demonstrate selected and deselected states of the focused row:
|
Focused Row is selected
|
The ColumnView.GetSelectedRows method returns three row handles, including the focused row handle.
| |
Focused Row is deselected
|
The ColumnView.GetSelectedRows method returns two handles that correspond to selected rows. The focused row handle will not be included in the method’s resulting array.
|
The table below lists related APIs:
|
API Member
|
Description
| | --- | --- | |
|
Gets or sets the focused (selected) row/card.
| |
|
This event occurs after the focused row has been changed.
| |
|
In single row/card selection mode, the GetSelectedRows method returns an integer array that contains a single element (the focused row’s handle).
| |
|
In single row/card selection mode, the SelectedRowsCount property returns 1.
|
Read the following topics for additional information:
|
API Member
|
Description
| | --- | --- | |
|
Copies the focused or selected record(s) to the Clipboard as text.
| |
|
Deletes a specific row/card.
| |
|
Deletes the focused or selected rows.
| |
|
Returns an object that contains a specified row.
| |
|
Returns a DataRow object that contains a specified row.
| |
ColumnView.GetFocusedRowCellValue
|
Gets the value in a row’s field.
| |
ColumnView.GetRowCellDisplayText
ColumnView.GetFocusedRowCellDisplayText
|
Gets the text representation of a row’s value.
| |
ColumnView.SetFocusedRowCellValue
|
Assigns a value to a row’s cell.
|
A user can select rows/cards and cells with a mouse and keyboard. Please refer to the following topic for more information: End-User Capabilities: Selecting Rows/Cards.
Handle the SelectionChanging event to control whether a user can select or deselect specific rows/cards/cells based on a condition.
The following code sample does not allow users to select the first 5 rows:
gridView1.SelectionChanging += (s, e) => {
e.Cancel = e.Action == CollectionChangeAction.Add && e.ControllerRow <= 4;
};
gridView1.SelectionChanging += Function(s, e)
e.Cancel = e.Action = CollectionChangeAction.Add AndAlso e.ControllerRow <= 4
End Function
Selected and focused rows are painted with the same appearance settings. Use appearance-related properties of the View’s Appearance object (GridView.Appearance, CardView.Appearance, etc.).
| API Member | Description |
|---|---|
| GridViewAppearances.FocusedRow | Contains appearance settings used to paint the focused row. |
| GridViewAppearances.SelectedRow | Contains appearance settings used to paint selected rows. |
| GridViewAppearances.HideSelectionRow | Contains appearance settings used to paint selected rows when the Grid Control is not focused. |
| CardViewAppearances.FocusedCardCaption | Contains appearance settings used to paint the caption of the focused card. |
| CardViewAppearances.SelectedCardCaption | Contains appearance settings used to paint captions of selected cards. |
| CardViewAppearances.HideSelectionCardCaption | Contains appearance settings used to paint captions of selected cards when the Grid Control is not focused. |
Row appearance settings take priority over column appearance settings (GridColumn.AppearanceCell). To prioritize column appearance settings, enable the GridColumn.AppearanceCell.Options.HighPriority option:
gridColumn1.AppearanceCell.Options.HighPriority = true;
GridColumn1.AppearanceCell.Options.HighPriority = True
Read the following topic for additional information: Priority of Appearance Objects.
Handle the following events to customize appearance settings of cells within selected rows:
To prevent the focused row from being highlighted, set the View’s OptionsSelection.EnableAppearanceFocusedRow property to false. The View’s OptionsSelection.EnableAppearanceFocusedCell property allows you to disable coloring of a focused cell.
The following example disables focused cell appearance settings and keeps the focused row’s appearance when the Grid Control loses focus:
void Form1_Load(object sender, EventArgs e) {
gridView1.OptionsSelection.EnableAppearanceHideSelection = false;
gridView1.OptionsSelection.EnableAppearanceFocusedCell = false;
}
Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
gridView1.OptionsSelection.EnableAppearanceHideSelection = False
gridView1.OptionsSelection.EnableAppearanceFocusedCell = False
End Sub
Tip
To prevent selected/focused rows from being highlighted when the grid control is not focused, use the View’s OptionsSelection.EnableAppearanceHideSelection property.
You can use the following techniques to display selected rows and cells without highlight effects:
Assign regular row appearance to the GridViewAppearances.SelectedRow property:
Handle the GridView.RowStyle, GridView.RowCellStyle, or GridView.CustomDrawCell event and modify selected row appearance:
This example obtains selected rows and modifies their values in the “Discounted” column.
If data is sorted or filtered, changes made to one grid row can make other rows change their order and, as a result, their row handles. For this reason, you cannot access selected rows by their handles and process these rows right away. Instead, pass row handles retrieved by the ColumnView.GetSelectedRows method to the ColumnView.GetDataRow method. This allows you to access underlying data source objects (in this example, DataRows), save them to an array, and safely change their values afterwards.
Each row modification forces the Grid View to update itself. The example encloses the code within BaseView.BeginUpdate and BaseView.EndUpdate method calls to avoid excessive updates.
ArrayList rows = new ArrayList();
// Add the selected rows to the list.
Int32[] selectedRowHandles = gridView1.GetSelectedRows();
for (int i = 0; i < selectedRowHandles.Length; i++) {
int selectedRowHandle = selectedRowHandles[i];
if (selectedRowHandle >= 0)
rows.Add(gridView1.GetDataRow(selectedRowHandle));
}
try {
gridView1.BeginUpdate();
for (int i = 0; i < rows.Count; i++) {
DataRow row = rows[i] as DataRow;
// Change the field value.
row["Discontinued"] = true;
}
}
finally {
gridView1.EndUpdate();
}
Dim Rows As New ArrayList()
' Add the selected rows to the list.
Dim selectedRowHandles As Int32() = GridView1.GetSelectedRows()
Dim I As Integer
For I = 0 To selectedRowHandles.Length - 1
Dim selectedRowHandle As Int32 = selectedRowHandles(I)
If (selectedRowHandle >= 0) Then
Rows.Add(GridView1.GetDataRow(selectedRowHandle))
End If
Next
Try
GridView1.BeginUpdate()
For I = 0 To Rows.Count - 1
Dim Row As DataRow = CType(Rows(I), DataRow)
' Change the field value.
Row("Discontinued") = True
Next
Finally
GridView1.EndUpdate()
End Try
Run Demo: Obtain Selected Rows
The following example emulates the behavior introduced in Microsoft Excel (when a user left-clicks a column header, all cells displayed within this column are highlighted):
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraGrid.Views.Grid.ViewInfo;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Drawing;
using DevExpress.Data;
using DevExpress.XtraGrid.Columns;
using DevExpress.Utils;
namespace DXApplication16 {
public partial class Form1 : FluentDesignForm {
// The list of selected columns:
ArrayList selectedColumns;
public Form1() {
InitializeComponent();
gridView1.MouseDown += GridView1_MouseDown;
this.Load += Form1_Load;
}
private void Form1_Load(object sender, System.EventArgs e) {
selectedColumns = new ArrayList();
}
private void GridView1_MouseDown(object sender, MouseEventArgs e) {
GridView view = sender as GridView;
GridHitInfo info = view.CalcHitInfo(new Point(e.X, e.Y));
if (info.InColumn & e.Button == MouseButtons.Left) {
// Disable sort operations when a user left-clicks a header.
info.Column.OptionsColumn.AllowSort = DefaultBoolean.False;
// Check whether the clicked column is already in the list.
if (!selectedColumns.Contains(info.Column.FieldName)) {
// If not, custom draw its cells and add it to the list.
info.Column.AppearanceCell.Assign(view.PaintAppearance.SelectedRow);
selectedColumns.Add(info.Column.Name);
}
else {
// Otherwise, remove this column from the selected columns list
// and reset its cell appearances.
selectedColumns.Remove(info.Column.Name);
info.Column.AppearanceCell.Reset();
}
}
else {
// If anything but a column header is clicked,
// reset all column cell appearances and clear the list.
if (selectedColumns.Count != 0) {
foreach (string name in selectedColumns)
view.Columns.ColumnByName(name).AppearanceCell.BackColor =
Color.Transparent;
selectedColumns.Clear();
}
}
// Users can still right-click a header and choose sort options.
if (info.InColumn & e.Button == MouseButtons.Right) {
info.Column.OptionsColumn.AllowSort = DefaultBoolean.Default;
}
}
}
}
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraGrid.Views.Grid.ViewInfo
Imports System.Collections
Imports System.ComponentModel
Imports System.Windows.Forms
Imports System.Drawing
Imports DevExpress.Data
Imports DevExpress.XtraGrid.Columns
Imports DevExpress.Utils
Namespace DXApplication16
Partial Public Class Form1
Inherits FluentDesignForm
' The list of selected columns:
Private selectedColumns As ArrayList
Public Sub New()
InitializeComponent()
AddHandler gridView1.MouseDown, AddressOf GridView1_MouseDown
AddHandler Me.Load, AddressOf Form1_Load
End Sub
Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs)
selectedColumns = New ArrayList()
End Sub
Private Sub GridView1_MouseDown(ByVal sender As Object, ByVal e As MouseEventArgs)
Dim view As GridView = TryCast(sender, GridView)
Dim info As GridHitInfo = view.CalcHitInfo(New Point(e.X, e.Y))
If info.InColumn And e.Button = MouseButtons.Left Then
' Disable sort operations when a user left-clicks a header.
info.Column.OptionsColumn.AllowSort = DefaultBoolean.False
' Check whether the clicked column is already in the list.
If Not selectedColumns.Contains(info.Column.FieldName) Then
' If not, custom draw its cells and add it to the list.
info.Column.AppearanceCell.Assign(view.PaintAppearance.SelectedRow)
selectedColumns.Add(info.Column.Name)
Else
' Otherwise, remove this column from the selected columns list
' and reset its cell appearances.
selectedColumns.Remove(info.Column.Name)
info.Column.AppearanceCell.Reset()
End If
Else
' If anything but a column header is clicked,
' reset all column cell appearances and clear the list.
If selectedColumns.Count <> 0 Then
For Each name As String In selectedColumns
view.Columns.ColumnByName(name).AppearanceCell.BackColor = Color.Transparent
Next name
selectedColumns.Clear()
End If
End If
' Users can still right-click a header and choose sort options.
If info.InColumn And e.Button = MouseButtons.Right Then
info.Column.OptionsColumn.AllowSort = DefaultBoolean.Default
End If
End Sub
End Class
End Namespace
Run Demo: How to Select a Column in Excel Style
Data Grid cells can embed interactive editors (for instance, check boxes or ButtonEdit buttons). When multiple row/cell selection is enabled, clicking such UI elements activates the cell but its editor does not raise events (for example, Click or CheckedChanged) because the editor does not yet exist. To trigger these events, a user must click the element the second time.
To change this behavior, set the ColumnViewOptionsBehavior.EditorShowMode property to EditorShowMode.MouseDown.
See Also
Examples: Navigation and Selection
End-User Capabilities: Selecting Rows/Cards
Multiple Row Selection using Built-In Check Column and Selection Binding