Written by:
Microsoft
Microsoft

Control Templates

Mar 05, 2009

Summary

Describes how to create a ControlTemplate to customize the appearance of a CheckBox control.

In Silverlight, you create a control template when you want to customize a control's visual structure and visual behavior. Controls have many properties, such as Background, Foreground, and FontFamily, that you can set to specify different aspects of the control's appearance. However, the changes that you can make by setting these properties are limited. You can use the ControlTemplate class to create a template that provides additional customization. This QuickStart shows how to create a ControlTemplate to customize the appearance of a CheckBox control.

This QuickStart contains the following sections:

Custom Control Template Example
Specifying the Visual Structure of a Control
Specifying the Visual Behavior of a Control

For more information, see Customizing the Appearance of an Existing Control by Creating a ControlTemplate in the Silverlight documentation on MSDN.

Custom Control Template Example

By default, a CheckBox control puts its Content (the string or object next to the CheckBox) to the right of the selection box. This is the visual structure of the CheckBox. By default, a check mark indicates that the CheckBox is selected. This is the visual behavior of the CheckBox. You can change these characteristics by creating a ControlTemplate for the CheckBox. For example, suppose that you want the content of the check box to be above the selection box, and you want to use an X to indicate that the check box is selected. You specify these characteristics in the ControlTemplate of the CheckBox.

The following example shows a CheckBox with the default ControlTemplate and a CheckBox with a custom ControlTemplate. To try this example, click the check boxes multiple times to see the Checked, Unchecked, and Indeterminate states.

Specifying the Visual Structure of a Control

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 makes up the control's visual structure.

The following XAML creates a ControlTemplate of a CheckBox that specifies that the content of the control is above the selection box. The example specifies a Path to create an X that indicates that the CheckBox is selected, and an Ellipse that indicates an indeterminate state. Note that the Opacity is set to 0 on the Path and the Ellipse so that by default, neither appear.

XAML

 
<ControlTemplate TargetType="CheckBox">
  <StackPanel x:Name="Root" 
    HorizontalAlignment="Center" 
    VerticalAlignment="Center">
       <!--The ContentPresenter displays the Content 
        property of the CheckBox.  Content can be any 
        type of object.-->    <ContentPresenter/>
        <!--Draw the selection indicator area.-->    <Border Width="30" Height="30" 
      BorderBrush="Black" 
      BorderThickness="1" CornerRadius="0" 
      HorizontalAlignment="Left"
      Background="{TemplateBinding Background}" 
      Padding="2" >

      <Grid>
                <!--Create an X to indicate that the 
               CheckBox is selected.-->        <Path x:Name="Checkmark" 
          Opacity="0" Stroke="#FF313030"
          Margin="-10.5,-6.8,-10.5,-6" 
          RenderTransformOrigin="0.5,0.5" 
          Fill="#FFE0E0E0" Stretch="Fill"
          Data="M103,240 L111,240 119,248 127,240 
                135,240 123,252 135,264 127,264 
                119,257 111,264 103,264 114,252 z" >

          <Path.RenderTransform>
            <TransformGroup>
              <ScaleTransform ScaleX="0.5" 
                ScaleY="0.5"/>
            </TransformGroup>
          </Path.RenderTransform>
        </Path>
                <!--Create an Ellipse to indicate that 
            the CheckBox is in an indeterminate 
            state.-->        <Ellipse x:Name="IndeterminateEllipse" 
          Opacity="0"
          Fill="#FFE0E0E0" Stroke="#FF313030"
          StrokeThickness="0.5" 
          Margin="1.5,1.9,1.5,1.4">
        </Ellipse>
      </Grid>
    </Border>
  </StackPanel>
</ControlTemplate>

Specifying the Visual Behavior of a Control

A visual behavior specifies the appearance of a control when it is in a certain state. The CheckBox control has three states: Checked, Unchecked, and Indeterminate. The value of the CheckBox.IsChecked property determines the state of the CheckBox, and its state determines what appears in the box.

The following table lists the possible values of IsChecked, the corresponding states of the CheckBox, and the appearance of the CheckBox.

IsChecked value	CheckBox state	CheckBox appearance
true	Checked	Contains an X.
false	Unchecked	Empty.
null	Indeterminate	Contains an ellipse.

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. 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. 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 XAML shows the VisualState objects for the Checked, Unchecked, and Indeterminate states. The example sets the VisualStateManager.VisualStateGroups attached property on the StackPanel, which is the root element of the ControlTemplate. The Checked VisualState specifies that the Opacity of the Path named Checkmark (which is shown in the previous example) is 1. The Indeterminate VisualState specifies that the Opacity of the Ellipse named IndeterminateEllipse is 1. The Unchecked VisualState has no Storyboard, so the CheckBox returns to its default appearance.

XAML


<ControlTemplate TargetType="CheckBox">
  <StackPanel x:Name="Root" 
    HorizontalAlignment="Center" 
    VerticalAlignment="Center">

    <vsm:VisualStateManager.VisualStateGroups>
      <vsm:VisualStateGroup x:Name="CheckStates">

        <vsm:VisualStateGroup.Transitions>
          <vsm:VisualTransition 
            GeneratedDuration="0:0:.2" />
        </vsm:VisualStateGroup.Transitions>

        <vsm:VisualState x:Name="Unchecked"/>

        <vsm:VisualState x:Name="Checked">
          <Storyboard>
            <DoubleAnimation 
              Storyboard.TargetName="Checkmark" 
              Storyboard.TargetProperty="Opacity" 
              Duration="0" To="1"/>
          </Storyboard>
        </vsm:VisualState>

        <vsm:VisualState x:Name="Indeterminate">
          <Storyboard>
            <DoubleAnimation 
              Storyboard.TargetName=
                "IndeterminateEllipse" 
              Storyboard.TargetProperty="Opacity" 
              Duration="0" To="1"/>
          </Storyboard>
        </vsm:VisualState>

      </vsm:VisualStateGroup>
    </vsm:VisualStateManager.VisualStateGroups>

        <!--The visual structure of ControlTemplate, 
        which is shown in the previous example, 
        is defined here.-->
    ...
  </StackPanel>
</ControlTemplate>

To better understand how VisualState objects work, consider what occurs when the CheckBox goes from the Unchecked state to the Indeterminate state, then to the Checked state, and then back to the Unchecked state. The following table describes these transitions.

State transition	What occurs	CheckBox appearance when the transition completes
From Unchecked to Indeterminate.	The Storyboard of the Indeterminate VisualState begins, so the Opacity of `IndeterminateEllipse` is 1.	An X is displayed.
From Indeterminate to Checked.	The Storyboard of the Checked VisualState begins, so the Opacity of `Checkmark` is 1. The Storyboard of the Indeterminate VisualState ends, so the Opacity of `IndeterminateEllipse` is 0.	An ellipse is displayed.
From Checked to Unchecked.	The Storyboard of the Checked VisualState ends, so the Opacity of `Checkmark` is 0.	Nothing is displayed.

Quickstarts

Animations
Describes how to create basic animations by changing property values and by using key frames.
Audio and Video
Describes how to integrate media into your applications.
Images
Describes how to integrate images into your applications.
Deep Zoom
Describes how to create a Deep Zoom image, load a Deep Zoom image, and add interactivity.
Control Templates
Describes how to create a ControlTemplate to customize the appearance of a CheckBox control.
Data Binding to Controls
Describes how to data bind to a control and customize the display.
HTML Bridge
Describes how to access the HTML DOM from managed code, and to call managed code from JavaScript.
Isolated Storage
Describes how to save and retrieve data as key-value pairs or files in isolated storage.
LINQ TO XML
Describes hows how to use LINQ to filter, group, sort, transform, and project an RSS feed.
Syndication Feeds
Describes how to create a Silverlight client that can access and display a syndication service.
Web Services
Provides an introduction to using Web services in Silverlight.
Dynamic Languages
Demonstrates dynamic languages (Python and Ruby) by showing the DLR Console sample.
Three D
Describes how to create 3D effects.