Share via

AddEventListener Method

  • Article

Registers an event listener on the event target object.

XAML
Cannot use methods in XAML.
Scripting
[token = ]object.AddEventListener(eventName, functionReference)

Parameters

eventName

string

The name of the event, such as "KeyDown". This is a true string, and the value must be quoted. An exception is thrown if eventName is invalid (not a known event name).
functionReference

object

A reference to the event handler function. Specifying the name of an existing function (without quotes) will create a delegate that fills this object reference.

-or-

The name of an existing function, with quotes. See Remarks.

Return Value

integer

A token that is returned from the function, which you can optionally retain as a variable. If you intend to call RemoveEventListener to remove the handler, you will need this token.

Remarks

The AddEventListener method registers an event listener on a UIElement-derived object, such as a Canvas or Image. The event handler function that is defined as the event listener receives a notification when the specified eventType occurs.

The alternative syntax that specifies the event handler as a quoted string was originally for Safari browsers, which did not have the ability in the browser object model to retain handler references. You can still use the quoted string syntax as an option; the quoted string syntax effectively parallels the mechanism that is used to add the handlers that are declared as XAML attributes. When you use the quoted string syntax, you are not obligated to use the token in calls to RemoveEventListener. Instead, you can also specify the second parameter of RemoveEventListener as a quoted string of the handler name. Instead of the retained token, you can specify the second parameter of RemoveEventListener as a quoted string of the handler name. To explicitly remove handlers that were added through XAML, you can either specify the handler name as a string, or use a token value of 0 (handlers from XAML always have that token value).

Note  The Silverlight implementation of AddEventListener is different from the HTML Document Object Model (DOM) version of the same name. The DOM version provides an additional third parameter that enables event capture.

Another important difference from the HTML DOM is that the the Silverlight implementation of AddEventListener will register multiple identical event listeners if provided. The event listener is called as many times as it was added. If there are multiples, a RemoveEventListener call removes only one of the instances, not all of them.

The AddEventListener method returns a token. Often you do not need this token, so you can call this method without storing the return value. However, if you plan to remove the event handler at some later point in your code, by calling RemoveEventListener, and you have added multiple listeners to the same event using scripting, you should retain this token.

Use the RemoveEventListener method to remove a functionReference that has been added using the AddEventListener method.

The token is just an integer value to track the order in which handlers were added for each object-event combination. Therefore, if you are certain that your code has added only one handler, you can pass 0 as the token value rather than storing it as a token.

Examples

The following JavaScript example shows how to define a Silverlight keyboard event by using the AddEventListener method:

JavaScript 
function onLoaded(sender, eventArgs)
{
    // Set the root Canvas object to a KeyDown event handler function.
    var token = sender.addEventListener("keyDown", onKeyDown);
}
function onKeyDown(sender, keyEventArgs)
{
    // Determine whether the keystroke combination CTRL+V was detected.
    if ((keyEventArgs.key == 51) && (keyEventArgs.ctrl == true))
    {
        // Retrieve a reference to the plug-in.
        var slPlugin = sender.getHost();
        // Display the current version of the plug-in.
        alert("Silverlight version: " + slPlugin.isVersionSupported("1.0"));
    }
}

The following Javascript example shows how to remove a Silverlight event handler function for the KeyDown event. The token variable in the previous example is used here to fill the second parameter of the RemoveEventListener method.

JavaScript 
function onCleanUp()
{
    // Remove the KeyDown event handler function from the root Canvas object.
    sender.removeEventListener("keyDown", token);
}

Applies To

Canvas, Ellipse, Glyphs, Image, InkPresenter, Line, MediaElement, Path, Polygon, Polyline, Rectangle, TextBlock

See Also

Silverlight Events
RemoveEventListener