ControlTemplate class

Applies to Windows and Windows Phone

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

Inheritance

Object
  DependencyObject
    FrameworkTemplate
      ControlTemplate

Syntax

Public NotInheritable Class ControlTemplate
    Inherits FrameworkTemplate

<ControlTemplate ...>
    templateRootElement
</ControlTemplate>

XAML Values

templateRootElement

A single object element that derives from FrameworkElement. The templateRootElement is often a panel that contains other elements.

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The ControlTemplate class has these types of members:

Constructors

The ControlTemplate class has these constructors.

ConstructorDescription
ControlTemplate Initializes a new instance of the ControlTemplate class.

 

Methods

The ControlTemplate class has these methods. It also inherits methods from the Object class.

MethodDescription
ClearValue Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)

 

Properties

The ControlTemplate class has these properties.

PropertyAccess typeDescription

Dispatcher

Read-onlyGets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)

TargetType

Read/writeGets or sets the type to which the ControlTemplate is applied.

 

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 value.

Learning more about the control template for a control

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>


Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

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

FrameworkTemplate
DataTemplate
OnApplyTemplate
Control.Template
Control
Style
Quickstart: Control templates

 

 

Show:
© 2014 Microsoft