Todd's World: WPF DataGrid Design-time Walkthrough

WPF DataGrid Design-time Walkthrough

The DataGrid walkthrough on windowsclient.net/wpf and the Tips & Tricks section on codeplex talk briefly about the Design-time support for DataGrid. I thought I’d expand on that just a little more so you get a good idea of what you have available.

Installation

So to get it to work you need to install the toolkit using the WPFToolkit.msi (download from here). This will put the dlls under your “C:\Program Files\WPF Toolkit\<version number>\” directory as well as set a reg key in Visual Studio to recognize the controls in the toolbox. In your application, you will need to reference the wpftoolkit.dll from this install directory location to get the design-time support to work.

Walkthrough

Ok, I’ll start from the very beginning.

0. Install and set a reference to wpftoolkit.dll

1. Open the Toolbox. You should see a group with DataGrid, DatePicker, and Calendar.

a. If you don’t, you can add them by right-clicking in the Toolbox, selecting “Choose Toolbox Items”, tab to the WPF Components tab, then selecting DataGrid, DatePicker, and Calendar.

2. Drag & drop support: Drag the DataGrid item from the Toolbox to the window on the design surface.

a. Note: You may need to resize the window as well as work with the layout so the DataGrid fits as you would like.

3. Setup the ItemsSource for the DataGrid

a. In my example I’m going to use a DataTable that retrieves the Customers Table from the Northwind database. The code for that is in the sample on this post.

<Window.Resources>

<ObjectDataProvider x:Key="CustomerDataProvider"

ObjectType="{x:Type local:Customers}"

MethodName="GetCustomers" />

</Window.Resources>

<Grid>

<my:DataGrid Name="dataGrid1"

ItemsSource="{Binding Source={StaticResource CustomerDataProvider}}" />

</Grid>

b. As soon as the ItemsSource is set, the design surface should update to show you the data on the DataGrid. This is because DataGrid.AutoGenerateColumns is set to true by default.

4. Properties View grouping support: Now, click on the DataGrid in the design window and open the Properties View. Set the grouping to “Categorized”. You will find some groups that are specific to DataGrid such as the Columns group, GridLines group, Headers group, and Rows group.

a. In my example, from the Properties View I set EnableColumnVirtualization to true and AlternationRowBackground to LightGray

5. Now, right-click on the DataGrid in design view. You should see a DataGrid menu item with additional sub-items. The sub-items will be a little different depending if you have an ItemsSource set or not. Here is what it looks like with an ItemsSource set but no columns explicitly added:

When no ItemsSource is set, some sub-items will not appear. When explicit columns are set on the DataGrid, additional sub-items will be added. Now, let’s try out each of the options.

6. Generating columns all at once: Right-click on the DataGrid in design view. Select the DataGrid menu item, then select the “Generate Columns” sub-menu item. What just happened?

a. That may be a little confusing at first since the design view didn’t change. The design-time sets DataGrid.AutoGenerateColumns to false, then generates a list of columns with a one-to-one mapping of the data source’s properties and adds them to the columns collection in the xaml. Here is what my DataGrid looks like now in the xaml:

<my:DataGrid Name="dataGrid1" ItemsSource="{Binding Source={StaticResource CustomerDataProvider}}" EnableColumnVirtualization="True" AlternatingRowBackground="LightGray" AutoGenerateColumns="False">

<my:DataGrid.Columns>

<my:DataGridTextColumn Binding="{Binding Path=CustomerID}" Header="CustomerID" />

<my:DataGridTextColumn Binding="{Binding Path=CompanyName}" Header="CompanyName" />

<my:DataGridTextColumn Binding="{Binding Path=ContactName}" Header="ContactName" />

<my:DataGridTextColumn Binding="{Binding Path=ContactTitle}" Header="ContactTitle" />

<my:DataGridTextColumn Binding="{Binding Path=Address}" Header="Address" />

<my:DataGridTextColumn Binding="{Binding Path=City}" Header="City" />

<my:DataGridTextColumn Binding="{Binding Path=Region}" Header="Region" />

<my:DataGridTextColumn Binding="{Binding Path=PostalCode}" Header="PostalCode" />

<my:DataGridTextColumn Binding="{Binding Path=Country}" Header="Country" />

<my:DataGridTextColumn Binding="{Binding Path=Phone}" Header="Phone" />

<my:DataGridTextColumn Binding="{Binding Path=Fax}" Header="Fax" />

</my:DataGrid.Columns>

</my:DataGrid>

7. Removing all columns: Now that I have explicit columns set, if I wanted to clear them I can right-click on the DataGrid in design view, select DataGrid -> Remove Columns. This will remove all the columns from xaml but it will not change the AutoGenerateColumns property back to true.

8. Creating a column with the Add/Edit Columns editor: With all columns removed now, select DataGrid -> Add/Edit Columns… You should be presented with a column editor where the data sources properties are mapped on the left panel. The middle area is where you can choose the type of DataGridColumn to create and the right panel shows the columns that will be created.

a. Leave Type as Default and press the Add All button. You should see all the properties on the left panel moved to the right panel and mapped to columns. The default column is DataGridTextColumn.

b. Now, press the “Edit…” button on the first column in the right panel. An “Edit Column” editor should pop up with a list of common properties to set on the column.

c. Edit any of the fields of the columns you created and press ok on the “Add/Edit Columns” editor. The xaml should be updated with the set of columns you’ve created.

Summary

To recap, the cider design-time supports toolbox drag and drop, generating all columns, generating specific columns, editing columns, and removing columns. Remember that you have to set the ItemsSource on the DataGrid declaratively in order to get that functionality. The Properties View has also been updated for the DataGrid to support grouping of specific properties on the DataGrid. Please try it out and any feedback would be greatly appreciated.

Other Design-time Resources

Karl Shifflett has created this awesome tool called XAML Power Toys. Included in the tool is a utility for creating and customizing a WPF DataGrid. Check out the video walkthrough of it here.