FrameworkElement.Loaded event

Occurs when a FrameworkElement has been constructed and added to the object tree, and is ready for interaction.

Syntax

public:
event RoutedEventHandler^ Loaded {
   Windows::Foundation::EventRegistrationToken add(RoutedEventHandler^ value);
   void remove(Windows::Foundation::EventRegistrationToken token);
}

<frameworkElement Loaded="eventhandler"/>
 

Event information

Remarks

Although this event uses the RoutedEventHandler delegate and RoutedEventArgs as event data, the event is not a routed event. It can be handled only on the element that originates the event (in other words, the sender). OriginalSource in event data for this event is always null.

Loaded and object lifetime

In the Windows Runtime implementation, the Loaded event is guaranteed to occur after a control template is applied, and you can obtain references to objects that are created by applying the XAML template. This fact was not documented correctly in previous releases of documentation.

The Loaded event can be used as a point to hook up event handlers on elements that come from a template, or to invoke logic that relies on the existence of child elements that are the result of an applied template. Loaded is the preferred object lifetime event for manipulating element tree structures with app code prior to the display of XAML controls. It is also appropriate to call the VisualStateManager.GoToState method from a Loaded handler in order to set an initial view state that is defined in the template.

The timing of Loaded in the Windows Runtime implementation is similar to its timing in the Windows Presentation Foundation (WPF) implementation. In contrast, the Microsoft Silverlight implementation has a timing issue where you cannot rely on the template being loaded when Loaded fired. If you are migrating XAML or code-behind from these XAML frameworks, you may want to adjust what you do in a Loaded handler to be appropriate for the template-load timing of the Windows Runtime implementation.

To access the items that come from an applied template, you can use the VisualTreeHelper static methods and navigate child elements by index. Or you can call the FindName method on the root element of the templated content to find a specific part of the template with a given x:Name value. Note that you must call FindName on the template root rather than the control itself, because there is a XAML namescope created any time that objects are created by a template that is specific to that template (for more info, see XAML namescopes). To get to the template root, use VisualTreeHelper.GetChild(target,0) where target is the object where the template is applied.

If you are deriving from an existing control, instead of handling Loaded on a per instance basis, you can override OnApplyTemplate to make the behavior part of the default class behavior. OnApplyTemplate is specifically intended as the callback for this situation, where you have a tree of objects from the applied template and now you want to examine or adjust the visuals. This is a key part of defining behavior for a custom control, including actions such as declaring the starting visual states and wiring class handlers that can't be defined using the On* override pattern.

LayoutUpdated is a related event. The LayoutUpdated event is the last "object lifetime" event in the sequence of enabling a control, and occurs after Loaded. However, LayoutUpdated is raised for objects that are involved in a layout change, not just successive parents in the tree. Several objects in a UI might all fire LayoutUpdated at the same time. Layout changes happen for a variety of reasons, such as the user changing the view state or screen resolution, or programmatic resize of other elements in the same UI or layout container. For this reason, Loaded is usually a better choice for running code that works with an initial layout or an applied template.

For app code that uses navigation between pages, do not use Page.OnNavigatedTo for element manipulation or state change of controls on the destination page. The OnNavigatedTo virtual method is invoked before the template is loaded, thus elements from templates aren't available yet. Instead, attach a Loaded event handler at the root of the newly loaded page's content, and perform any element manipulations, state changes, event wiring and so on in the Loaded event handler.

Examples

Handlers for Loaded and Unloaded are automatically attached to any page that uses the LayoutAwarePage common code template. The event wiring is done in the LayoutAwarePage constructor. The handler invokes helper methods that maintain view state, and attaches other event handlers so that page navigation can use mouse or keyboard events.

Loaded += ref new RoutedEventHandler([=](Object^ sender, RoutedEventArgs^ e)
{
    this->StartLayoutUpdates(sender, e);

    // Keyboard and mouse navigation only apply when occupying the entire window
    if (this->ActualHeight == Window::Current->Bounds.Height &&
        this->ActualWidth == Window::Current->Bounds.Width)
    {
        // Listen to the window directly so focus isn't required
        _acceleratorKeyEventToken = Window::Current->CoreWindow->Dispatcher->AcceleratorKeyActivated +=
            ref new TypedEventHandler<CoreDispatcher^, AcceleratorKeyEventArgs^>(this,
            &LayoutAwarePage::CoreDispatcher_AcceleratorKeyActivated);
        _pointerPressedEventToken = Window::Current->CoreWindow->PointerPressed +=
            ref new TypedEventHandler<CoreWindow^, PointerEventArgs^>(this,
            &LayoutAwarePage::CoreWindow_PointerPressed);
        _navigationShortcutsRegistered = true;
    }
});

The Loaded event is a good time to start decorative animations that aren't tied to theme animations or other triggers. This example shows triggering a PointAnimation in XAML, by wiring a Loaded handler to a method that calls Begin on an animation Storyboard.

<Canvas Width="450" Height="350">
    <Canvas.Resources>
        <Storyboard x:Name="myStoryboard">

            <!-- Animate the center point of the ellipse from 100 X, 300 Y
             to 400 X, 100 Y over 5 seconds. -->
            <PointAnimation
             Storyboard.TargetProperty="Center"
             Storyboard.TargetName="MyAnimatedEllipseGeometry"
             Duration="0:0:5" 
             From="100,300"
             To="400,100"
             RepeatBehavior="Forever" EnableDependentAnimation="True"/>

        </Storyboard>
    </Canvas.Resources>
    <Path Fill="Blue" Loaded="Start_Animation">
        <Path.Data>

            <!-- Describes an ellipse. -->
            <EllipseGeometry x:Name="MyAnimatedEllipseGeometry"
             Center="200,100" RadiusX="15" RadiusY="15" />
        </Path.Data>
    </Path>
</Canvas>

// Start the animation when the object loads
void SampleApp::Page::Start_Animation(Platform::Object^ sender, Windows::UI::Xaml::Input::RoutedEventArgs^ e)
{
    myStoryboard->Begin();
}

Requirements

See also

FrameworkElement

OnApplyTemplate

VisualTreeHelper

Control.Template

Events and routed events overview

Quickstart: control templates

Build date: 1/31/2013