How to create a template for a control (WPF.NET)

With Windows Presentation Foundation (WPF), you can customize an existing control's visual structure and behavior with your own reusable template. Templates can be applied globally to your application, windows and pages, or directly to controls. Most scenarios that require you to create a new control can be covered by instead creating a new template for an existing control.

In this article, you explore creating a new ControlTemplate for the Button control.

When to create a ControlTemplate

Controls have many properties, such as Background, Foreground, and FontFamily. These properties control different aspects of the control's appearance, but the changes that you can make by setting these properties are limited. For example, you can set the Foreground property to blue and FontStyle to italic on a CheckBox. When you want to customize the control's appearance beyond what setting the other properties on the control can do, you create a ControlTemplate.

In most user interfaces, a button has the same general appearance: a rectangle with some text. If you want to create a rounded button, you could create a new control that inherits from the button or recreates the functionality of the button. In addition, the new user control provides the circular visual.

You can avoid creating new controls by customizing the visual layout of an existing control. For a rounded button, you create a ControlTemplate with the desired visual layout.

On the other hand, if you need a control with new functionality, different properties, and new settings, you create a new UserControl.

Prerequisites

Create a new WPF application. In MainWindow.xaml (or another window of your choice), set the following properties on the element:

Set the content of the element to the following XAML:

    Unstyled Button
    Button 1
    Rounded Button
    Button 2

At the end, the MainWindow.xaml file should look similar to the following XAML:

    
        Unstyled Button
        Button 1
        Rounded Button
        Button 2
    

If you run the application, it looks like the following image:

Create a ControlTemplate

The most common way to declare a ControlTemplate is as a resource in the Resources section in a XAML file. Because templates are resources, they follow the same scoping rules as all resources. Where you declare a template affects where you can apply it. For example, if you declare the template in the root element of your application definition XAML file, you can use the template anywhere in your application. If you define the template in a window, only the controls in that window can use the template.

To start, add a Window.Resources element to your MainWindow.xaml file:

    
        
    
    
        Unstyled Button
        Button 1
        Rounded Button
        Button 2
    

Create a new and set the following properties:

This control template is simple:

• a root element for the control, a Grid
• an Ellipse to draw the rounded appearance of the button
• a ContentPresenter to display the user-specified button content

TemplateBinding

When you create a new ControlTemplate, you might still want to use the public properties to change the control's appearance. The TemplateBinding markup extension binds a property of an element that is in the ControlTemplate to a public property that the control defines. When you use a TemplateBinding, you enable properties on the control to act as parameters to the template. When you set a property on a control, the value passes to the element that has the TemplateBinding.

Ellipse

The Fill and Stroke properties of the element bind to the control's Foreground and Background properties.

ContentPresenter

The template also includes a element. Because this template is designed for a button, remember that the button inherits from ContentControl. The button displays the content of the element. You can set anything inside the button, such as plain text or even another control. Both of the following examples are valid buttons:

My Text




    Checkbox in a button

In both of the previous examples, the text and the checkbox are set as the Button.Content property. Whatever is set as the content can be presented through a , which is what the template does.

If you apply the ControlTemplate to a ContentControl type, such as a Button, the template looks for a ContentPresenter in the element tree. If it finds the ContentPresenter, the template automatically binds the control's Content property to the ContentPresenter.

Use the template

Find the buttons that you declared at the start of this article.

    Unstyled Button
    Button 1
    Rounded Button
    Button 2

Set the second button's Template property to the roundbutton resource:

    Unstyled Button
    Button 1
    Rounded Button
    Button 2

If you run the project and look at the result, you see that the button has a rounded background.

You might notice that the button isn't a circle but is skewed. Because of the way the element works, it always expands to fill the available space. Make the circle uniform by changing the button's width and height properties to the same value:

    Unstyled Button
    Button 1
    Rounded Button
    Button 2

Add a trigger

Even though a button with a template applied looks different, it behaves the same as any other button. If you press the button, the Click event fires. However, you might notice that when you move your mouse over the button, the button's visuals don't change. The template defines these visual interactions.

By using the dynamic event and property systems that WPF provides, you can watch a specific property for a value and then restyle the template when appropriate. In this example, you watch the button's IsMouseOver property. When the mouse is over the control, style the with a new color. This type of trigger is known as a PropertyTrigger.

For this feature to work, you need to add a name to the that you can reference. Give it the name of backgroundElement.

Next, add a new Trigger to the ControlTemplate.Triggers collection. The trigger watches the IsMouseOver event for the value true.

Next, add a to the that changes the Fill property of the to a new color.

Run the project. When you move the mouse over the button, the color of the changes.

Use a VisualState

Visual states are defined and triggered by a control. For example, when you move the mouse over the control, the control triggers the CommonStates.MouseOver state. You can animate property changes based on the current state of the control. In the previous section, you used a to change the background of the button to AliceBlue when the IsMouseOver property was true. Instead, create a visual state that animates the change of this color, providing a smooth transition. For more information about VisualStates, see Styles and templates in WPF.

To convert the to an animated visual state, remove the element from your template.

Next, in the root of the control template, add the element with a for CommonStates. Define two states, Normal and MouseOver.

Apply any animations you define in a when that state is triggered. Create animations for each state. Put animations inside of a element. For more information about storyboards, see Storyboards Overview.

• Normal

  This state animates the ellipse fill, restoring it to the control's Background color.

• MouseOver

  This state animates the ellipse Background color to a new color: Yellow.

The should now look like the following code.

Run the project. When you move the mouse over the button, the color of the animates.

Next steps

• Create a style for a control
• Styles and templates
• Overview of XAML resources