This topic assumes that you understand creating and using controls and styles as discussed in Getting Started with Controls. The concepts discussed in this topic apply to elements that inherit from the Control class, except for the UserControl. You cannot apply a ControlTemplate to a UserControl.

Controls have many properties, such as Background, Foreground, and FontFamily, that you can set to specify 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.

Without the ability to create a new ControlTemplate for controls, all controls in every Silverlight-based application would have the same general appearance, which would limit the ability to create an application with a custom look and feel. By default, every CheckBox has similar characteristics. For example, the content of the CheckBox is always to the right of the selection indicator, and the check mark is always used to indicate that the CheckBox is selected.

You create a ControlTemplate when you want to customize the control's appearance beyond what setting the other properties on the control will do. In the example of the CheckBox, suppose that you want the content of the check box to be above the selection indicator and an X to indicate that the CheckBox is selected. You specify this is the ControlTemplate of the CheckBox.

Click the following link to see a CheckBox that uses a default ControlTemplate and CheckBox that uses a custom ControlTemplate to place the content of the CheckBox above the selection indicator and display an X when the CheckBox is selected.

Run this sample.

The ControlTemplate for the CheckBox in this sample is relatively complex, so this topic uses a simpler example of creating a ControlTemplate for a Button.

The Template property specifies the ControlTemplate of a control. Like many properties, the Template property can be set in the following ways:

• Locally set Template to a ControlTemplate that is defined inline.

• Locally set Template to a reference to a ControlTemplate that is defined as a resource.

• Set Template and define a ControlTemplate in a Style.

The following example demonstrates setting the Template property locally and defining the ControlTemplate inline.

<Button Content="Button1">
  <Button.Template>
    <ControlTemplate TargetType="Button">

      <!--Define the ControlTemplate here.-->

    </ControlTemplate>
  </Button.Template>
</Button> 

The following example demonstrates defining the ControlTemplate as a resource and setting the Template to a reference to the resource.

<StackPanel>
  <StackPanel.Resources>
    <ControlTemplate x:Key="ButtonTemplate" TargetType="Button">

      <!--Define the ControlTemplate here.-->

    </ControlTemplate>
  </StackPanel.Resources>

  <Button Template="{StaticResource ButtonTemplate}" Content="Button1"/>
</StackPanel>

The following example demonstrates setting the Template property and defining the ControlTemplate in a Style.

<StackPanel>
  <StackPanel.Resources>
    <Style x:Key="ButtonStyle" TargetType="Button"> 
      <Setter Property="Template">
        <Setter.Value>
          <ControlTemplate TargetType="Button">

            <!--Define the ControlTemplate here.-->

          </ControlTemplate>
        </Setter.Value>
      </Setter>
    </Style>
  </StackPanel.Resources>
  <Button Style="{StaticResource ButtonStyle}" Content="Button1"/>
</StackPanel>

Although all three of these methods are valid ways to define a ControlTemplate, it is probably most common to see the Template property set in a Style. When you see a ControlTemplate is set in a Style, realize that the style just sets the Template property, just as it does for any other property.

In Silverlight, a control is often a composite FrameworkElement objects. When you create a ControlTemplate, you combine FrameworkElement objects to build a single control. A ControlTemplate must have only one FrameworkElement as its root element. The root element usually contains other FrameworkElement objects. The combination of objects is makes up the control's visual structure.

The following example creates a custom ControlTemplate for the Button. The ControlTemplate creates the visual structure of the Button. This example does not change the button's appearance when you point to it or click it. Changing the button's appearance when it is in a different state is discussed later in this topic.

In this example, the visual structure is made up of the following parts:

• A Border called RootElement that serves as the template's root FrameworkElement.

• A Grid that is a child of RootElement.

• A ContentPresenter that displays the button's content. The ContentPresenter enables any type of object to be displayed.

<ControlTemplate TargetType="Button">
  <Border x:Name="RootElement">

    <!--Create the SolidColorBrush for the Background 
        as an object elemment and give it a name so 
        it can be referred to elsewhere in the control template.-->
    <Border.Background>
      <SolidColorBrush x:Name="BorderBrush" Color="Black"/>
    </Border.Background>

    <!--Create a border that has a different color by adding smaller grid.
        The background of this grid is specificied by the button's Background
        property.-->
    <Grid Margin="4" Background="{TemplateBinding Background}">

      <!--Use a ContentPresenter to display the Content of
          the Button.-->
      <ContentPresenter
          HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
          VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
          Margin="4,5,4,4" />
    </Grid>

  </Border>
</ControlTemplate>

Preserving the Functionality of a Control's Properties by Using TemplateBinding

<StackPanel>
  <Button Style="{StaticResource newTemplate}" 
          Background="Navy" Foreground="White" FontSize="14"
          Content="Button1"/>

  <Button Style="{StaticResource newTemplate}" 
          Background="Purple" Foreground="White" FontSize="14"
          Content="Button2" Click="Button_Click"/>
</StackPanel>

The difference between a button with its default appearance and the button in the preceding example is that the default button subtly changes when it is in different states. For example, the default button's appearance changes when the button is pressed, or when the mouse pointer is over the button. Although the ControlTemplate does not change the functionality of a control, it does change the control's visual behavior. A visual behavior describes the control appearance when it is in a certain state. To understand the difference between the functionality and visual behavior of a control, consider the button example. The button's functionality is to raise the Click event when it is clicked, but the button's visual behavior is to change its appearance when it is pointed to or pressed.

You use VisualState objects to specify the appearance of a control when it is in a certain state. A VisualState contains a Storyboard that changes the appearance of the elements that are in the ControlTemplate. You do not have to write any code to make this occur because the control's logic changes state by using the VisualStateManager. When the control enters the state that is specified by the VisualState..::.Name property, the storyboard begins. When the control exits the state, the Storyboard stops.

The following example shows the VisualState that changes the appearance of a Button when the mouse pointer is over it. The Name of the VisualState matches the name specified by the TemplateVisualStateAttribute on the Button class. The Storyboard changes the button's border color by changing the color of the BorderBrush. If you refer to the ControlTemplate example at the beginning of this topic, you will recall that BorderBrush is the name of the SolidColorBrush that is assigned to the Background of the Border.

<!--Change the border of the button to red when the
    mouse is over the button.-->
<vsm:VisualState x:Name="MouseOver">
  <Storyboard>
    <ColorAnimation Storyboard.TargetName="BorderBrush" 
                    Storyboard.TargetProperty="Color" To="Red" />

  </Storyboard>
</vsm:VisualState>

The control is responsible for defining the states as part of its control contract, which is discussed in detail in Customizing Other Controls by Understanding the Control Contract later in this topic. The states of a control are specified by the TemplateVisualStateAttribute, which is placed on the control's class definition. A TemplateVisualStateAttribute specifies the name of the state and the name of the state group that the state belongs to. The following example shows the states that are specified for the Button.

[TemplateVisualState(Name = "Normal", GroupName = "CommonStates")]
[TemplateVisualState(Name = "MouseOver", GroupName = "CommonStates")]
[TemplateVisualState(Name = "Pressed", GroupName = "CommonStates")]
[TemplateVisualState(Name = "Disabled", GroupName = "CommonStates")]
[TemplateVisualState(Name = "Unfocused", GroupName = "FocusStates")]
[TemplateVisualState(Name = "Focused", GroupName = "FocusStates")]
public class Button : ButtonBase
{
}

<TemplateVisualStateAttribute(Name:="Pressed", GroupName:="CommonStates")> _
<TemplateVisualStateAttribute(Name:="Focused", GroupName:="FocusStates")> _
<TemplateVisualStateAttribute(Name:="Normal", GroupName:="CommonStates")> _
<TemplateVisualStateAttribute(Name:="MouseOver", GroupName:="CommonStates")> _
<TemplateVisualStateAttribute(Name:="Disabled", GroupName:="CommonStates")> _
<TemplateVisualStateAttribute(Name:="Unfocused", GroupName:="FocusStates")> _
Public Class Button
    Inherits ButtonBase

End Class

The TemplateVisualStateAttribute..::.GroupName property specifies which group a state belongs to. In the preceding example, the Button defines two state groups: the CommonStates group contains the Normal, MouseOver, Pressed, and Disabled states. The FocusStates group contains the Focused and Unfocused states. States in the same state group are mutually exclusive. The control is always in exactly one state per group. For example, a Button can have focus even when the mouse pointer is not over it, so a Button in the Focused state can be in the MouseOver, Pressed, or Normal state.

You add VisualState objects to VisualStateGroup objects. You add VisualStateGroup objects to the VisualStateManager.VisualStateGroups attached property, which you set on the root FrameworkElement of the ControlTemplate. The following example defines the VisualState objects for the Normal, MouseOver, and Pressed states, which are all in the CommonStates group. The Disabled state and the states in the FocusStates group are omitted to keep the example short, but they are included in the entire example in How to: Create a Custom Appearance for a Button.

<ControlTemplate TargetType="Button" 
                 xmlns:vsm="clr-namespace:System.Windows;assembly=System.Windows">
  <Border x:Name="RootElement">

    <vsm:VisualStateManager.VisualStateGroups>

      <!--Define the states and transitions for the common states.
          The states in the VisualStateGroup are mutually exclusive to
          each other.-->
      <vsm:VisualStateGroup x:Name="CommonStates">

        <!--The Normal state is the state the button is in
            when it is not in another state from this VisualStateGroup.-->
        <vsm:VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, BorderBrush, to red when the
            mouse is over the button.-->
        <vsm:VisualState x:Name="MouseOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Red" />

          </Storyboard>
        </vsm:VisualState>

        <!--Change the SolidColorBrush, BorderBrush, to Transparent when the
            button is pressed.-->
        <vsm:VisualState x:Name="Pressed">
          <Storyboard >
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Transparent"/>
          </Storyboard>
        </vsm:VisualState>

        <!--The Disabled state is omitted for brevity.-->
      </vsm:VisualStateGroup>
    </vsm:VisualStateManager.VisualStateGroups>

    <Border.Background>
      <SolidColorBrush x:Name="BorderBrush" Color="Black"/>
    </Border.Background>

    <Grid Background="{TemplateBinding Background}" Margin="4">
      <ContentPresenter
        HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
        VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
        Margin="4,5,4,4" />

    </Grid>


  </Border>
</ControlTemplate>

Run this sample.

If you run the preceding sample, you will notice that the appearance of a button changes when you point to it. The appearance of the button also changes when you click it, but unless you keep the button pressed for a full second, you do not see the effect. By default, an animation takes one second to occur. Because users are likely to click and release a button in much less time, the visual feedback will not be effective if you leave the ControlTemplate in its default state.

You can specify the amount of time that it takes an animation to occur to smoothly transition a control from one state to another by adding VisualTransition objects to the ControlTemplate. When you create a VisualTransition, you specify one or more of the following:

• The time it takes for a transition between states to occur.

• Additional changes in the control's appearance that occur at the time of the transition.

• Which states the VisualTransition is applied to.

Specifying the Duration of a Transition

<!--Take one hundredth of a second to transition to the
    Pressed state.-->
<vsm:VisualTransition To="Pressed" 
                      GeneratedDuration="0:0:0.01" />

Specifying Changes to the Control's Appearance During a Transition

<!--Take one and a half seconds to transition from the
    MouseOver state to the Normal state. 
    Have the SolidColorBrush, BorderBrush, fade to blue, 
    then to yellow, and then to black in that time.-->
<vsm:VisualTransition From="MouseOver" To="Normal" 
                      GeneratedDuration="0:0:1.5">
  <Storyboard>
    <ColorAnimationUsingKeyFrames
      Storyboard.TargetProperty="Color"
      Storyboard.TargetName="BorderBrush"
      FillBehavior="HoldEnd" >

      <ColorAnimationUsingKeyFrames.KeyFrames>

        <LinearColorKeyFrame Value="Blue" 
                             KeyTime="0:0:0.5" />
        <LinearColorKeyFrame Value="Yellow" 
                             KeyTime="0:0:1" />
        <LinearColorKeyFrame Value="Black" 
                             KeyTime="0:0:1.5" />

      </ColorAnimationUsingKeyFrames.KeyFrames>
    </ColorAnimationUsingKeyFrames>
  </Storyboard>
</vsm:VisualTransition>

Specifying When a VisualTransition Is Applied

<!--Take one half second to trasition to the MouseOver state.-->
<vsm:VisualTransition To="MouseOver" 
                      GeneratedDuration="0:0:0.5" />

<!--Take one hundredth of a second to transition from the
    Pressed state to the MouseOver state.-->
<vsm:VisualTransition From="Pressed" To="MouseOver" 
                      GeneratedDuration="0:0:0.01" />