<html dir="ltr" xmlns:mshelp="http://msdn.microsoft.com/mshelp"
xmlns:silverlightsdk="http://msdn.microsoft.com/silverlight" xmlns=
"http://www.w3.org/1999/xhtml">
<head>
<meta name="keywords" content="online documentation, web online help, web help, chm2web" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="chm2web Standard 2.7 (unicode)" />
<meta http-equiv="Content-Type" content=
"text/html; charset=utf-8" />
<title>AddEventListener Method</title>
<link rel="stylesheet" href="../../default.css" type="text/css" />
<script type="text/JavaScript" src="../../files/supply.js"></script>
<script type="text/JavaScript">
chmtop.c2wtopf.pageid = "reference/m_uielement_addeventlistener.htm";
</script>
</head>
<body topmargin="0"><script type="text/JavaScript">
if (window.name != "content")
document.write(" <table width=\"100%\" bgcolor=\"#e1e1e1\"cellspacing=\"2\" cellpadding=\"0\" style=\"border-collapse: collapse; font-family: sans-serif; font-size: 14px; color: #000000; text-decoration: none; \"> <tr> <td align=\"center\" style=\"border-bottom: 2px solid gray\" > <br> Click <a href=\"../../index.html?page=source%2freference%2fm_uielement_addeventlistener.htm\">here</a> to show toolbars of the Web Online Help System: <a href=\"../../index.html?page=source%2freference%2fm_uielement_addeventlistener.htm\">show toolbars</a><br> </td></tr></table><br> ");
</script>
<!-- !chm2web! -->
<span id="sdkbannersection"></span>
<div class="tableSection"><span id="sdkbannersection"></span>
<table class="buttonbarshade" cellspacing="0">
<tr>
<td> </td>
</tr>
</table>
</div>
<div class="tableSection"><span id="sdkbannersection"></span>
<table class="buttonbartable" cellspacing="0">
<tr id="hdr">
<td class="runninghead" nowrap="nowrap"><img src=
"../common/logo.png" height="21" alt="Silverlight SDK" />
</td>
</tr>
</table>
</div>
<p><span class="betaboilerplate"><font color="gray" pointsize="8.5"
face="Verdana">[This topic is pre-release documentation and is
subject to change in future releases. Blank topics are included as
placeholders.]</font></span>
</p>
<h1><a name=
"silverlight_uielement_addeventlistner_method"></a>AddEventListener
Method</h1>
<div id="mainSection">
<div id="mainBody">
<p>Registers an event listener on the event target object.</p>
<div id="syntaxblock">
<table class="auto_syntaxtable" id="syntaxtable" style=
"width: 90%; background: #CCCCCC; border: none;">
<tr id="xamlSyntaxBlock">
<th class="syntaxblocklanguage" nowrap="nowrap" style=
"width: 150px; background: #EEEEEE; vertical-align: top;">XAML</th>
<td class="syntaxblockcode" style="background:white;">
<div class="codesyntax">You cannot use methods in XAML.</div>
</td>
</tr>
<tr id="scriptingSyntaxBlock">
<th class="syntaxblocklanguage" nowrap="nowrap" style=
"width: 150px; background: #EEEEEE; vertical-align: top;">
Scripting</th>
<td class="syntaxblockcode" style="background:white;">
<div class="codesyntax" style=
"font-family: 'Courier New', Courier, monospace;">[<i>token</i> =
]<i>object</i>.<b>addEventListener</b>(<i>eventType</i>,
<i>functionReference</i>)</div>
</td>
</tr>
</table>
</div>
<div id="returnvaluesection">
<div id="parametersection">
<h4>Parameters</h4>
<div class="tableSection">
<table class="parametertable" id="table1">
<tr>
<td class="parametername"><i>eventType</i>
</td>
<td class="parameterdesc"><b>String</b>
<p>The type of event, such as "KeyDown". This is a true string, and
the value must be quoted. An exception is thrown if
<i>eventType</i> is invalid.</p>
</td>
</tr>
<tr>
<td class="parametername"><i>functionReference</i>
</td>
<td class="parameterdesc"><b>Object</b>
<p>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.</p>
<p><b>-or-</b>
</p>
<p>The name of an existing function, with quotes. See Remarks.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<h4>Return Value</h4>
<b>Integer</b>
<p>A token that is returned from the function, which you can
optionally retain as a variable. If you intend to call <a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a> to
remove the handler, you will need this token.</p>
<h4>Remarks</h4>
<p>The <b>AddEventListener</b> method allows you to registers an
event listener on a <a href="o_uielement.htm">UIElement</a>-derived
object, such as a <a href="o_canvas.htm">Canvas</a> or <a href=
"o_image.htm">Image</a>. The event handler function that is defined
as the event listener receives a notification when the specified
<i>eventType</i> occurs.</p>
<p>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 <a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a>.
Instead, you can also specify the second parameter of <a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a> as a
quoted string of the handler name. Instead of the retained token,
you can specify the second parameter of <b>RemoveEventListener</b>
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).</p>
<p>The following JavaScript example shows how to define a
Silverlight keyboard event by using the <b>AddEventListener</b>
method:</p>
<div class="snippetdistributor_codesnippet" id=
"events_reference_snip#EventsReferenceEventListenersAddHandlers">
<div style="width: 99%;">
<table class="codeexampletable" style=
"border: 1px solid #999999; background: #CCCCCC; width: 99%;">
<tr>
<th class="codelanguagecell" style=
"background: #CCCCCC; text-align: left;">JavaScript</th>
</tr>
<tr>
<td class="codeblockcell" style=
"background: #e6e6e6; border: none;">
<pre class="codeblock" style=
"background: transparent; border: none; margin: 0px; padding: 0px; font-family:'Courier New', Courier, monospace;">
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 plugin.
var slPlugin = sender.getHost();
// Display the current version of the plugin.
alert("Silverlight version: " + slPlugin.settings.version);
}
}
</pre>
</td>
</tr>
</table>
</div>
</div>
<p class="note"><b>Note</b> The Silverlight
implementation of <b>AddEventListener</b> 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.</p>
<!-- <p>If multiple identical event listeners are registered on the same event
target with the same parameters, the duplicate instances are discarded. They
do not cause the event listener to be called twice, and since they are
discarded, they do not need to be removed with the <b>RemoveEventListener</b>
method.</p>-->
<p>Another important difference from the HTML DOM is that the the
Silverlight implementation of <b>AddEventListener</b> 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
<b>RemoveEventListener</b> call removes only one of the instances,
not all of them.</p>
<p>The <b>AddEventListener</b> 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 <a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a>, and
you have added multiple listeners to the same event using
scripting, you should retain this token.</p>
<p>Use the <a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a>
method to remove a <i>functionReference</i> that has been added
using the <b>AddEventListener</b> method. The following Javascript
example shows how to remove a Silverlight event handler function
for the <b>KeyDown</b> event. The <i>token</i> variable in the
previous example is used here to fill the second parameter of the
<a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a>
method.</p>
<div class="snippetdistributor_codesnippet" id=
"events_reference_snip#EventsReferenceEventListenersRemoveHandlers">
<div style="width: 99%;">
<table class="codeexampletable" style=
"border: 1px solid #999999; background: #CCCCCC; width: 99%;">
<tr>
<th class="codelanguagecell" style=
"background: #CCCCCC; text-align: left;">JavaScript</th>
</tr>
<tr>
<td class="codeblockcell" style=
"background: #e6e6e6; border: none;">
<pre class="codeblock" style=
"background: transparent; border: none; margin: 0px; padding: 0px; font-family:'Courier New', Courier, monospace;">
function onCleanUp()
{
// Remove the KeyDown event handler function from the root Canvas object.
sender.removeEventListener("keyDown", token);
}
</pre>
</td>
</tr>
</table>
</div>
</div>
<p>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.</p>
<h4>Applies To</h4>
<p><a href="o_canvas.htm">Canvas</a>, <a href=
"o_ellipse.htm">Ellipse</a>, <a href="o_glyphs.htm">Glyphs</a>,
<a href="o_image.htm">Image</a>, <a href="o_line.htm">Line</a>,
<a href="o_linebreak.htm">LineBreak</a>, <a href=
"o_mediaelement.htm">MediaElement</a>, <a href=
"o_path.htm">Path</a>, <a href="o_polygon.htm">Polygon</a>,
<a href="o_polyline.htm">Polyline</a>, <a href=
"o_rectangle.htm">Rectangle</a>, <a href="o_run.htm">Run</a>,
<a href="o_shape.htm">Shape</a>, <a href=
"o_textblock.htm">TextBlock</a>, <a href=
"o_uielement.htm">UIElement</a></p>
<h4>See Also</h4>
<p><a href=
"m_uielement_removeeventlistener.htm">RemoveEventListener</a>
</p>
</div>
</div>
<script type="text/JavaScript">
var fe = FindFrame("toc", top);
if ((fe != null) && (chmtop.c2wtopf.jstree != null)) {
if (chmtop.c2wtopf.FITEMS[chmtop.c2wtopf.pagenum] != chmtop.c2wtopf.pageid)
chmtop.c2wtopf.jstree.OpenTreeNode("source/" + chmtop.c2wtopf.pageid);
}
</script>
<!-- CHM2WEB -->
<!-- DO NOT DELETE OR MODIFY THIS CODE WITHOUT
WRITTEN PERMISSION OF A!K RESEARCH LABS -->
<table width="100%" cellspacing="0" cellpadding="0"
style="margin-top: 0pt; border-collapse: collapse;">
<tr> <td align="right" style="background-color:white; border-top: 1px solid gray;">
<a href="http://chm2web.aklabs.com" target="_blank" style="font-family: sans-serif; font-size: 11px; text-decoration: none;"><font color="gray">Converted from CHM to HTML with <b>chm2web Standard 2.7 (unicode)</b></font></a>
</td></tr></table>
<!-- /CHM2WEB -->
</body>
</html>