Expand Minimize

Control.Template property

Applies to Windows and Windows Phone

Gets or sets a control template. The control template defines the visual appearance of a control in UI, and is defined in XAML markup.

Syntax


Public Property Template As ControlTemplate


<control Template="{StaticResource templateResourceKey}"/>


<Style TargetType="controlTypeName">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="controlTypeName">
        templateRoot
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

XAML Values

templateResourceKey

The key that identifies the template being requested. The key refers to an existing resource in a ResourceDictionary.

Note  Property element syntax to define an inline template is technically possible, but not recommended for most template scenarios.

controlTypeName

The string form of the Type for a control.

templateRoot

A single object element (must be FrameworkElement derived) that defines the root element of a template. For more info on what can be used as a template root see Quickstart: Control templates.

Property value

Type: ControlTemplate

The template that defines the appearance of the Control. The ControlTemplate must have exactly one root element as its content.

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 Quickstart: 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.

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> 


Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Controls
Windows::UI::Xaml::Controls [C++]

Metadata

Windows.winmd

See also

Quickstart: Control templates
Control
OnApplyTemplate
GetTemplateChild
ControlTemplate
Style

 

 

Show:
© 2014 Microsoft