ControlTemplate ControlTemplate ControlTemplate Class

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

Syntax

Declaration

public sealed class ControlTemplatepublic sealed class ControlTemplatePublic NotInheritable Class ControlTemplate
<ControlTemplate ...>
    templateRootElement
</ControlTemplate>

Inheritance Hierarchy

Remarks

ControlTemplate is used as the value of the 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 Template with a Setter. You rarely if ever assign a value for 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 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(String).

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.

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>

Constructors summary

Initializes a new instance of the ControlTemplate class.

Properties summary

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

Constructors

  • ControlTemplate()
    ControlTemplate()
    ControlTemplate()
    ControlTemplate()

    Initializes a new instance of the ControlTemplate class.

    public ControlTemplate()public New()Public Sub New()public ControlTemplate()

Properties

  • TargetType
    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 Typepublic TypeName TargetType { get; set; }
    <ControlTemplate TargetType="typeName"/>
    

    Property Value

    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 TargetType value and the 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#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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll