DataGrid Class

To bind the DataGrid to data, set the ItemsSource property to an IEnumerable implementation. Each row in the data grid is bound to an object in the data source, and each column in the data grid is bound to a property of the data object. In order for the DataGrid user interface to update automatically when items are added to or removed from the source data, the DataGrid must be bound to a collection that implements the INotifyCollectionChanged interface, such as an ObservableCollection<T>. To automatically reflect property changes, the objects in the source collection must implement the INotifyPropertyChanged interface. For more information, see Data Binding (WPF).

By default, the DataGrid control generates columns automatically when you set the ItemsSource property. The type of column that is generated depends on the type of data in the column. The following table lists the generated columns types.

The following illustration shows each of the column types.

When columns are auto-generated, you can handle the AutoGeneratingColumn event to customize or cancel columns before they are added to the DataGrid. If you add both user-defined columns and auto-generated columns to the DataGrid, the user-defined columns are added first. To rearrange the display order of the columns, you can set the DisplayIndex property for individual columns.

You can prevent automatic column generation by setting the AutoGenerateColumns property to false. This is useful if you want to create and configure all columns explicitly.

Use the DataGridTemplateColumn type to define a custom column if the built-in column types do not meet your needs. The DataGridTemplateColumn type provides CellTemplate and CellEditingTemplate properties that enable you to specify content templates for both display and editing modes. For example, you could define a custom column for dates. The CellTemplate could define a TextBlock to display a date, and the CellEditingTemplate could define a DatePicker control to edit the date.

You can use the Columns collection to programmatically add, insert, remove, and change any columns in the control at run time. Check the IsAutoGenerated property to determine whether a column is auto generated or user defined. Auto-generated columns will be automatically added, removed, or regenerated when the ItemsSource changes.

By default, the entire row is selected when a user clicks a cell in a DataGrid, and a user can select multiple rows. You can set the SelectionMode property to specify whether a user can select cells, full rows, or both. Set the SelectionUnit property to specify whether multiple rows or cells can be selected, or only single rows or cells.

You can get information about the cells that are selected from the SelectedCells property. You can get information about cells for which selection has changed in the SelectedCellsChangedEventArgs of the SelectedCellsChanged event. Call the SelectAllCells or UnselectAllCells methods to programmatically select or unselect all cells. For more information, see Default Keyboard and Mouse Behavior in the DataGrid Control.

By default, you can sort items in a DataGrid by clicking the column header. You can customize sorting by handling the Sorting event. To cancel the default sort, set the Handled property to true. You can also sort the source data before it is displayed in the DataGrid.

To group, sort, and filter data in the DataGrid, you bind the DataGrid to an ICollectionView implementation that supports these operations. You then perform the operations on the collection view. When items are grouped in the DataGrid, you can define a GroupStyle that specifies the appearance of each group. You apply the GroupStyle by adding it to the GroupStyle collection of the DataGrid. If you have multiple levels of grouping, you can apply different styles to each group level. Styles are applied in the order in which they are defined. For more information, see How to: Group, Sort, and Filter Data in the DataGrid Control.

By default, you can edit items directly in the DataGrid. To guarantee that edits can be committed and canceled correctly, the objects in the DataGrid must implement the IEditableObject interface. Alternatively, you can set the IsReadOnly property to true to disable editing in the DataGrid.

The DataGrid has built-in support for the following editing commands:

You put the current cell into edit mode by clicking it or pressing F2. A cell-level edit is committed when you move to another cell in the same row or press ENTER while the cell is in edit mode. All edits in a row are committed when you move to another row or press ENTER while the row is in edit mode. You cancel a cell edit by pressing ESC one time, and cancel all edits in a row by pressing ESC two times. For more information about programmatically committing and canceling edits, see the BeginEdit, CommitEdit, and CancelEdit methods. For more information about edit-related events, see BeginningEdit, PreparingCellForEdit, CellEditEnding, and RowEditEnding.

Set the CanUserAddRows and CanUserDeleteRows properties to specify whether a user can add or delete rows. A user can delete selected rows by pressing the DELETE key. If the CanUserAddRows property is set to true, a new item row is added as the last row in the DataGrid. You can set default values for new items by handling the InitializingNewItem event.

Note
Whether editing actions are allowed is influenced by a variety of additional factors, including the IsReadOnly and IsEnabled state of the DataGrid, and whether the underlying data collection allows the action.

The DataGrid enables you to perform validation at both the cell and row level. With cell-level validation, you validate individual properties of a bound data object when a user updates a value. With row-level validation, you validate entire data objects when a user commits changes to a row. You can provide customized visual feedback for row-level validation errors by setting the RowValidationErrorTemplate property, or you can use the default error indicator. To create a custom validation rule, create a class that derives from the ValidationRule class and implement the Validate method. Add the custom validation rule to the RowValidationRules collection.

The DataGrid control supports common table formatting options, such as alternating row backgrounds and the ability to show or hide headers, gridlines, and scroll bars. Additionally, the control provides several style and template properties that you can use to completely change the appearance of the control and its rows, columns, headers, and cells.

To customize DataGrid behavior, you can handle events for selection change, cell editing, and column re-ordering. The DataGrid also exposes several events for row recycling that you can handle to customize rows.

To apply the same property settings to multiple DataGrid controls, use the Style property. You can modify the default ControlTemplate to give the control a unique appearance. For more information about creating a ControlTemplate, see Customizing the Appearance of an Existing Control by Creating a ControlTemplate. To see the parts and states that are specific to the DataGrid, see DataGrid Styles and Templates.

Dependency properties for this control might be set by the control’s default style. If a property is set by a default style, the property might change from its default value when the control appears in the application. The default style is determined by which desktop theme is used when the application is running. For more information, see Default WPF Themes.

Note
Setting a visual property will only have an effect if that property is both present in the DataGrid control's default template and is set by using a TemplateBinding. You can find a list of visual properties in the "Changing the Visual Structure of a Control" section in Customizing the Appearance of an Existing Control by Creating a ControlTemplate.

The following table provides information about tasks that are typically associated with the DataGrid.