Click to Rate and Give Feedback
MSDN
MSDN Library
Web Development
Silverlight 3
DataGrid Class
Collapse All/Expand All Collapse All
This page is specific to
Microsoft Silverlight 3

Other versions are also available for the following:
.NET Framework Class Library for Silverlight
DataGrid Class

Displays data in a customizable grid.

Namespace:  System.Windows.Controls
Assembly:  System.Windows.Controls.Data (in System.Windows.Controls.Data.dll)
Visual Basic (Declaration)
<TemplatePartAttribute(Name := "ColumnHeadersPresenter", Type := GetType(DataGridColumnHeadersPresenter))> _
<StyleTypedPropertyAttribute(Property := "ColumnHeaderStyle", StyleTargetType := GetType(DataGridColumnHeader))> _
<StyleTypedPropertyAttribute(Property := "CellStyle", StyleTargetType := GetType(DataGridCell))> _
<TemplatePartAttribute(Name := "FrozenColumnScrollBarSpacer", Type := GetType(FrameworkElement))> _
<TemplatePartAttribute(Name := "HorizontalScrollbar", Type := GetType(ScrollBar))> _
<TemplatePartAttribute(Name := "ValidationSummary", Type := GetType(ValidationSummary))> _
<TemplatePartAttribute(Name := "VerticalScrollbar", Type := GetType(ScrollBar))> _
<TemplateVisualStateAttribute(Name := "Disabled", GroupName := "CommonStates")> _
<TemplateVisualStateAttribute(Name := "Normal", GroupName := "CommonStates")> _
<TemplateVisualStateAttribute(Name := "Invalid", GroupName := "ValidationStates")> _
<TemplateVisualStateAttribute(Name := "Valid", GroupName := "ValidationStates")> _
<StyleTypedPropertyAttribute(Property := "RowStyle", StyleTargetType := GetType(DataGridRow))> _
<StyleTypedPropertyAttribute(Property := "RowHeaderStyle", StyleTargetType := GetType(DataGridRowHeader))> _
<StyleTypedPropertyAttribute(Property := "DragIndicatorStyle", StyleTargetType := GetType(ContentControl))> _
<StyleTypedPropertyAttribute(Property := "DropLocationIndicatorStyle", StyleTargetType := GetType(ContentControl))> _
<TemplatePartAttribute(Name := "RowsPresenter", Type := GetType(DataGridRowsPresenter))> _
Public Class DataGrid _
    Inherits Control
Visual Basic (Usage)
Dim instance As DataGrid
C#
[TemplatePartAttribute(Name = "ColumnHeadersPresenter", Type = typeof(DataGridColumnHeadersPresenter))]
[StyleTypedPropertyAttribute(Property = "ColumnHeaderStyle", StyleTargetType = typeof(DataGridColumnHeader))]
[StyleTypedPropertyAttribute(Property = "CellStyle", StyleTargetType = typeof(DataGridCell))]
[TemplatePartAttribute(Name = "FrozenColumnScrollBarSpacer", Type = typeof(FrameworkElement))]
[TemplatePartAttribute(Name = "HorizontalScrollbar", Type = typeof(ScrollBar))]
[TemplatePartAttribute(Name = "ValidationSummary", Type = typeof(ValidationSummary))]
[TemplatePartAttribute(Name = "VerticalScrollbar", Type = typeof(ScrollBar))]
[TemplateVisualStateAttribute(Name = "Disabled", GroupName = "CommonStates")]
[TemplateVisualStateAttribute(Name = "Normal", GroupName = "CommonStates")]
[TemplateVisualStateAttribute(Name = "Invalid", GroupName = "ValidationStates")]
[TemplateVisualStateAttribute(Name = "Valid", GroupName = "ValidationStates")]
[StyleTypedPropertyAttribute(Property = "RowStyle", StyleTargetType = typeof(DataGridRow))]
[StyleTypedPropertyAttribute(Property = "RowHeaderStyle", StyleTargetType = typeof(DataGridRowHeader))]
[StyleTypedPropertyAttribute(Property = "DragIndicatorStyle", StyleTargetType = typeof(ContentControl))]
[StyleTypedPropertyAttribute(Property = "DropLocationIndicatorStyle", StyleTargetType = typeof(ContentControl))]
[TemplatePartAttribute(Name = "RowsPresenter", Type = typeof(DataGridRowsPresenter))]
public class DataGrid : Control
XAML Object Element Usage
<data:DataGrid .../>

XAML Values

data:

A prefix that is defined to map the XML namespace for the System.Windows.Controls.Data assembly and the System.Windows.Controls CLR namespace.

The DataGrid control provides a flexible way to display a collection of data in rows and columns. The built-in column types include a text box column, a check box column, and a template column for hosting custom content. The built-in row type includes a drop-down details section that you can use to display additional content below the cell values.

The following illustration shows an example of a DataGrid.

DataGrid control example

For information about adding and referencing a DataGrid control, see How to: Add a DataGrid Control to a Page.

NoteNote:

The DataGrid control is available as part of the libraries in the Silverlight Software Development Kit (SDK). For more information, see the Silverlight Tools.

Binding to Data

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 INotifyCollectionChanged, such as an ObservableCollection<(Of <(T>)>). In order to automatically reflect property changes, the objects in the source collection must implement the INotifyPropertyChanged interface.

Columns

By default, the DataGrid control generates columns automatically when you set the ItemsSource property. The generated columns are of type DataGridCheckBoxColumn for bound Boolean (and nullable Boolean) properties, and of type DataGridTextColumn for all other properties. If a property does not have a String or numeric value type, the generated text box columns are read-only and display the data object's ToString value.

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. Alternatively, you can let the data grid generate columns, but handle the AutoGeneratingColumn event to customize columns after creation. To rearrange the display order of the columns, you can set the DisplayIndex property for individual columns. For more information, see How to: Customize Auto-Generated Columns in the DataGrid Control.

Generated columns recognize the DisplayAttribute if it is present on the source object. The DisplayAttribute..::.ShortName property is used to specify column header text. The DisplayAttribute..::.Order property is used to specify the order in which columns appear. The DisplayAttribute..::.AutoGenerateField property is used to specify whether the field has a column generated for it. For more information, see Using Data Annotations to Customize Data Classes.

Regardless of whether you generate columns, you can use the DataGrid..::.Columns collection to programmatically add, insert, remove, and change any columns in the control at run time. Alternatively, you can specify columns in XAML, in which case you should set AutoGenerateColumns to false. Creating your own columns enables you to use additional column types, such as the DataGridTemplateColumn type or custom column types. The DataGridTemplateColumn type provides an easy way to create a simple custom column. The CellTemplate and CellEditingTemplate properties enable you to specify content templates for both display and editing modes.

Grouping, Sorting, and Filtering

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 data is grouped in the DataGrid, you can customize the appearance of the row group headers with the RowGroupHeaderStyles property. Groups can be expanded and collapsed manually, or programmatically with the ExpandRowGroup and CollapseRowGroup methods. For more information, see How to: Group, Sort, and Filter Data in the DataGrid Control.

Editing

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.

A cell level edit is committed when you move to another cell in the same row. All edits in a row are committed when you press ENTER or move to another row. 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 CommitEdit and CancelEdit methods. For more information about edit related events, see BeginningEdit, PreparingCellForEdit, CellEditEnding, CellEditEnded, RowEditEnding, and RowEditEnded.

Validation

The DataGrid supports cell-level property validation and row-level object validation. If a validation exception is encountered in the property setter, the cell editing control displays its error state. The DataGridCell..::.IsValid, DataGridRow..::.IsValid, and DataGrid..::.IsValid properties are all set to false. The DataGrid will not exit cell editing mode until the validation error is resolved.

When the row edit is committed, each cell is validated again. In addition, if the object that the row is bound to has a ValidationAttribute, validation is performed on the object. If object validation errors are found, the DataGridRow..::.IsValid, and DataGrid..::.IsValid properties are set to false The DataGrid has a built-in ValidationSummary where row-level errors are displayed. The DataGrid will not exit row editing mode until the validation errors are resolved. In order for validation to work correctly, each DataGridBoundColumn..::.Binding must have its ValidatesOnExceptions and NotifyOnValidationError properties set to true, and its UpdateSourceTrigger set to Explicit.

Paging

To page data in the DataGrid, you bind the DataGrid to an IPagedCollectionView implementation that supports paging operations. You can use a DataGrid with a DataPager control and a data source wrapped in the PagedCollectionView class to easily add paging to your DataGrid.

Customizing the DataGrid Control

The DataGrid control supports common table formatting options, such as alternating row backgrounds and the ability to show or hide headers, grid lines, 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 further customize rows. For more information, see Walkthrough: Customizing the DataGrid Control Using Properties.

To apply the same property settings to multiple DataGrid controls, use the Style property. To change the visual structure and visual behavior of a DataGrid, copy and modify its default style and template. For more information, see Control Customization.

If a dependency property for a DataGrid is set by its default style, the property might change from its default value when the DataGrid appears in the application. For more information, see Dependency Property Value Precedence. You can get the default style and template for DataGrid from DataGrid Styles and Templates.

NoteNote:

Setting a visual property will only have an effect if that property is both present in 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 of Customizing the Appearance of an Existing Control by Using a ControlTemplate.

The following code example creates a page with several DataGrid controls configured in a variety of ways.

Run this sample

XAML
<UserControl x:Class="DataGridSnippets.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"     
    xmlns:data="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data">
    <ScrollViewer VerticalScrollBarVisibility="Auto" BorderThickness="0" Padding="0">
    <StackPanel Margin="10,10,10,10">

        <TextBlock Text="DataGrid with autogenerated columns:"/>
        <data:DataGrid x:Name="dataGrid1" 
            Height="140" Margin="0,5,0,10"
            AutoGenerateColumns="True" />            

        <TextBlock Text="DataGrid with row details sections:"/>
        <data:DataGrid x:Name="dataGrid3" 
            Height="140" Margin="0,5,0,10"
            RowDetailsVisibilityMode="VisibleWhenSelected" >            
            <data:DataGrid.RowDetailsTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Horizontal">
                        <TextBlock FontSize="12" Text="Address: " />
                        <TextBlock FontSize="12" Text="{Binding Address}"/>
                    </StackPanel>
                </DataTemplate>
            </data:DataGrid.RowDetailsTemplate>                
        </data:DataGrid>

        <TextBlock Text="DataGrid with configured columns:"/>
        <data:DataGrid x:Name="dataGrid4" 
            Height="160" Margin="0,5,0,10" 
            RowHeight="40" AutoGenerateColumns="False" >    
            <data:DataGrid.Columns>
                <data:DataGridTextColumn 
                    Header="First Name" 
                    Width="SizeToHeader"
                    Binding="{Binding FirstName}" 
                    FontSize="20" />
                <data:DataGridTextColumn 
                    Header="Last Name" 
                    Width="SizeToCells"
                    Binding="{Binding LastName}" 
                    FontSize="20" />
                <data:DataGridTextColumn 
                    Header="Address"
                    Width="150"
                    Binding="{Binding Address}" >
                    <data:DataGridTextColumn.ElementStyle>
                        <Style TargetType="TextBlock">
                            <Setter Property="TextWrapping" Value="Wrap"/>
                        </Style>
                    </data:DataGridTextColumn.ElementStyle>
                    <data:DataGridTextColumn.EditingElementStyle>
                        <Style TargetType="TextBox">
                            <Setter Property="Foreground" Value="Blue"/>
                        </Style>
                    </data:DataGridTextColumn.EditingElementStyle>
                </data:DataGridTextColumn>
                <data:DataGridCheckBoxColumn 
                    Header="New?" 
                    Width="40"
                    Binding="{Binding IsNew}" />
                <data:DataGridCheckBoxColumn 
                    Header="Subscribed?" 
                    Width="Auto"
                    Binding="{Binding IsSubscribed}" 
                    IsThreeState="True" />
            </data:DataGrid.Columns>
        </data:DataGrid>

        <TextBlock Text="DataGrid with template column and custom alternating row backgrounds:"/>
        <data:DataGrid x:Name="dataGrid5" 
            Height="125" Margin="0,5,0,10"
            AutoGenerateColumns="False"
            RowBackground="Azure"
            AlternatingRowBackground="LightSteelBlue">
            <data:DataGrid.Columns>
                <!-- Name Column -->
                <data:DataGridTemplateColumn Header="Name">
                    <data:DataGridTemplateColumn.CellTemplate>
                        <DataTemplate>
                            <StackPanel Orientation="Horizontal" VerticalAlignment="Center">
                                <TextBlock Padding="5,0,5,0"
                                    Text="{Binding FirstName}"/>
                                <TextBlock Text="{Binding LastName}"/>
                            </StackPanel>
                        </DataTemplate>
                    </data:DataGridTemplateColumn.CellTemplate> 
                    <data:DataGridTemplateColumn.CellEditingTemplate>
                        <DataTemplate>
                            <StackPanel Orientation="Horizontal">
                                <TextBox Text="{Binding FirstName}" BorderThickness="0"/>
                                <TextBox Text="{Binding LastName}" BorderThickness="0"/>
                            </StackPanel>
                        </DataTemplate>
                    </data:DataGridTemplateColumn.CellEditingTemplate> 
                </data:DataGridTemplateColumn>              
                <!-- Address Column -->
                <data:DataGridTextColumn
                    Header="Address" Width="300"
                    Binding="{Binding Address}" />
            </data:DataGrid.Columns>
        </data:DataGrid>
    </StackPanel>
    </ScrollViewer>
</UserControl>
Visual Basic
Partial Public Class Page
    Inherits UserControl

    Public Sub New()
        InitializeComponent()

        dataGrid1.ItemsSource = Customer.GetSampleCustomerList()
        dataGrid3.ItemsSource = Customer.GetSampleCustomerList()
        dataGrid4.ItemsSource = Customer.GetSampleCustomerList()
        dataGrid5.ItemsSource = Customer.GetSampleCustomerList()
    End Sub

End Class

Public Class Customer
    Dim m_FirstName As String
    Dim m_LastName As String
    Dim m_Address As String
    Dim m_IsNew As Boolean
    Dim m_IsSubscribed As Boolean?

    Public Sub New(ByVal firstName As String, ByVal lastName As String, ByVal address As String, ByVal isNew As Boolean, ByVal isSubscribed As Boolean?)
        Me.FirstName = firstName
        Me.LastName = lastName
        Me.Address = address
        Me.IsNew = isNew
        Me.IsSubscribed = isSubscribed
    End Sub

    Property FirstName() As String
        Get
            Return m_FirstName
        End Get
        Set(ByVal value As String)
            m_FirstName = value
        End Set
    End Property

    Property LastName() As String
        Get
            Return m_LastName
        End Get
        Set(ByVal value As String)
            m_LastName = value
        End Set
    End Property

    Property Address() As String
        Get
            Return m_Address
        End Get
        Set(ByVal value As String)
            m_Address = value
        End Set
    End Property

    Property IsNew() As Boolean
        Get
            Return m_IsNew
        End Get
        Set(ByVal value As Boolean)
            m_IsNew = value
        End Set
    End Property

    Property IsSubscribed() As Boolean?
        Get
            Return m_IsSubscribed
        End Get
        Set(ByVal value As Boolean?)
            m_IsSubscribed = value
        End Set
    End Property

    Public Shared Function GetSampleCustomerList() As List(Of Customer)
        Return New List(Of Customer)(New Customer() _
               {New Customer("A.", "Zero", "12 North Third Street, Apartment 45", False, True), _
                New Customer("B.", "One", "34 West Fifth Street, Apartment 67", False, False), _
                New Customer("C.", "Two", "56 East Seventh Street, Apartment 89", True, Nothing), _
                New Customer("D.", "Three", "78 South Ninth Street, Apartment 10", True, True)})
    End Function
End Class
C#
using System;
using System.Collections.Generic;
using System.Windows.Controls;

namespace DataGridSnippets
{
    public partial class Page : UserControl
    {
        public Page()
        {
            InitializeComponent();

            // Set the ItemsSource to autogenerate the columns.
            dataGrid1.ItemsSource = Customer.GetSampleCustomerList();
            dataGrid3.ItemsSource = Customer.GetSampleCustomerList();
            dataGrid4.ItemsSource = Customer.GetSampleCustomerList();
            dataGrid5.ItemsSource = Customer.GetSampleCustomerList();
        }
    }

    public class Customer
    {
        public String FirstName { get; set; }
        public String LastName { get; set; }
        public String Address { get; set; }
        public Boolean IsNew { get; set; }

        // A null value for IsSubscribed can indicate 
        // "no preference" or "no response".
        public Boolean? IsSubscribed { get; set; }

        public Customer(String firstName, String lastName, 
            String address, Boolean isNew, Boolean? isSubscribed)
        {
            this.FirstName = firstName;
            this.LastName = lastName;
            this.Address = address;
            this.IsNew = isNew; 
            this.IsSubscribed = isSubscribed;
        }

        public static List<Customer> GetSampleCustomerList()
        {
            return new List<Customer>(new Customer[4] {
                new Customer("A.", "Zero", 
                    "12 North Third Street, Apartment 45", 
                    false, true), 
                new Customer("B.", "One", 
                    "34 West Fifth Street, Apartment 67", 
                    false, false),
                new Customer("C.", "Two", 
                    "56 East Seventh Street, Apartment 89", 
                    true, null),
                new Customer("D.", "Three", 
                    "78 South Ninth Street, Apartment 10", 
                    true, true)
            });
        }
    }
}
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Processing
© 2009 Microsoft Corporation. All rights reserved. Terms of Use | Trademarks | Privacy Statement | Site Feedback
Page view tracker