Handling Silverlight Events by Using JavaScript

Adding an Event Handler in XAML

The following XAML example shows how to add a handler for the Loaded event on a Canvas object. Notice that the event-handler function cannot be called with parameter values (even empty ones), which is unlike JavaScript event-handler functions for HTML elements in the HTML DOM.

<Canvas Loaded="OnLoaded" />

At the element level in XAML, there is no difference in how you reference the handler between the managed API and the JavaScript API. In both cases, you provide a string that names an event handler function (or method).

Programming Models and Event Handler Lookup

If the x:Class attribute exists, this corresponds to the page and larger application using the managed API. In this case, lookup for the event handler goes to the class referenced as x:Class. If the x:Class attribute does not exist, the page cannot be markup-compiled, there is no code-behind partial class (or at least the XAML parser cannot determine what the class is), and the page must use the JavaScript API for event handling. In this case, the host evaluates scripting in its scripting engine against the available JavaScript function and object definitions at run time in the HTML DOM.

Event Model Features That Are Common to Managed and JavaScript

Whether using the managed API or the JavaScript API, event handler functions/methods share the following concepts in their signatures: a sender value and an eventArgs (event data) value. The meaning of sender in both models is that sender is the object where the event handler is attached. The event data in both models is some object that has properties (and sometimes methods) that report specifics of that particular occurrence of the event.

Both models support the Silverlight implementation of a routed event. A routed event is an event that originates with one object in a tree of objects, but is then routed (forwarded) to each successive parent in the object tree and potential handlers on that parent, until that event reaches the root of the object tree. Generally, the object tree representation of how an event routes through the tree is analogous to the nesting of XAML object elements in the XAML that defines the page. The routed event concept in Silverlight is the reason why the definition of sender as the object where the event handler is attached differs from sender definitions you might see in basic .NET Framework documentation about CLR events, where sender is the object that raised the event. That is not necessarily true in a routed event case; the event might have been raised by a child object in the object tree and routed upwards. This routed event concept is also sometimes discussed in Silverlight and WPF documentation as being a bubbling event.

Writing Event Handlers in JavaScript

The following JavaScript example shows how to define a Silverlight event-handler function. In this case, the code displays a string in an alert dialog box that calls toString() on the sender parameter, which can be a useful debugging technique for determining information about objects.

function onLoaded(sender, eventArgs)
{
    // Display the object type of the sender parameter.
    alert("Sender = " + sender.toString());
}

JavaScript Optional Parameters and eventArgs

Accessing the Silverlight Object Tree by Combining sender and FindName

<Canvas
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  Loaded="onLoaded">

  <TextBlock x:Name="myTextBlock" />

</Canvas>

function onLoaded(sender, eventArgs)
{
    // Set the TextBlock to display the current date and time.
    sender.findName("myTextBlock").text = Date();
}

Adding Event Handlers in JavaScript

In addition to adding handlers to objects through the initial XAML, you can also add handlers to objects at run time.

To add and remove event-handler functions for Silverlight objects in JavaScript, use the AddEventListener and RemoveEventListener methods. The following JavaScript example shows how to add events to a TextBlock object.

function onLoaded(sender, eventArgs)
{
    textBlock = sender.findName("Status");
    var entertoken1 = textBlock.addEventListener("MouseEnter", onMouseEnter);
    var leavetoken1 = textBlock.addEventListener("MouseLeave", onMouseLeave);
}

In the preceding example, you might have noticed the "token" return values. In some circumstances, you might want to remove event handlers. You might do this if you intend to replace a previously added event handler with a different handling function. To remove an existing event-handler function, use the RemoveEventListener method. The following JavaScript example shows how to remove event handlers for two different events from a TextBlock object.

function removeEvents()
{
    textBlock.removeEventListener("MouseEnter", entertoken1);
    textBlock.removeEventListener("MouseLeave", leavetoken1);
}

Notice how the remove event handler code references the named tokens that were declared as variables in the add event handler code. The tokens are really just integer values. The tokens are returned by the AddEventListener calls because it might be necessary to differentiate handlers if there was more than one handler defined for the same event on the same instance. If you do not intend to remove handlers later, you do not have to store the return value tokens when you call AddEventListener.

You can also remove handlers for cases where the event was added through a XAML event attribute. In the XAML event attribute case, there was no function call that could return a token. However, you can supply the value 0 (zero) for the token parameter to remove an event where the handler was added using a XAML attribute. The tokens represent the order that handlers were added, starting from 0 and counting up. Because the XAML attribute handlers are the first handlers added (parsing of XAML happens before any script can add handlers), and because there can only be one event handler added per event/instance using XAML, a XAML-added event handler's token value is always 0.

Note:

The Gecko DOM supports a DOM method on many elements that is also named AddEventHandler and has a similar conceptual purpose. The Gecko DOM version can be distinguished from the Silverlight AddEventHandler because the Gecko DOM version has three parameters and the Silverlight version has two. You cannot use the Gecko DOM version of AddEventHandler to add handlers for objects in the Silverlight object tree. However, you could use it to add handlers to any elements in your HTML page that are truly in the HTML DOM.

JavaScript HTML DOM Events and Loaded/onload

JavaScript provides a set of events that you can use to respond to changes on the Web page. For example, the following HTML example shows JavaScript code that is triggered by the JavaScript HTML DOM onload event.

<body onload='javascript:alert("onload event generated")'>

In this example, JavaScript code is defined inline, instead of referencing an event-handler function. This is not possible with Silverlight events; you must define and reference functions.

Also, note the name similarity between the onload HTML DOM event, and the Silverlight Loaded. The HTML DOM onload event is not raised until the entire Web page is loaded. This means that any Silverlight plug-in contained within the page raises its Loaded event before the HTML DOM onload event.

Error Events

See Also

Concepts