Control​Template Control​Template Control​Template Class

Definition

Defines the element tree that is used as the control template for a control.

public : sealed class ControlTemplate : FrameworkTemplate, IControlTemplatepublic sealed class ControlTemplate : FrameworkTemplate, IControlTemplatePublic NotInheritable Class ControlTemplate Inherits FrameworkTemplate Implements IControlTemplate
<ControlTemplate ...>
    templateRootElement
</ControlTemplate>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited methods

Inherited properties

Examples

The following example creates a simple ControlTemplate for a Button. The control template contains one Grid and specifies this behavior:

  • When the user puts the mouse over the Button, the Grid changes from green to red over one half second.
  • When the user moves the mouse away from the button, the Grid immediately changes back to green.
<ControlTemplate TargetType="Button">
  <Grid >
    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup x:Name="CommonStates">

        <VisualStateGroup.Transitions>

          <!--Take one half second to transition to the PointerOver state.-->
          <VisualTransition To="PointerOver" 
                              GeneratedDuration="0:0:0.5"/>
        </VisualStateGroup.Transitions>
        
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, ButtonBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="ButtonBrush" 
                            Storyboard.TargetProperty="Color" To="Red" />
          </Storyboard>
        </VisualState>
      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
    <Grid.Background>
      <SolidColorBrush x:Name="ButtonBrush" Color="Green"/>
    </Grid.Background>
  </Grid>
</ControlTemplate>

Remarks

ControlTemplate is used as the value of the Control.Template property, which defines the visuals of a control by applying the template. You almost always define a ControlTemplate as a XAML resource, using an implicit key TargetType that is the same as a Style that sets Control.Template with a Setter. You rarely if ever assign a value for Control.Template directly on a control instance.

There are really only two properties you use when defining a ControlTemplate: the TargetType, and the implicit XAML content. ControlTemplate inherits the implicit XAML content behavior from its FrameworkTemplate parent. Basically the element contained within a ControlTemplate as defined in XAML is assigning a root element for a further structure of XAML elements that define the template. This is setting a "Template" property that can't subsequently be examined by code and only has meaning for how the XAML parser assigns content for controls based on applying that template.

To have its content be set from a ControlTemplate, a control element must be a true Control subclass, so that it has the Control.Template property. There are other cases where templates apply content but this usually involves one of the other FrameworkTemplate derived template classes (DataTemplate or ItemsPanelTemplate ).

Control templates provide the visuals and parts that make up an instance of a control as it appears in an app's UI. At run time, the template has already been applied, and so all the parts that were created out of the template are now truly parts of the control, and can be accessed by techniques such as examining the XAML namescopes from within control content or using the VisualTreeHelper class. Events such as the input events sometimes expose the parts of a control that came from the applied control template.

There are ways to access template-defined content either before or after the template is applied to a specific control instance; see OnApplyTemplate or GetTemplateChild.

The actual point in time that a ControlTemplate is applied to a control instance can be detected because this invokes the OnApplyTemplate protected virtual method. So long as the control isn't sealed, you can subclass a control so that you have the opportunity to override OnApplyTemplate. This override can be written to perform actions that wouldn't be possible prior to the template being applied. For example, you can wire event handlers to control parts, or set control properties to reference object parts that were created out of the template but didn't start with a {TemplateBinding} markup extension value.

Learning more about the control template for a control

Each XAML control has a topic in the documentation that discusses the control template, including the resources consumed by that template and other style elements. For example, you can learn about the default XAML template for the FlipView control in the topic FlipView styles and templates.

Constructors

ControlTemplate() ControlTemplate() ControlTemplate()

Initializes a new instance of the ControlTemplate class.

public : ControlTemplate()public ControlTemplate()Public Sub New()
Attributes

Properties

TargetType TargetType TargetType

Gets or sets the type to which the ControlTemplate is applied.

public : TypeName TargetType { get; set; }public Type TargetType { get; set; }Public ReadWrite Property TargetType As Type
<ControlTemplate TargetType="typeName"/>
Value
TypeName Type Type

The type to which the ControlTemplate is applied. This value is usually set in XAML, not code. See Remarks.

Attributes

Remarks

The typical way to specify a TargetType value is through a XAML attribute on the ControlTemplate. When set in XAML, the meaning of TargetType and the values you provide take on some aspects of how types are represented in XAML. In particular, any prefixes that would be necessary to refer to a given type as a XAML element should also be included as the value of the TargetType value string. For example, if a template is intended to target a custom type that must be preceded by the already-mapped prefix "local" in a particular markup scope, then the TargetType value should include that same prefix. This behavior is enabled by built-in conversion behavior in the Windows Runtime XAML parser.

In most cases, you will be setting the TargetType for a ControlTemplate where that ControlTemplate is within a Setter for the Template property. This in turn is within the implicit Style you are defining for a control. The ControlTemplate.TargetType value and the Style.TargetType value of the containing Style should always be the same type reference, referring to the same implicitly named control. Otherwise the control template might not work.

For more info on how to write a control template, see Quickstart: Control templates.

Note

If you have previously programmed XAML for Windows Presentation Foundation (WPF), then you might have used an x:Type markup extension to fill in any XAML values that take a System.Type. The Windows Runtime XAML parser does not support x:Type. Instead, you should refer to the type by name without using any markup extension, and any necessary XAML-to-backing type conversion is already handled by the built-in conversion behavior described in the previous paragraph.

Using TargetType in code

Setting TargetType in code is uncommon. The XAML style/template system is intended to be used by loading XAML as a resource and having all aspects of a control template be ready beforehand. There should be very few scenarios where you would not know info about controls and templates until runtime, where there is a need to set a TargetType on a ControlTemplate created or referenced in code.

Getting a TargetType in code is also uncommon, but you might do this to double-check that a ControlTemplate that you've loaded from XAML is compatible with a given control target that you got from the runtime tree.

Tip

If you are programming using a Microsoft .NET language (C# or Microsoft Visual Basic), the TypeName type projects as System.Type. When programming using C#, you usually use the typeof operator to get references to the System.Type of a type based on a type name as a string. In Microsoft Visual Basic, use GetType.

See Also

See Also