Reusability and factorizing are maybe the most commons things you want and use when you are developing applications. In WPF it often means creating controls library (i don’t mean UserControl) that will be easy to use in multiple applications.
In this post we'll see all the step to create a control library useable in differents projects.
The example to illustrate the theory will be to create an headered control.
PS: note that it already exists in the framework under the nice name of GroupBox.
Creating a control library
Foundation of the project
The first step is to use the VS2010 Wizard named "WPF Custom control library" to create the library which will contain the controls. We will name it, by excess of modesty : “AmazingsWPFControls” !
As you can see, VS has created some files and directory for us :
Let’s take them one by one ! The “Themes\generic.xaml” file is where the WPF engine, when it loads your control, looks for it’s theme aka. a style setting a template. Here is its content :
<Style TargetType="{x:Type local:CustomControl1}">
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="{x:Type local:CustomControl1}">
<Border Background="{TemplateBinding Background}"
BorderBrush="{TemplateBinding BorderBrush}"
BorderThickness="{TemplateBinding BorderThickness}">
</Border>
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
The “AssemblyInfo.cs” file which contains a specific attribute :" ThemeInfo”. It tells the framework where to look for the theme files. Usually it is used like this :
[assembly: ThemeInfo( ResourceDictionaryLocation.None,
//where theme specific resource dictionaries are located //(used if a resource is not found in the page, // or application resource dictionaries) ResourceDictionaryLocation.SourceAssembly
//where the generic resource dictionary is located //(used if a resource is not found in the page, // app, or any theme specific resource dictionaries) )]
The “CustomControl1.cs” which is an empty custom control the wizard created for you(how kind of him). Its content is interesting because it show you that you have to override the MetaData of the newly created control to force the WPF engine using the style defined in the generic.xaml file.
public class CustomControl1 : Control { static CustomControl1() { DefaultStyleKeyProperty.OverrideMetadata(typeof(CustomControl1), new FrameworkPropertyMetadata(typeof(CustomControl1))); } }
Each time you want to add a new custom control to the library, you will have to reproduce each of these steps. Of course, the wizard to add a new Custom Control can do it for you but its always a good thing to know how it works. In our case we’ve to rename CustomControl1 to HeaderedControl.
Here we are with the foundation of the library. Now we are going to add a template and behaviors to the control.
Choose the more appropriated base class
By default the wizard make the control a inherit from the Control class but there are differents options that you may consider for base class :
- Control : This is a base class which lets you the most freedom but the most to do !
- ContentControl : This is a good choice if the control will be used to represent a single piece of content.
- HeaderedContentControl : This is a good choice to represent a single element with an header.
- ItemsControl: This is a good choice if the control will be used to represent a list of items.
In our case the best choice should be to inherit from HeaderedContentControl but we will prefer the ContentControl for demonstration purpose. Note that it meets the specifications: we will represent a single element with an header.
Adding a Template and some behaviors to the control
Setting the template of the control
Unlike UserControl there is no code-behind and you set the template of the control by creating a style in the generic.xaml file. This also means that it’s not possible to access the elements via their names because the control and its representation are linked together only at runtime. But don’t worry, you can still access the differents parts following the steps described in this post.
One of the best practice is to name the revelants parts of your control prefixed with “PART”. By revelants parts, I mean the elements which together build the behavior of your control : for example the track of the slider control is named “PART_Track”. This best practice make your control re-templatable by designer which will know that the controls prefixed by “PART_” are mandatory in the new template they are building. Finally, the parts are declared in the control class via an attribute “TemplatePart” defining the name and the aimed type of control. So in our example, we’ll add a part named “PART_Header which will be the header :
/// <summary>
/// A control displaying an header at the top of its content.
/// </summary>
[TemplatePart(Name = "PART_Header", Type = typeof(Border))]
public class HeaderedControl : Control
{
// ...
}
Adding a content to the control
To add and display a content two things are needed : a property containing the content and a place in the template to display it. The content can be of any type of your choice and is usually placed in the Content property for ContentControl and the Items property for ItemsControl. This is the default behavior but you can override it and tell which property is the content by using the ContentPropertyAttribute on the control’s class :
[ContentPropertyAttribute("Content")] public class HeaderedControl : ContentControl { // ... }
Then, in the template, you define where the content is displayed using a ContentPresenter that you can place where you wants depending of the need. We also use a TemplateBinding to bind the content of the class to the ContentPresenter. In our case we add the content under the header :
<Style TargetType="{x:Type local:HeaderedControl}">
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="{x:Type local:HeaderedControl}">
<DockPanel>
<Border x:Name="PART_Header" DockPanel.Dock="Top" Background="{TemplateBinding Background}"
BorderBrush="{TemplateBinding BorderBrush}"
BorderThickness="{TemplateBinding BorderThickness}" />
<ContentPresenter Content="{TemplateBinding Content}" />
</DockPanel>
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
Adding a bindable property to the control
Adding a property to your control is quite useful if you want to permit some customization of its behavior. This is something very common that you use often without noticing it : every attribute you set in the XAML is simply a property of the controls you use.
In our case there is a lot which are already here because of our inheritance of FrameworkElement. But let’s said that we want to add another one all we have to do is do declare a new dependency property and its accessor as in the code behind. In our case we add two property : the header (of type Object) and the position of the header in the control. So we have this class :
public class HeaderedControl : ContentControl
{
static HeaderedControl()
{
DefaultStyleKeyProperty.OverrideMetadata(typeof(HeaderedControl),
new FrameworkPropertyMetadata(typeof(HeaderedControl)));
}
#region Header
/// <summary>
/// Header Dependency Property
/// </summary>
public static readonly DependencyProperty HeaderProperty =
DependencyProperty.Register("Header", typeof(object), typeof(HeaderedControl),
new FrameworkPropertyMetadata((object)null));
/// <summary>
/// Gets or sets the Header property. This dependency property
/// indicates the header to display.
/// </summary>
public object Header
{
get { return (object)GetValue(HeaderProperty); }
set { SetValue(HeaderProperty, value); }
}
#endregion
#region HeaderPosition
/// <summary>
/// HeaderPosition Dependency Property
/// </summary>
public static readonly DependencyProperty HeaderPositionProperty =
DependencyProperty.Register("HeaderPosition", typeof(HeaderPosition), typeof(HeaderedControl),
new FrameworkPropertyMetadata(HeaderPosition.Top));
/// <summary>
/// Gets or sets the HeaderPosition property. This dependency property
/// indicates ....
/// </summary>
public HeaderPosition HeaderPosition
{
get { return (HeaderPosition)GetValue(HeaderPositionProperty); }
set { SetValue(HeaderPositionProperty, value); }
}
#endregion
/// <summary>
/// Defines where to place the header
/// </summary>
public enum HeaderPosition : int
{
/// <summary>
/// The header is positioned on the left.
/// </summary>
Left = 0,
/// <summary>
/// The header is positioned at the top.
/// </summary>
Top = 1,
/// <summary>
/// The header is positioned on the right.
/// </summary>
Right = 2,
/// <summary>
/// The header is positioned at the bottom.
/// </summary>
Bottom = 3,
}
}
Now let’s use these properties in the template to show and place the header at the right position. We will add another content presenter to display the header and we’ll use a converter to convert the header position into the correct DockPanel.Dock value (only the revelant XAML is showed) :
<ControlTemplate TargetType="{x:Type local:HeaderedControl}">
<Border Background="{TemplateBinding Background}"
BorderBrush="{TemplateBinding BorderBrush}"
BorderThickness="{TemplateBinding BorderThickness}">
<DockPanel>
<Border x:Name="PART_Header"
DockPanel.Dock="{Binding PositionOfTheHeader,
RelativeSource={RelativeSource Mode=TemplatedParent},
Converter={conv:HeaderPositionToDockPositionConverter}}">
<ContentPresenter Content="{TemplateBinding Header}" />
</Border>
<ContentPresenter Content="{TemplateBinding Content}" />
</DockPanel>
</Border>
</ControlTemplate>
Adding a custom command to the control
Adding a command to our control is not as straightforward as I thought before to try 
but here is the guideline is used to make it work fine :
- Create the RoutedCommand of your choice in the control class,
- Create a private method which will be called when the command is executed,
- Register a Class Command binding of this command in the static constructor of the control (you can think of it as a static command binding which will be called each time the command is executed),
- In the handler of the class command binding gets the sender of the command, cast it to your class and call the private method you created just before.
In our case there no really need of a command but lets say that we will add a command which sets the position of the header property to the “Top” value we will results with this code (against only the revelant part):
static HeaderedControl()
{
DefaultStyleKeyProperty.OverrideMetadata(typeof(HeaderedControl),
new FrameworkPropertyMetadata(typeof(HeaderedControl)));
//Instanciate the command
MoveHeaderToTopCommand = new RoutedUICommand("MoveHeaderToTop",
"MoveHeaderToTop", typeof(HeaderedControl));
//Create the command binding
CommandBinding moveHeaderToTopCommandBinding =
new CommandBinding(MoveHeaderToTopCommand,
MoveHeaderToTopCommand_Executed,
MoveHeaderToTopCommand_CanExecute);
CommandManager.
RegisterClassCommandBinding(typeof(HeaderedControl),
moveHeaderToTopCommandBinding);
}
static void MoveHeaderToTopCommand_Executed(
object sender, ExecutedRoutedEventArgs e)
{
HeaderedControl headeredControl =
sender as HeaderedControl;
if (headeredControl != null)
headeredControl.moveHeaderToTop();
}
static void MoveHeaderToTopCommand_CanExecute(object sender,
CanExecuteRoutedEventArgs e)
{
e.CanExecute = true;
}
private void moveHeaderToTop()
{
this.PositionOfTheHeader = HeaderPosition.Top;
}
The command is then useable as any other WPF command in your application and you can even use parameters if needed.
Adding a Routed event to the control
Adding an event can be useful to notify the others part of your application that an action occurred in the control or to deliver informations.
To add an event here are the guideline :
- (optionnal) Creates the events args inherithing from RoutedEventArgs that you will use
- Declare the event handler of the event,
- Declare the RoutedEvent with the name of your choice,
- Creates the accesor for a simplier use,
- (optionnal) creates a raiseYourEvent method to raise the event easily.
Now lets assume we wants to raise an event when the header is clicked. For this we’ll subscribe to the Header “MouseDown” event in the OnApplyTemplate() method and raise a newly created event in its handler :
public override void OnApplyTemplate()
{
base.OnApplyTemplate();
PART_Header = this.GetTemplateChild("PART_Header") as Border;
if (PART_Header == null)
throw new ArgumentNullException(
"Can't find PART_Header in the HeaderedControl template.");
PART_Header.MouseDown += (a, b) => { RaiseHeaderClickedEvent(); };
}
/// <summary>
/// the event handler delegate
/// </summary>
public delegate void HeaderClickedEventHandler(object sender,
HeaderClickedEventArgs e);
/// <summary>
/// Create a custom routed event by first
/// registering a RoutedEventID
/// This event uses the bubbling routing strategy
/// </summary>
public static readonly RoutedEvent HeaderClickedEvent =
EventManager.RegisterRoutedEvent(
"HeaderClicked", RoutingStrategy.Bubble,
typeof(HeaderClickedEventHandler), typeof(HeaderedControl));
/// <summary>
/// Occurs when the header is clicked.
/// </summary>
public event RoutedEventHandler HeaderClicked
{
add { AddHandler(HeaderClickedEvent, value); }
remove { RemoveHandler(HeaderClickedEvent, value); }
}
/// <summary>
/// Raises the header clicked event.
/// </summary>
void RaiseHeaderClickedEvent()
{
HeaderClickedEventArgs newEventArgs =
new HeaderClickedEventArgs(
HeaderedControl.HeaderClickedEvent);
RaiseEvent(newEventArgs);
}
/// <summary>
/// The header has been clicked event args
/// </summary>
public class HeaderClickedEventArgs : RoutedEventArgs
{
/// <summary>
/// Initializes a new instance of the
/// <see cref="HeaderClickedEventArgs"/> class.
/// </summary>
/// <param name="routedEvent">The routed event.</param>
public HeaderClickedEventArgs(RoutedEvent routedEvent)
: base(routedEvent) { }
}
Ease the use of your library by declaring an URL as an XML namespace
What is it ? Simply that when you will use the controls in another page you will not declare the XML namespace via an assembly name but via an URL easy to remember. Example :
<Window x:Class="AmazingWPFControls.Showcase.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:controls="http://blog.lexique-du-net.com/wpf/AmazingsWPFControls"
/>
Why to do it ?
So now all you have to do is to create a bright new control
Interesting links
- Recommended practices for WPF Custom Control developers
- MSDN : Control Authoring Overview
- MSDN : slider templating example
- how to get a reference to an element of the template
