The DataGrid Control

What a DataGrid is and why you want one

A DataGrid is a table control. Each object in a collection becomes a row, and each property you choose becomes a column. Think of a spreadsheet that is wired straight to your C# objects.

A ListBox with a data template can show a list nicely, but a DataGrid gives you a lot for free:

• column headers you can click to sort
• columns the user can resize and reorder
• editing cells in place, with the changes written back to your objects
• adding and deleting rows
• single or multiple selection

For CoinJar, an expense tracker, a grid of expenses (title, category, date, amount) is exactly the right fit. In this lesson you will build that grid step by step.

The starting point

We keep the pieces from the earlier lessons. An Expense class raises PropertyChanged (from INotifyPropertyChanged), and the window’s data lives in an ObservableCollection<Expense> (from Binding to Collections).

public class ExpenseListViewModel : INotifyPropertyChanged
{
    public ObservableCollection<Expense> Expenses { get; } = new();

    // PropertyChanged plumbing as in earlier lessons...
}

The class that holds a window’s data is often called a view model. You will learn the full pattern in Introduction to MVVM. For now it is just a class we set as the window’s DataContext.

public MainWindow()
{
    InitializeComponent();
    DataContext = new ExpenseListViewModel();
}

The quickest grid: auto generated columns

Point ItemsSource at the collection and you are done:

<DataGrid ItemsSource="{Binding Expenses}" />

By default AutoGenerateColumns is True. The grid looks at the public properties of Expense and makes one column per property. It even picks a sensible column type: a bool becomes a check box column and an enum becomes a combo box column.

This is great for a quick look at your data, but you rarely ship it:

• the headers are the raw property names (Id, Amount)
• money and dates are not formatted
• you cannot choose the order or the width

If you only need small tweaks, the AutoGeneratingColumn event lets you rename or skip a column while it is created:

private void Grid_AutoGeneratingColumn(object sender, DataGridAutoGeneratingColumnEventArgs e)
{
    if (e.PropertyName == "Id")
    {
        e.Cancel = true;          // do not show the Id column
    }
}

For a real screen, define the columns yourself.

Defining your own columns

Set AutoGenerateColumns="False" and list the columns inside DataGrid.Columns:

<DataGrid ItemsSource="{Binding Expenses}"
          AutoGenerateColumns="False">
    <DataGrid.Columns>
        <DataGridTextColumn Header="Title" Binding="{Binding Title}" Width="*" />
        <DataGridTextColumn Header="Category" Binding="{Binding Category}" Width="120" />
        <DataGridTextColumn Header="Date" Binding="{Binding Date, StringFormat=d}" Width="Auto" />
        <DataGridTextColumn Header="Amount" Binding="{Binding Amount, StringFormat=N2}" Width="100" />
    </DataGrid.Columns>
</DataGrid>

Each column has a Header and a Binding. The binding path is relative to one row’s object, so {Binding Title} means “the Title of this expense”.

Column widths

Width accepts the same ideas you met in The Grid Panel:

Giving Title a * width means it soaks up any spare space, so the grid always fills the window.

The built in column types

WPF ships five column types:

A combo box column for the category

CoinJar has five categories: Food, Transport, Bills, Fun and Other. A combo box column stops people typing “fod” by mistake.

There is one catch. Columns are not part of the visual tree (see Logical and Visual Trees), so a column cannot inherit the window’s DataContext. A plain {Binding Categories} on the column’s ItemsSource finds nothing. The simple fix is a resource:

<Window.Resources>
    <x:Array x:Key="Categories" Type="sys:String">
        <sys:String>Food</sys:String>
        <sys:String>Transport</sys:String>
        <sys:String>Bills</sys:String>
        <sys:String>Fun</sys:String>
        <sys:String>Other</sys:String>
    </x:Array>
</Window.Resources>

<DataGridComboBoxColumn Header="Category"
                        ItemsSource="{StaticResource Categories}"
                        SelectedItemBinding="{Binding Category}" />

The sys prefix is declared on the window as xmlns:sys="clr-namespace:System;assembly=mscorlib". Notice the binding property is SelectedItemBinding, not Binding. You will learn much more about resources in Resources and Resource Dictionaries.

Template columns for full control

A DataGridTemplateColumn takes two data templates: one for showing the cell and one for editing it.

<DataGridTemplateColumn Header="Date" Width="130" SortMemberPath="Date">
    <DataGridTemplateColumn.CellTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Date, StringFormat=d}" Margin="4,0" />
        </DataTemplate>
    </DataGridTemplateColumn.CellTemplate>
    <DataGridTemplateColumn.CellEditingTemplate>
        <DataTemplate>
            <DatePicker SelectedDate="{Binding Date}" />
        </DataTemplate>
    </DataGridTemplateColumn.CellEditingTemplate>
</DataGridTemplateColumn>

Now the date shows as text, but turns into a DatePicker when the user edits it. A template column does not know what to sort by, so set SortMemberPath if you want its header to be clickable for sorting.

Formatting money

You might try StringFormat=C on a text column to show the amount as currency. It looks right, but editing breaks: the edit box now contains “$12.50”, and converting that text back to a decimal fails because of the currency symbol. The cell gets a red border and the value is not saved.

A template column solves this neatly. Show the currency in the normal template, and edit the plain number:

<DataGridTemplateColumn Header="Amount" Width="110" SortMemberPath="Amount">
    <DataGridTemplateColumn.CellTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Amount, StringFormat=C}"
                       HorizontalAlignment="Right" Margin="4,0" />
        </DataTemplate>
    </DataGridTemplateColumn.CellTemplate>
    <DataGridTemplateColumn.CellEditingTemplate>
        <DataTemplate>
            <TextBox Text="{Binding Amount, StringFormat=N2}" TextAlignment="Right" />
        </DataTemplate>
    </DataGridTemplateColumn.CellEditingTemplate>
</DataGridTemplateColumn>

The currency symbol comes from the culture that the binding uses. WPF bindings use US English unless you tell them otherwise, which is why you may see “$” on a PC set to another country. The Data Binding Basics lesson showed how to make WPF use the user’s own culture.

Editing, adding and deleting rows

Editing is on by default. Double click a cell (or press F2) to edit, then press Enter or move to another cell to commit. Press Escape to cancel. The new value is written into the Expense object through the binding.

A few properties control what users may do:

<DataGrid IsReadOnly="False"
          CanUserAddRows="True"
          CanUserDeleteRows="True"
          CanUserSortColumns="True"
          CanUserReorderColumns="True"
          CanUserResizeColumns="True" />

• IsReadOnly="True" turns off all editing. You can also set it on a single column.
• CanUserAddRows shows an empty “new item” row at the bottom. Typing in it creates a new Expense. This only works when the class has a public constructor with no parameters.
• CanUserDeleteRows lets the user press Delete to remove the selected rows from the collection.

Because Expenses is an ObservableCollection, the collection you hold in C# changes too. Nothing needs copying back.

Selection

The grid tracks what the user selected. Bind SelectedItem to a property to know which expense is highlighted:

<DataGrid ItemsSource="{Binding Expenses}"
          SelectedItem="{Binding SelectedExpense}"
          SelectionMode="Single"
          SelectionUnit="FullRow" />

• SelectionMode is Single or Extended (the default, which allows Ctrl and Shift clicks).
• SelectionUnit is FullRow, Cell or CellOrRowHeader.
• With Extended, read grid.SelectedItems in code to get every selected row.

SelectedItem binds two way by default, so the view model can also select a row by setting SelectedExpense.

Row details

Row details are an extra area that opens under a row. They are good for information that does not deserve its own column:

<DataGrid RowDetailsVisibilityMode="VisibleWhenSelected">
    <DataGrid.RowDetailsTemplate>
        <DataTemplate>
            <TextBlock Margin="24,4" Foreground="Gray"
                       Text="{Binding Id, StringFormat='Expense #{0}'}" />
        </DataTemplate>
    </DataGrid.RowDetailsTemplate>
</DataGrid>

RowDetailsVisibilityMode can be Collapsed, Visible (every row) or VisibleWhenSelected.

Making the grid easier to read

A handful of properties give a cleaner look without any styling knowledge:

<DataGrid AlternatingRowBackground="#F5F7FA"
          GridLinesVisibility="Horizontal"
          HeadersVisibility="Column"
          RowHeight="28"
          FrozenColumnCount="1" />

• AlternatingRowBackground stripes every second row.
• GridLinesVisibility is All, Horizontal, Vertical or None.
• HeadersVisibility="Column" hides the grey row header strip on the left.
• FrozenColumnCount="1" keeps the first column visible while scrolling sideways.

For deeper changes, such as coloured rows, you will use RowStyle and CellStyle in Styles and Setters and Triggers.

Keeping a total in sync

CoinJar shows a total under the grid. It must update when a row is added, removed or edited. ObservableCollection only tells you about adds and removes, so we also listen to each expense’s PropertyChanged event (a C# event):

public ExpenseListViewModel()
{
    Expenses.CollectionChanged += (s, e) =>
    {
        if (e.NewItems != null)
            foreach (Expense x in e.NewItems) x.PropertyChanged += Expense_PropertyChanged;
        if (e.OldItems != null)
            foreach (Expense x in e.OldItems) x.PropertyChanged -= Expense_PropertyChanged;
        OnPropertyChanged(nameof(Total));
    };
}

private void Expense_PropertyChanged(object? sender, PropertyChangedEventArgs e)
{
    if (e.PropertyName == nameof(Expense.Amount))
        OnPropertyChanged(nameof(Total));
}

public decimal Total => Expenses.Sum(x => x.Amount);

Total is a calculated property using LINQ. We just announce “Total changed” whenever something that affects it changes, and the bound TextBlock asks for the new value.

Common mistakes

• Columns appear twice. You defined columns but forgot AutoGenerateColumns="False", so you get yours plus the generated ones.
• The combo box column is empty. Its ItemsSource used a normal {Binding}. Columns have no DataContext, so use a StaticResource.
• Edits do not stick on a currency column. StringFormat=C cannot be converted back. Use a template column or N2 for editing.
• No “new row” appears. The item class has no parameterless constructor, or the grid or column is read only.
• The total does not change after editing. You only listened to CollectionChanged. Item edits raise PropertyChanged on the item, not on the collection.
• Slow with thousands of rows. Do not put the grid inside a StackPanel or ScrollViewer. It then gets infinite height and turns off virtualization. Give it a Grid row with * height instead. More on this in Performance and Virtualization.

Quick recap

• A DataGrid shows a collection as rows and columns, with sorting, resizing, editing and selection built in.
• Turn off AutoGenerateColumns and define columns yourself for real screens.
• Use text, check box, combo box, hyperlink and template columns. Template columns have a CellTemplate and a CellEditingTemplate.
• Columns are not in the visual tree, so give a combo box column its list from a resource.
• Avoid StringFormat=C on editable cells. Show currency, edit the plain number.
• CanUserAddRows, CanUserDeleteRows and IsReadOnly control editing. SelectedItem tells you the current row.
• Listen to each item’s PropertyChanged to keep calculated values such as a total up to date.