Share via


FrameworkElement.Loaded Event

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Occurs when a FrameworkElement has been constructed and added to the object tree.

Namespace:  System.Windows
Assembly:  System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Event Loaded As RoutedEventHandler
public event RoutedEventHandler Loaded
<frameworkElement Loaded="eventhandler"/>

Remarks

This event uses the RoutedEventHandler delegate type, but the event does not route (as many Silverlight input events do). However, the nature of XAML loading of the object tree typically shows a pattern that superficially resembles a bubbling routed event pattern: all properties must be set on an object before it can be loaded. The deepest nested objects, such as objects that have no child objects, are loaded first—after all their XAML properties have values. For objects that have child objects, one of those properties is the property that holds the child objects. Therefore, the sequence of raising Loaded events occurs in an upward direction as the object tree is loaded. However, this sequence is really each object raising its own Loaded event in that order. Event data is not shared for the various Loaded events; these are all separate events, each raised by the individual object source.

There are exceptions to the above statement that Loaded events are raised in inverse tree order. Therefore, do not rely entirely on Loaded order for application logic. The following are some example cases where Loaded order can vary:

  • In most cases, the objects that are created from an applied control template or data template are the last objects to raise Loaded. However, this order principle can vary if specific controls use ApplyTemplate in initialization to force an early template load.

  • Because of template application and also because of data presentation rules for items in ItemsControl, sometimes the items will raise Loaded after their parent ItemsControl does, and after other branches of the main (non-templated) object tree raise Loaded.

Silverlight does not have an equivalent event for the WPF event Initialized.

Being resized by layout does not typically reload the object. See SizeChanged.

Loaded and Control Object Lifetime

The timing of the Loaded event in Silverlight differs from the timing of the FrameworkElement.Loaded event in WPF. Specifically, the WPF Loaded event occurs after the template is applied. In Silverlight, the Loaded event is not guaranteed to occur after the template is applied. This might be an issue for you if you are using the Loaded event for a relatively common control scenario: you want to examine the visual tree, either to get a value as a source for something else or to change a value in the templated composition where you can know the new value only at run time. In this case, calls to the Silverlight VisualTreeHelper methods to examine the visual tree of the template content might not work if you make them directly from a Loaded handler.

There are several ways to work around this issue. Each has merits as well as possible limitations:

  • If you are deriving from an existing control, instead of adding handling for Loaded, you can override OnApplyTemplate. OnApplyTemplate is specifically intended as the callback for this situation, where you have a tree from the template and now you want to examine or adjust the visuals. A limitation is that if you are just using an existing control as part of your application, you cannot change anything about OnApplyTemplate.

  • You can still continue to use Loaded. However, as the very first call in your Loaded handler, call ApplyTemplate on that control. ApplyTemplate is a synchronous method, so once you make that call and it returns, your template-created visual tree is now present. Calling ApplyTemplate in this case does not duplicate effort on the part of the Silverlight runtime. A limitation is that your element of concern does need to be a Control derived class.

  • You can handle LayoutUpdated instead of Loaded. LayoutUpdated is the last "object lifetime" event in the sequence of enabling a control in Silverlight UI. The main limitation of LayoutUpdated is that the initialization is possibly not the only time that LayoutUpdated is raised. Also, LayoutUpdated is raised for objects that are involved in a layout change. For instance, a peer in layout might have changed its size. In terms of visual trees, even the peer object may have changed only a few property values and not the tree structure, and the visual tree of the object that you are handling LayoutUpdated on might not have changed at all. Therefore, you might have to apply your own logic to determine whether a LayoutUpdated event really means that you need to examine or reexamine a visual tree.

Note that there are scenarios for handling Loaded that are not affected by the timing issues of template application. For instance, you can still add event handlers or set properties for the object where Loaded is raised, even if you cannot yet access the template parts. For instance, you can create objects in code and add them into content properties or content collections at this time, or add input-type event handlers that you chose not to hook up in the initial XAML.

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.