Share via

Writing Event Handlers for the OnLoad Event

  • Article

Writing Event Handlers for the Silverlight OnLoad Event

The OnLoad event occurs after the XAML content in the Microsoft Silverlight plug-in has completely loaded. The onLoad initialization parameter specifies the event-handler function that is called in response to the OnLoad event. onLoad is one of two possible events that you specify handlers for as part of Silverlight plug-in instantiation (the other event is onError). For information about specifying the handler name as a string during instantiation, see Instantiating a Silverlight Plug-in.

The OnLoad event occurs after any Loaded event for a UIElement-derived class such as Canvas, TextBlock, or Rectangle. The read-only IsLoaded property, which is set before the Onload event occurs, indicates whether the Silverlight plug-in is loaded.

OnLoad is a useful event-handling entry point, because you are assured that the user interface (UI) defined in the Source XAML for the Silverlight plug-in where the event is handled is ready for interaction and that all properties and methods are available. This is particularly relevant if you are merging information into your application that you chose not to represent in static XAML, such as user information, time-dependent information, and so on. This is also a convenient point to add event handlers to specific elements in the object tree that were not already added through the XAML attribute technique of name-referencing the event handler initially.

One aspect of the Silverlight plug-in is not determined at the time of OnLoad: the size of the overall plug-in content area, which is controlled by the hosting browser. If you need the current height and width of the overall content area, you should instead handle the OnResize event. This is true even for the initial load of the page that contains the Silverlight plug-in instance. Subsequent resizes of the OBJECT/EMBED tag, as initiated either by user action or through scripting to the hosting HTML element or the OBJECT/EMBED tags in the Document Object Model (DOM), also raise OnResize if the size changes.

JavaScript provides a set of events that you can use to respond to changes on the Web page at the DOM level, including the HTML page's onload event. You can use the Silverlight plug-in OnLoad event and the page's onload event on the same page. In this case, the OnLoad event occurs before the page's DOM-based onload event.

Using the Context Parameter with the OnLoad Event

The context parameter is a user-defined unique identifier that can be passed as a parameter to an OnLoad event handler that can be shared by multiple Silverlight plug-ins on the same Web page. The OnLoad context parameter corresponds to the value of the context initialization parameter.

The following HTML example shows how to define two Silverlight plug-in host elements on the same Web page.

HTML 
<div id="pluginHost" >
  <script type="text/javascript">
    // Create a variable that references the HTML element that hosts the plug-in.
    var parentElement = document.getElementById("pluginHost");
    // Create variables that contain unique identifiers for the plug-in.
    var name = "myslPlugin_1";
    var context = "context_1";
    // Initialize and create the plug-in.
    createSilverlight();
  </script>
</div>
<div id="pluginHost2" >
  <script type="text/javascript">
    // Create a variable that references the HTML element that hosts the plug-in.
    var parentElement = document.getElementById("pluginHost2");
    // Create variables that contain unique identifiers for the instance.
    var name = "myslPlugin_2";
    var context = "context_2";
    // Initialize and create the plug-in.
    createSilverlight();
  </script>
</div>

The following JavaScript example shows the corresponding CreateSilverlight method in the user-defined CreateSilverlight.js file. Notice that the method uses the values of the same parentElement, name, and context variables. Redefining an existing JavaScript variable replaces the old value with a new value of the variable.

JavaScript 
function createSilverlight()
{  
    Silverlight.createObject(
        "plugin.xaml",                  // Source property value.
        parentElement,                  // DOM reference to hosting DIV tag.
        name,                           // Unique plug-in ID value, a variable set before each page call.
        {                               // Plug-in properties.
            width:'600',                // Width of rectangular region of plug-in, in pixels.
            height:'200',               // Height of rectangular region of plug-in, in pixels.
            version:'1.0'               // Plug-in version to use.
        },
        {
            onError:null,               // Use default error handler.
            onLoad:onLoad               // OnLoad event handler that can be used for multiple instances.
        },
        null,                           // InitParams property value set to null.  
        context);                       // Unique context ID, a variable set before each page call.
}

The following JavaScript example shows the corresponding OnLoad event-handling function that is used by both plug-in instances. The context parameter corresponds to the value defined by the plug-in's context initialization parameter.

JavaScript 
function onLoad(plugin, userContext, sender)
{
    alert(plugin.id + " : " + userContext + " : " + sender.toString());
}

The Silverlight.js file generates a slightly different OnLoad event signature from the raw form that is provided to the OBJECT or EMBED tags created by the instantiation scripts. The Silverlight.js OnLoad wraps the basic OBJECT/EMBED OnLoad, adding two useful features:

  • If several plug-in instances are hosted on an HTML page, there is potential for event handlers to be confused about which instance was loaded. The CreateObject and CreateObjectEx functions in Silverlight.js add an optional context parameter for initialization, as decribed previously. Typically, this parameter is set to a unique string. That context value is passed back as an event-handler parameter, which makes it much simpler to write handler logic that can detect which plug-in's onLoad event is being handled at that time.
  • Instead of using the generic sender object, the Silverlight.js version of onLoad passes the actual Silverlight plug-in instance as the first event-handler parameter value. This saves you a call to sender.GetHost(), and you can store the return value as a variable in script for easy access to the Silverlight plug-in instance.

See Also

Silverlight Object Models and Scripting to the Silverlight Plug-in
Silverlight Events
Overviews and How-to Topics