| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.ControlTemplate |
winrt class |
Defines the element tree that is used as the control template for a control.
<ControlTemplate ...>
templateRootElement
</ControlTemplate>For more info and examples, see XAML control templates.
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.
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.
[!code-xaml11]
You can see the complete template for each XAML control in the generic.xaml file. This file is found in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP<SDK version>\Generic folder.
FrameworkTemplate, DataTemplate, OnApplyTemplate, Control.Template, Control, Style, Quickstart: Control templates, XAML control templates