發行項
06/13/2011

RemoveEventListener

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

Unregisters an event listener on the event target object.

object.RemoveEventListener(eventName, token) 
-or-
object.RemoveEventListener(eventName, functionName)

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 exception is thrown if eventName is invalid (it is not a known event name).

token

integer

A token that is returned from an AddEventListener call. If you have no token and/or the handler was added in XAML, you can pass 0.

functionName

string

The name of the event-handler function. This syntax only works in two cases: when the handler was added in XAML, or when the original AddEventListener call that added the handler used a quoted string instead of a delegate reference.

Managed Equivalent

None

Remarks

The AddEventListener method returns a token. Usually, 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, and you have added multiple listeners to the same event using scripting, you should retain this token.

The alternative AddEventListener 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; it 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 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).

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

Note:
The Silverlight implementation of RemoveEventListener is different from the HTML Document Object Model (DOM) method that has 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 multiples, a RemoveEventListener call removes only one of the instances, not all of them.

Example

The following JavaScript example shows how to remove events from a TextBlock object, using tokens that were obtained from earlier AddEventListener calls and stored as variables.

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