FrameworkElement.OnApplyTemplate Method
Microsoft Silverlight will reach end of support after October 2021. Learn more.
When overridden in a derived class, is invoked whenever application code or internal processes (such as a rebuilding layout pass) call ApplyTemplate. In simplest terms, this means the method is called just before a UI element displays in an application. For more information, see Remarks.
Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)
Syntax
'Declaration
Public Overridable Sub OnApplyTemplate
public virtual void OnApplyTemplate()
Remarks
Silverlight template support is not fully enabled on FrameworkElement. Instead, the Silverlight architecture provides template support for Control, which is an immediate subclass of FrameworkElement. Specialized template behavior also exists for ContentPresenter. OnApplyTemplate is defined at the FrameworkElement level for WPF compatibility reasons.
Notes to Inheritors
This method can have a native implementation, which is referenced by the default implementation at the FrameworkElement level; therefore, you should always call the base implementation if deriving from FrameworkElement. If deriving from Control or further subclasses, the Control implementation calls the FrameworkElement base. Therefore, this accesses the native-level implementation implicitly if you call the immediate base.
Derived classes can use this method as a notification or entry point for the following scenarios:
Build the remainder of a visual tree using custom code.
Run code that relies on the visual tree from templates having been applied, such as obtaining references to named elements that came from a template.
Introduce services that only make sense to exist after the visual tree from templates is complete.
Attach class-defined event handlers to parts of the template. For example, you might want class logic to handle KeyDown events from a TextBox template part so that UI states are updated, and other events that are specific to your control are raised instead.
Set states and properties of elements within the template that are dependent on other factors. For instance, property values might only be discoverable by knowing the parent element, or when a specific derived class uses a common template. However, note that a well-designed control should generally handle its visual and behavioral states through VisualStateManager. For details on this concept, see Control Customization.
OnApplyTemplate is often a more appropriate point to deal with adjustments to the template-created visual tree than is the Loaded event. In Silverlight, the Loaded event might occur before the template is applied, and therefore, you might not be able to adjust the visual tree that is created through applying a template in a Loaded handler. For more information, see the Remarks for Loaded.
Examples
The following example shows an OnApplyTemplate override defined by a custom control that is designed to account for callers potentially defining and applying their own control template through the template and style system. As part of its definition, the control attributes the named elements within a template that are required, such as UpButtonElement. Then OnApplyTemplate retrieves the object references based on this naming contract when the template is loaded. Also, this example calls the private method UpdateState (definition not shown). This is another common scenario for OnApplyTemplate: making sure that the visual state is set for the control's starting state, in this case by calling a private method that accounts for all of the control's defined states and calls GoToState to set the appropriate state.
Public Overloads Overrides Sub OnApplyTemplate()
UpButtonElement = TryCast(GetTemplateChild("UpButton"), RepeatButton)
DownButtonElement = TryCast(GetTemplateChild("DownButton"), RepeatButton)
TextElement = TryCast(GetTemplateChild("TextBlock"), TextBlock)
UpdateStates(False)
End Sub
public override void OnApplyTemplate()
{
UpButtonElement = GetTemplateChild("UpButton") as RepeatButton;
DownButtonElement = GetTemplateChild("DownButton") as RepeatButton;
TextElement = GetTemplateChild("TextBlock") as TextBlock;
UpdateStates(false);
}
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.