.NET 4.0+

WPF Control Templates - ItemsPresenter

by Richard Carr, published at http://www.blackwasp.co.uk/WPFItemsPresenter.aspx

The one hundred and sixty-third part of the Windows Presentation Foundation Fundamentals tutorial continues to describe control template creation. This article explains how the items of an ItemsControl can be incorporated into a template.

ItemsPresenter

In the last article in the WPF tutorial we saw how to add a ContentPresenter to a control template to act as a placeholder for the content of a ContentControl. This is important because the content of a control can be of many different types. With the ContentPresenter, we can ignore the type and allow the framework to render the content.

A similar problem exists with templates for controls that inherit from ItemsControl. This class includes a collection of objects in the Items property. These items are rendered according to a data template but we need to be able to specify the container for the output items. You can do so using an ItemsPresenter.

As with ContentPresenter, ItemsPresenter inherits functionality from the FrameworkElement class. However, you do not have to set any specific properties if you just want to use it as a simple placeholder for the items.

To demonstrate the creation of a control template for an ItemsControl we need a sample project. Create a new WPF application in Visual Studio named, "ItemsPresenterDemo". Once the environment is prepared, replace the XAML in the main window with the following code:

<Window x:Class="ItemsPresenterDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:sys="clr-namespace:System;assembly=mscorlib"
        Title="ItemsPresenter Demo" Height="250" Width="350">

    <ItemsControl Margin="20">
        <sys:String>The Frog King</sys:String>
        <sys:String>Cat and Mouse in Partnership</sys:String>
        <sys:String>Mary's Child</sys:String>
        <sys:String>The Wolf and the Seven Young Kids</sys:String>
        <sys:String>Trusty John</sys:String>
        <sys:String>The Good Bargain</sys:String>
    </ItemsControl>
</Window>

The XAML creates a window containing an ItemsControl with six strings in its Items collection. Run the program to see the results.

Adding an ItemsControl Template

Let's add a control template to replace the one used by the ItemsControl. Add the following resources section to the window:

<Window.Resources>
    <ControlTemplate x:Key="MyItemsTemplate" TargetType="ItemsControl">
        <Grid>
            <Border Background="Bisque" CornerRadius="10" Margin="15 15 0 0" />
            <Border Background="White" CornerRadius="10" Margin="0 0 15 15"
                    BorderBrush="Black" BorderThickness="3">
                <ItemsPresenter Margin="10" />
            </Border>
        </Grid>
    </ControlTemplate>
</Window.Resources>

The template includes two Borders with slightly different margins and different background colours. This is to give the impression of a border with a shadow. The second border, which will be in front of the first, holds the ItemsPresenter that is the placeholder for the collection of items. In this case, a margin of ten device-independent units around the ItemsPresenter will separate the items from the border's edge.

Apply the control template to the ItemsControl by updating its XAML, as follows:

<ItemsControl Margin="20" Template="{StaticResource MyItemsTemplate}">

Run the program to see the template applied to the ItemsControl.