Article
06/13/2011

AddEventListener

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

Registers an event listener on the event target object.

[token = ]object.AddEventListener(eventName, functionReference)

Arguments

eventName

string

The name of the event, such as "KeyDown". This is a true string, and the value must be enclosed in quotation marks. An error occurs 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 quotation marks) will create a delegate that fills this object reference.

-or-

The name of an existing function, enclosed in quotation marks. For more information, see the Remarks section.

Return Value

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.

Managed Equivalent

No direct equivalent. Adding and removing event handlers is either a language intrinsic or is accomplished through language-specific utility methods.

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 string (enclosed in quotation marks) 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 the RemoveEventListener method. 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) method 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 Silverlight implementation of AddEventListener will register multiple identical event listeners, if they are provided. The event listener is called as many times as it was added. If there are multiple handlers registered, a RemoveEventListener call removes only one of the instances, not all of them.

The AddEventListener method returns a token. If you do not intend to remove event handlers during the application lifetime, 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 by using scripting, you should retain this token.

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

The token is an integer value that is used 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.

Example

The following JavaScript example shows how to define a Silverlight keyboard event by using the AddEventListener method. Upon initial response of the event, the handler is then removed with the RemoveEventListener method.

var token;
function onLoaded(sender, eventArgs)
{
    // Set the root Canvas object to a KeyDown event-handler function.
    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 example uses the token variable from the previous example to fill the second parameter of the RemoveEventListener method and then uses sender to pass the root Canvas.

function onCleanUp(sender)
{
    // Remove the KeyDown event-handler function from the caller, referencing the global token.
    sender.removeEventListener("keyDown", token);
}