Control.Template Property
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Gets or sets a control template. The control template defines the visual appearance of a control in UI, and is defined in XAML markup.
public:
property ControlTemplate ^ Template { ControlTemplate ^ get(); void set(ControlTemplate ^ value); };ControlTemplate Template();
void Template(ControlTemplate value);public ControlTemplate Template { get; set; }var controlTemplate = control.template;
control.template = controlTemplate;Public Property Template As ControlTemplate<control Template="{StaticResource templateResourceKey}"/>
- or -
<Style TargetType="controlTypeName">
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="controlTypeName">
templateRoot
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
Property Value
The template that defines the appearance of the Control. The ControlTemplate must have exactly one root element as its content.
Examples
This example shows a more complete control template defined as a Style and Setter with Setter.Property value of "Template". This is a named style for a RadioButton control. It includes the template elements that are normally part of a functional control template, such as a VisualStateManager.VisualStateGroups attached property element attached to the root element of the template, and x:Name attribute values assigned to each of the prominent control parts.
<Style x:Key="TextRadioButtonStyle" TargetType="RadioButton">
<Setter Property="MinWidth" Value="0"/>
<Setter Property="MinHeight" Value="0"/>
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="RadioButton">
<Grid Background="Transparent">
<TextBlock
x:Name="Text"
Text="{TemplateBinding Content}"
Margin="3,-7,3,10"
TextWrapping="NoWrap"
Style="{StaticResource SubheaderTextStyle}"/>
<Rectangle
x:Name="FocusVisualWhite"
IsHitTestVisible="False"
Stroke="{StaticResource FocusVisualWhiteStrokeThemeBrush}"
StrokeEndLineCap="Square"
StrokeDashArray="1,1"
Opacity="0"
StrokeDashOffset="1.5"/>
<Rectangle
x:Name="FocusVisualBlack"
IsHitTestVisible="False"
Stroke="{StaticResource FocusVisualBlackStrokeThemeBrush}"
StrokeEndLineCap="Square"
StrokeDashArray="1,1"
Opacity="0"
StrokeDashOffset="0.5"/>
<VisualStateManager.VisualStateGroups>
<VisualStateGroup x:Name="CommonStates">
<VisualState x:Name="Normal"/>
<VisualState x:Name="PointerOver">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground">
<DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationPointerOverForegroundThemeBrush}"/>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
<VisualState x:Name="Pressed">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground">
<DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationPressedForegroundThemeBrush}"/>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
<VisualState x:Name="Disabled">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground">
<DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ButtonDisabledForegroundThemeBrush}"/>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
</VisualStateGroup>
<VisualStateGroup x:Name="FocusStates">
<VisualState x:Name="Focused">
<Storyboard>
<DoubleAnimation Duration="0" To="1" Storyboard.TargetName="FocusVisualWhite" Storyboard.TargetProperty="Opacity"/>
<DoubleAnimation Duration="0" To="1" Storyboard.TargetName="FocusVisualBlack" Storyboard.TargetProperty="Opacity"/>
</Storyboard>
</VisualState>
<VisualState x:Name="Unfocused"/>
</VisualStateGroup>
<VisualStateGroup x:Name="CheckStates">
<VisualState x:Name="Checked"/>
<VisualState x:Name="Unchecked">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetName="Text" Storyboard.TargetProperty="Foreground">
<DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource ApplicationSecondaryForegroundThemeBrush}"/>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
<VisualState x:Name="Indeterminate"/>
</VisualStateGroup>
</VisualStateManager.VisualStateGroups>
</Grid>
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
Remarks
The second XAML syntax shown above is a Setter syntax as part of a Style. This is how a Template value for a Control is defined in almost all cases.
TargetType is a required attribute on all ControlTemplate elements used as a Template value. The value should match the TargetType property for the Style that contains the Setter for Template, if you are using a style-setter syntax.
The ControlTemplate specifies the appearance of a Control; if a Control does not have a ControlTemplate, the Control will have no visible presence in your app. The control author defines the default control template, and the app author can re-template the ControlTemplate XAML to redefine the visual tree of the control.
Control templates are typically set in Extensible Application Markup Language (XAML) as part of a control-specific implicit style. In this case, a Property value in the Setter is set as the string "Template", and the Setter.Value value is set as a property element, which contains a ControlTemplate object element. For example, this is the Style that defines a Template value for a ScrollViewer. This is an example of an implicit style, where the Style can be in a ResourceDictionary but doesn't need an x:Key attribute.
<ResourceDictionary>
<Style TargetType="ScrollViewer">
...
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="ScrollViewer">
<!--visual root of template for a ScrollViewer-->
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
...
</ResourceDictionary>
Styles and templates
You can use a Setter in a Style to apply values to any dependency property. But it's the Setter for the Template property of a Control-derived class that constitutes the majority of the XAML markup in a typical Style. When a Style is used to define a control template, the TargetType of the Style element and the TargetType of the ControlTemplate element for its Control.Template setter should always use the same value. The Template setter defines the basic templated UI definition for a control where that template is applied. It also contains the visual states for a control, and other state-based UI definitions such as default theme transitions. For a complex control such as ListBox, the default template Style and the ControlTemplate within can have hundreds of lines of XAML. For more info on the role of Template in control templating scenarios, see XAML Control templates.
Implicit styles
You can define styles such that a Style is used implicitly by all objects of the same TargetType, without requiring each instance of such an object to specifically reference the Style as a FrameworkElement.Style value. When a <Style> resource is declared in a ResourceDictionary without an x:Key attribute, the x:Key value uses the value of the TargetType property. If you set the style implicitly, the style is applied only to the types that match the TargetType exactly and not to elements derived from the TargetType value. For example, if you create a style implicitly for all the ToggleButton controls in your application, and your application has ToggleButton and CheckBox controls (CheckBox derives from ToggleButton), the "ToggleButton" implicit style is applied only to the ToggleButton controls.