Loaded event timing in Silverlight

The FrameworkElement.Loaded event in Silverlight has a timing difference versus the FrameworkElement.Loaded event in WPF. Specifically, in WPF, the Loaded event will occur 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 if you are trying to use the Loaded event for a relatively common control-use or control-definition scenario: you want to examine the visual tree, either to get a value there as a source for something else, or to change a value in the templated composition where you could only have known the “right” value at run-time. In this case, calls to the Silverlight VisualTreeHelper API to “walk” the visual tree of the template content might not work if you make them directly from a Loaded handler.

In the RTM release of the documentation on MSDN (and the offline version for Visual Studio's collections), we documented Silverlight's Loaded by re-using the same description as WPF had: "Occurs when a FrameworkElement has completed layout passes, has rendered, and is ready for interaction." In terms of Silverlight's timeline of events and callbacks for a control or other object, that description is not correct. A better description would be : "Occurs when a FrameworkElement has been constructed and added to the object tree." Because of how Silverlight processes templates, the visual tree construction aspect of the visual tree under that object might still be pending as of the Silverlight Loaded event. (We'll be changing the Loaded description as well as adding remarks to an upcoming Silverlight reference refresh on MSDN.)

If you are trying to use the Silverlight Loaded in the same sense as you might have used the WPF Loaded, there are several possible workarounds. Each has merits as well as possible limitations.

1) If you are subclassing from an existing control, rather than 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 walk it either to examine or to adjust the visuals. The limitation here is that if you are just consuming an existing control as part of your application, you can’t change anything about OnApplyTemplate, it is defined by the control.

2) You can still continue to use Loaded. However, as the very first call in your Loaded handler, call Control.ApplyTemplate on that control. ApplyTemplate is a synchronous method, so once you make that call and it comes back, your template-created visual tree is now present. While it might appear that calling ApplyTemplate is forcing the issue of something that was already happening, an explicit ApplyTemplate call does not duplicate effort on the part of the various Silverlight subsystems (render, layout, etc.). To use this approach, your element of concern does need to be a Control as opposed to a FrameworkElement, and there has to be an actual template involved (so typically this is appropriate for a ContentControl or ItemsControl).

3) You can handle LayoutUpdated instead of Loaded. LayoutUpdated is the last “object lifetime” event in the sequence of spinning up a control in Silverlight UI. The main limitation with LayoutUpdated is that the initialization seequence is not the only time that LayoutUpdated might be 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 changed a few property values and not the tree structure, and the visual tree of the object that you care about might not have changed at all. Therefore you might have to apply your own throttling or logic to determine whether a LayoutUpdated event really means that you need to examine or re-examine a visual tree.

Note that there are a lot of scenarios for handling Loaded that are not impacted by the timing issues of when a template is applied. For instance, you can still add event handlers or set properties for the object where Loaded is handled, you just can’t get into the template parts quite yet. 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.

Another improvement we are trying to get into the SDK documentation is a more complete timeline of all the callbacks and events that you might be interested in, either as a control consumer or as a control author, including where Loaded falls in the sequence. Another Microsoft Silverlight blogger, Dave Relyea, has put up this post on the control object timeline, check it out.