mochikit_v14/doc/html/MochiKit/Signal.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   7 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
   8 <title>MochiKit.Signal - Simple universal event handling</title>
   9
  10 <link rel="stylesheet" href="../../../include/css/documentation.css" type="text/css" />
  11 <script type="text/javascript" src="../../../packed/MochiKit/MochiKit.js"></script>
  12 <script type="text/javascript" src="../../js/toc.js"></script>
  13 </head>
  14 <body>
  15 <div class="document">
  16 <div class="section">
  17 <h1><a id="name" name="name">Name</a></h1>
  18 <p>MochiKit.Signal - Simple universal event handling</p>
  19 </div>
  20 <div class="section">
  21 <h1><a id="synopsis" name="synopsis">Synopsis</a></h1>
  22 <p>Signal for DOM events:</p>
  23 <pre class="literal-block">
  24 // DOM events are also signals. Connect freely! The functions will be
  25 // called with the custom event as a parameter.
  26
  27 // calls myClicked.apply(getElement('myID'), [event])
  28 connect('myID', 'onclick', myClicked);
  29
  30 // calls wasClicked.apply(myObject, [event])
  31 connect('myID', 'onclick', myObject, wasClicked);
  32
  33 // calls myObject.wasClicked(event)
  34 connect('myID', 'onclick', myObject, 'wasClicked');
  35
  36 // the event is normalized, no more e = e || window.event!
  37 myObject.wasClicked = function(e) {
  38     var crossBrowserCoordinates = e.mouse().page;
  39     // e.mouse().page is a MochiKit.Style.Coordinates object
  40 }
  41 </pre>
  42 <p>Signal for non-DOM events:</p>
  43 <pre class="literal-block">
  44 // otherObject.gotFlash() will be called when 'flash' signalled.
  45 connect(myObject, 'flash', otherObject, 'gotFlash');
  46
  47 // gotBang.apply(otherObject, [...]) will be called when 'bang' signalled.
  48 // You can access otherObject from within gotBang as 'this'.
  49 connect(myObject, 'bang', otherObject, gotBang);
  50
  51 // myFunc.apply(myObject, [...]) will be called when 'flash' signalled.
  52 // You can access myObject from within myFunc as 'this'.
  53 var ident = connect(myObject, 'flash', myFunc);
  54
  55 // You may disconnect with the return value from connect
  56 disconnect(ident);
  57
  58 // Signal can take parameters. These will be passed along to the
  59 // connected functions.
  60 signal(myObject, 'flash');
  61 signal(myObject, 'bang', 'BANG!');
  62 </pre>
  63 </div>
  64 <div class="section">
  65 <h1><a id="description" name="description">Description</a></h1>
  66 <p>Event handling was never so easy!</p>
  67 <p>This module takes care of all the hard work—figuring out which
  68 event model to use, trying to retrieve the event object, and handling
  69 your own internal events, as well as cleanup when the page is unloaded
  70 to clean up IE's nasty memory leakage.</p>
  71 <p>This event system is largely based on Qt's signal/slot system. Read
  72 more on how that is handled and also how it is used in model/view
  73 programming at: <a class="reference" href="http://doc.trolltech.com/">http://doc.trolltech.com/</a></p>
  74 </div>
  75 <div class="section">
  76 <h1><a id="dependencies" name="dependencies">Dependencies</a></h1>
  77 <ul class="simple">
  78 <li><a class="mochiref reference" href="Base.html">MochiKit.Base</a></li>
  79 <li><a class="mochiref reference" href="DOM.html">MochiKit.DOM</a></li>
  80 </ul>
  81 </div>
  82 <div class="section">
  83 <h1><a id="overview" name="overview">Overview</a></h1>
  84 <div class="section">
  85 <h2><a id="using-signal-for-dom-events" name="using-signal-for-dom-events">Using Signal for DOM Events</a></h2>
  86 <p>When using MochiKit.Signal, do not use the browser's native event
  87 API. That means, no <tt class="docutils literal"><span class="pre">onclick=&quot;blah&quot;</span></tt>, no
  88 <tt class="docutils literal"><span class="pre">elem.addEventListener(...)</span></tt>, and certainly no
  89 <tt class="docutils literal"><span class="pre">elem.attachEvent(...)</span></tt>. This also means that
  90 <a class="mochiref reference" href="DOM.html#fn-addtocallstack">MochiKit.DOM.addToCallStack</a> and
  91 <a class="mochiref reference" href="DOM.html#fn-addloadevent">MochiKit.DOM.addLoadEvent</a> should not be used in
  92 combination with this module.</p>
  93 <p>Signals for DOM objects are named with the <tt class="docutils literal"><span class="pre">'on'</span></tt> prefix, e.g.:
  94 <tt class="docutils literal"><span class="pre">'onclick'</span></tt>, <tt class="docutils literal"><span class="pre">'onkeyup'</span></tt>, etc.</p>
  95 <p>When the signal fires, your slot will be called with one parameter,
  96 the custom event object.</p>
  97 </div>
  98 <div class="section">
  99 <h2><a id="custom-event-objects-for-dom-events" name="custom-event-objects-for-dom-events">Custom Event Objects for DOM events</a></h2>
 100 <p>Signals triggered by DOM events are called with a custom event object
 101 as a parameter. The custom event object presents a consistent view of
 102 the event across all supported platforms and browsers, and provides
 103 many conveniences not available even in a correct W3C implementation.</p>
 104 <p>See the <a class="reference" href="#dom-custom-event-object-reference">DOM Custom Event Object Reference</a> for a detailed API
 105 description of this object.</p>
 106 <p>If you find that you're accessing the native event for any reason,
 107 create a <a class="reference" href="http://trac.mochikit.com/newticket">new ticket</a> and we'll look into normalizing the behavior
 108 you're looking for.</p>
 109 </div>
 110 <div class="section">
 111 <h2><a id="memory-usage" name="memory-usage">Memory Usage</a></h2>
 112 <p>Any object that has connected slots (via <a class="mochiref reference" href="#fn-connect">connect()</a>) is
 113 referenced by the Signal mechanism until it is disconnected via
 114 <a class="mochiref reference" href="#fn-disconnect">disconnect()</a> or <a class="mochiref reference" href="#fn-disconnectall">disconnectAll()</a>.</p>
 115 <p>Signal does not leak. It registers an <tt class="docutils literal"><span class="pre">'onunload'</span></tt> event that
 116 disconnects all objects on the page when the browser leaves the
 117 page. However, memory usage will grow during the page view for every
 118 connection made until it is disconnected. Even if the DOM object is
 119 removed from the document, it will still be referenced by Signal until
 120 it is explicitly disconnected.</p>
 121 <p>In order to conserve memory during the page view,
 122 <a class="mochiref reference" href="#fn-disconnectall">disconnectAll()</a> any DOM elements that are about to be
 123 removed from the document.</p>
 124 </div>
 125 <div class="section">
 126 <h2><a id="synthesized-events" name="synthesized-events">Synthesized Events</a></h2>
 127 <p>Certain events supported by MochiKit are not generated natively by all
 128 browsers. MochiKit can synthesize these events even for non-supporting
 129 browsers, however, by watching for related events and triggering the
 130 appropriate signals at the right times.</p>
 131 <p>These events include:</p>
 132 <p><tt class="docutils literal"><span class="pre">onmouseenter</span></tt></p>
 133 <blockquote>
 134 <p>Similar to <tt class="docutils literal"><span class="pre">'onmouseover'</span></tt>, but does not &quot;bubble&quot; up to parent
 135 nodes. Such bubbling is often a cause of confusion. On an
 136 <tt class="docutils literal"><span class="pre">'onmouseenter'</span></tt> event, you can be certain that the mouse has
 137 left the node attached to the event.</p>
 138 <dl class="docutils">
 139 <dt><em>Availability:</em></dt>
 140 <dd>Available in MochiKit 1.4+</dd>
 141 </dl>
 142 </blockquote>
 143 <p><tt class="docutils literal"><span class="pre">onmouseleave</span></tt></p>
 144 <blockquote>
 145 <p>Similar to <tt class="docutils literal"><span class="pre">'onmouseout'</span></tt>, but does not &quot;bubble&quot; up to parent
 146 nodes. This is the analog to <tt class="docutils literal"><span class="pre">'onmouseenter'</span></tt>.</p>
 147 <dl class="docutils">
 148 <dt><em>Availability:</em></dt>
 149 <dd>Available in MochiKit 1.4+</dd>
 150 </dl>
 151 </blockquote>
 152 </div>
 153 <div class="section">
 154 <h2><a id="using-signal-for-non-dom-objects" name="using-signal-for-non-dom-objects">Using Signal for non-DOM objects</a></h2>
 155 <p>Signals are triggered with the <a class="mochiref reference" href="#fn-signal">signal(src, 'signal', ...)</a>
 156 function. Additional parameters passed to this are passed onto the
 157 connected slots. Explicit signals are not required for DOM events.</p>
 158 <p>Slots that are connected to a signal are called in the following
 159 manner when that signal is signalled:</p>
 160 <ul class="simple">
 161 <li>If the slot was a single function, then it is called with <tt class="docutils literal"><span class="pre">this</span></tt>
 162 set to the object originating the signal with whatever parameters
 163 it was signalled with.</li>
 164 <li>If the slot was an object and a function, then it is called with
 165 <tt class="docutils literal"><span class="pre">this</span></tt> set to the object, and with whatever parameters it was
 166 signalled with.</li>
 167 <li>If the slot was an object and a string, then <tt class="docutils literal"><span class="pre">object[string]</span></tt> is
 168 called with the parameters to the signal.</li>
 169 </ul>
 170 </div>
 171 </div>
 172 <div class="section">
 173 <h1><a id="api-reference" name="api-reference">API Reference</a></h1>
 174 <div class="section">
 175 <h2><a id="signal-api-reference" name="signal-api-reference">Signal API Reference</a></h2>
 176 <p>
 177 <a name="fn-connect"></a>
 178 <a class="mochidef reference" href="#fn-connect">connect(src, signal, dest[, func])</a>:</p>
 179 <blockquote>
 180 <p>Connects a signal to a slot, and return a unique identifier that
 181 can be used to disconnect that signal.</p>
 182 <p><tt class="docutils literal"><span class="pre">src</span></tt> is the object that has the signal. You may pass in a
 183 string, in which case, it is interpreted as an id for an HTML
 184 element.</p>
 185 <p><tt class="docutils literal"><span class="pre">signal</span></tt> is a string that represents a signal name. If 'src' is
 186 an HTML Element, <tt class="docutils literal"><span class="pre">window</span></tt>, or the <tt class="docutils literal"><span class="pre">document</span></tt>, then it can be
 187 one of the 'on-XYZ' events. You must include the 'on' prefix, and
 188 it must be all lower-case.</p>
 189 <p><tt class="docutils literal"><span class="pre">dest</span></tt> and <tt class="docutils literal"><span class="pre">func</span></tt> describe the slot, or the action to take
 190 when the signal is triggered.</p>
 191 <blockquote>
 192 <ul class="simple">
 193 <li>If <tt class="docutils literal"><span class="pre">dest</span></tt> is an object and <tt class="docutils literal"><span class="pre">func</span></tt> is a string, then
 194 <tt class="docutils literal"><span class="pre">dest[func].apply(dest,</span> <span class="pre">[...])</span></tt> will be called when the
 195 signal is signalled.</li>
 196 <li>If <tt class="docutils literal"><span class="pre">dest</span></tt> is an object and <tt class="docutils literal"><span class="pre">func</span></tt> is a function, then
 197 <tt class="docutils literal"><span class="pre">func.apply(dest,</span> <span class="pre">[...])</span></tt> will be called when the signal
 198 is signalled.</li>
 199 <li>If <tt class="docutils literal"><span class="pre">func</span></tt> is undefined and <tt class="docutils literal"><span class="pre">dest</span></tt> is a function, then
 200 <tt class="docutils literal"><span class="pre">dest.apply(src,</span> <span class="pre">[...])</span></tt> will be called when the signal is
 201 signalled.</li>
 202 </ul>
 203 </blockquote>
 204 <p>No other combinations are allowed and will raise an exception.</p>
 205 <p>The return value can be passed to <a class="mochiref reference" href="#fn-disconnect">disconnect</a> to
 206 disconnect the signal.</p>
 207 <p>In MochiKit 1.4+, if <tt class="docutils literal"><span class="pre">src</span></tt> is an object that has a <tt class="docutils literal"><span class="pre">__connect__</span></tt>
 208 method, then <tt class="docutils literal"><span class="pre">src.__connect__(ident,</span> <span class="pre">signal,</span> <span class="pre">objOrFunc,</span> <span class="pre">funcOrStr)</span></tt>
 209 will be called. This method may be used to disconnect the signal.
 210 DOM objects can not implement this feature.</p>
 211 <dl class="docutils">
 212 <dt><em>Availability</em>:</dt>
 213 <dd>Available in MochiKit 1.3.1+</dd>
 214 </dl>
 215 </blockquote>
 216 <p>
 217 <a name="fn-disconnect"></a>
 218 <a class="mochidef reference" href="#fn-disconnect">disconnect(ident)</a>:</p>
 219 <blockquote>
 220 <p>To disconnect a signal, pass its ident returned by
 221 <a class="mochiref reference" href="#fn-connect">connect()</a>.  This is similar to how the browser's
 222 <tt class="docutils literal"><span class="pre">setTimeout</span></tt> and <tt class="docutils literal"><span class="pre">clearTimeout</span></tt> works.</p>
 223 <dl class="docutils">
 224 <dt><em>Availability</em>:</dt>
 225 <dd>Available in MochiKit 1.3.1+</dd>
 226 </dl>
 227 </blockquote>
 228 <p>
 229 <a name="fn-disconnectall"></a>
 230 <a class="mochidef reference" href="#fn-disconnectall">disconnectAll(src[, signal, ...])</a>:</p>
 231 <blockquote>
 232 <p><tt class="docutils literal"><span class="pre">disconnectAll(src)</span></tt> removes all signals from src.</p>
 233 <p><tt class="docutils literal"><span class="pre">disconnectAll(src,</span> <span class="pre">'onmousedown',</span> <span class="pre">'mySignal')</span></tt> will remove all
 234 <tt class="docutils literal"><span class="pre">'onmousedown'</span></tt> and <tt class="docutils literal"><span class="pre">'mySignal'</span></tt> signals from src.</p>
 235 <dl class="docutils">
 236 <dt><em>Availability</em>:</dt>
 237 <dd>Available in MochiKit 1.3.1+</dd>
 238 </dl>
 239 </blockquote>
 240 <p>
 241 <a name="fn-disconnectallto"></a>
 242 <a class="mochidef reference" href="#fn-disconnectallto">disconnectAllTo(dest[, func])</a>:</p>
 243 <blockquote>
 244 <p><tt class="docutils literal"><span class="pre">disconnectAllTo(dest)</span></tt> removes all signals connected to dest.</p>
 245 <p><tt class="docutils literal"><span class="pre">disconnectAllTo(dest,</span> <span class="pre">func)</span></tt> will remove all
 246 signals connected to dest using func.</p>
 247 <dl class="docutils">
 248 <dt><em>Availability</em>:</dt>
 249 <dd>Available in MochiKit 1.4+</dd>
 250 </dl>
 251 </blockquote>
 252 <p>
 253 <a name="fn-signal"></a>
 254 <a class="mochidef reference" href="#fn-signal">signal(src, signal, ...)</a>:</p>
 255 <blockquote>
 256 <p>This will signal a signal, passing whatever additional parameters
 257 on to the connected slots. <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">signal</span></tt> are the same as
 258 for <a class="mochiref reference" href="#fn-connect">connect()</a>.</p>
 259 <dl class="docutils">
 260 <dt><em>Availability</em>:</dt>
 261 <dd>Available in MochiKit 1.3.1+</dd>
 262 </dl>
 263 </blockquote>
 264 </div>
 265 <div class="section">
 266 <h2><a id="dom-custom-event-object-reference" name="dom-custom-event-object-reference">DOM Custom Event Object Reference</a></h2>
 267 <p>
 268 <a name="fn-event"></a>
 269 <a class="mochidef reference" href="#fn-event">event()</a>:</p>
 270 <blockquote>
 271 <p>The native event produced by the browser. You should not need to
 272 use this.</p>
 273 <dl class="docutils">
 274 <dt><em>Availability</em>:</dt>
 275 <dd>Available in MochiKit 1.3.1+</dd>
 276 </dl>
 277 </blockquote>
 278 <p>
 279 <a name="fn-src"></a>
 280 <a class="mochidef reference" href="#fn-src">src()</a>:</p>
 281 <blockquote>
 282 <p>The element that this signal is connected to.</p>
 283 <dl class="docutils">
 284 <dt><em>Availability</em>:</dt>
 285 <dd>Available in MochiKit 1.3.1+</dd>
 286 </dl>
 287 </blockquote>
 288 <p>
 289 <a name="fn-type"></a>
 290 <a class="mochidef reference" href="#fn-type">type()</a>:</p>
 291 <blockquote>
 292 <p>The event type (<tt class="docutils literal"><span class="pre">'click'</span></tt>, <tt class="docutils literal"><span class="pre">'mouseover'</span></tt>, <tt class="docutils literal"><span class="pre">'keypress'</span></tt>,
 293 etc.) as a string. Does not include the <tt class="docutils literal"><span class="pre">'on'</span></tt> prefix.</p>
 294 <dl class="docutils">
 295 <dt><em>Availability</em>:</dt>
 296 <dd>Available in MochiKit 1.3.1+</dd>
 297 </dl>
 298 </blockquote>
 299 <p>
 300 <a name="fn-target"></a>
 301 <a class="mochidef reference" href="#fn-target">target()</a>:</p>
 302 <blockquote>
 303 <p>The element that triggered the event. This may be a child of
 304 <a class="mochiref reference" href="#fn-src">src()</a>.</p>
 305 <dl class="docutils">
 306 <dt><em>Availability</em>:</dt>
 307 <dd>Available in MochiKit 1.3.1+</dd>
 308 </dl>
 309 </blockquote>
 310 <p>
 311 <a name="fn-modifier"></a>
 312 <a class="mochidef reference" href="#fn-modifier">modifier()</a>:</p>
 313 <blockquote>
 314 <p>Returns <tt class="docutils literal"><span class="pre">{shift,</span> <span class="pre">ctrl,</span> <span class="pre">meta,</span> <span class="pre">alt,</span> <span class="pre">any}</span></tt>, where each property is
 315 <tt class="docutils literal"><span class="pre">true</span></tt> if its respective modifier key was pressed, <tt class="docutils literal"><span class="pre">false</span></tt>
 316 otherwise. <tt class="docutils literal"><span class="pre">any</span></tt> is <tt class="docutils literal"><span class="pre">true</span></tt> if any modifier is pressed,
 317 <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
 318 <dl class="docutils">
 319 <dt><em>Availability</em>:</dt>
 320 <dd>Available in MochiKit 1.3.1+</dd>
 321 </dl>
 322 </blockquote>
 323 <p>
 324 <a name="fn-stoppropagation"></a>
 325 <a class="mochidef reference" href="#fn-stoppropagation">stopPropagation()</a>:</p>
 326 <blockquote>
 327 <p>Works like W3C's <a class="reference" href="http://developer.mozilla.org/en/docs/DOM:event.stopPropagation">stopPropagation()</a>.</p>
 328 <dl class="docutils">
 329 <dt><em>Availability</em>:</dt>
 330 <dd>Available in MochiKit 1.3.1+</dd>
 331 </dl>
 332 </blockquote>
 333 <p>
 334 <a name="fn-preventdefault"></a>
 335 <a class="mochidef reference" href="#fn-preventdefault">preventDefault()</a>:</p>
 336 <blockquote>
 337 <p>Works like W3C's <a class="reference" href="http://developer.mozilla.org/en/docs/DOM:event.preventDefault">preventDefault()</a>.</p>
 338 <dl class="docutils">
 339 <dt><em>Availability</em>:</dt>
 340 <dd>Available in MochiKit 1.3.1+</dd>
 341 </dl>
 342 </blockquote>
 343 <p>
 344 <a name="fn-stop"></a>
 345 <a class="mochidef reference" href="#fn-stop">stop()</a>:</p>
 346 <blockquote>
 347 <p>Shortcut that calls <tt class="docutils literal"><span class="pre">stopPropagation()</span></tt> and
 348 <tt class="docutils literal"><span class="pre">preventDefault()</span></tt>.</p>
 349 <dl class="docutils">
 350 <dt><em>Availability</em>:</dt>
 351 <dd>Available in MochiKit 1.3.1+</dd>
 352 </dl>
 353 </blockquote>
 354 <p>
 355 <a name="fn-key"></a>
 356 <a class="mochidef reference" href="#fn-key">key()</a>:</p>
 357 <blockquote>
 358 <p>Returns <tt class="docutils literal"><span class="pre">{code,</span> <span class="pre">string}</span></tt>.</p>
 359 <p>Use <tt class="docutils literal"><span class="pre">'onkeydown'</span></tt> and <tt class="docutils literal"><span class="pre">'onkeyup'</span></tt> handlers to detect control
 360 characters such as <tt class="docutils literal"><span class="pre">'KEY_F1'</span></tt>. Use the <tt class="docutils literal"><span class="pre">'onkeypress'</span></tt>
 361 handler to detect &quot;printable&quot; characters, such as <tt class="docutils literal"><span class="pre">'é'</span></tt>.</p>
 362 <p>When a user presses F1, in <tt class="docutils literal"><span class="pre">'onkeydown'</span></tt> and <tt class="docutils literal"><span class="pre">'onkeyup'</span></tt> this
 363 method returns <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">122,</span> <span class="pre">string:</span> <span class="pre">'KEY_F1'}</span></tt>. In
 364 <tt class="docutils literal"><span class="pre">'onkeypress'</span></tt>, it returns <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">0,</span> <span class="pre">string:</span> <span class="pre">''}</span></tt>.</p>
 365 <p>If a user presses Shift+2 on a US keyboard, this method returns
 366 <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">50,</span> <span class="pre">string:</span> <span class="pre">'KEY_2'}</span></tt> in <tt class="docutils literal"><span class="pre">'onkeydown'</span></tt> and
 367 <tt class="docutils literal"><span class="pre">'onkeyup'</span></tt>.  In <tt class="docutils literal"><span class="pre">'onkeypress'</span></tt>, it returns <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">64,</span>
 368 <span class="pre">string:</span> <span class="pre">'&#64;'}</span></tt>.</p>
 369 <p>See <tt class="docutils literal"><span class="pre">_specialKeys</span></tt> in the source code for a comprehensive list
 370 of control characters.</p>
 371 <dl class="docutils">
 372 <dt><em>Availability</em>:</dt>
 373 <dd>Available in MochiKit 1.3.1+</dd>
 374 </dl>
 375 </blockquote>
 376 <p>
 377 <a name="fn-mouse"></a>
 378 <a class="mochidef reference" href="#fn-mouse">mouse()</a>:</p>
 379 <blockquote>
 380 <p>Properties for <tt class="docutils literal"><span class="pre">'onmouse*'</span></tt>, <tt class="docutils literal"><span class="pre">'onclick'</span></tt>, <tt class="docutils literal"><span class="pre">'ondblclick'</span></tt>,
 381 and <tt class="docutils literal"><span class="pre">'oncontextmenu'</span></tt>:</p>
 382 <blockquote>
 383 <ul class="simple">
 384 <li><tt class="docutils literal"><span class="pre">page</span></tt> is a <a class="mochiref reference" href="Style.html#fn-coordinates">MochiKit.Style.Coordinates</a> object
 385 that represents the cursor position relative to the HTML
 386 document.  Equivalent to <tt class="docutils literal"><span class="pre">pageX</span></tt> and <tt class="docutils literal"><span class="pre">pageY</span></tt> in
 387 Safari, Mozilla, and Opera.</li>
 388 <li><tt class="docutils literal"><span class="pre">client</span></tt> is a <a class="mochiref reference" href="Style.html#fn-coordinates">MochiKit.Style.Coordinates</a>
 389 object that represents the cursor position relative to the
 390 visible portion of the HTML document. Equivalent to
 391 <tt class="docutils literal"><span class="pre">clientX</span></tt> and <tt class="docutils literal"><span class="pre">clientY</span></tt> on all browsers. Current versions of
 392 Safari incorrectly return clientX as relative to the canvas
 393 instead of relative to the viewport (<a class="reference" href="http://bugs.webkit.org/show_bug.cgi?id=8707">Safari Bug 8707</a>).</li>
 394 </ul>
 395 </blockquote>
 396 <p>Properties for <tt class="docutils literal"><span class="pre">'onmouseup'</span></tt>, <tt class="docutils literal"><span class="pre">'onmousedown'</span></tt>, <tt class="docutils literal"><span class="pre">'onclick'</span></tt>,
 397 and <tt class="docutils literal"><span class="pre">'ondblclick'</span></tt>:</p>
 398 <blockquote>
 399 <ul class="simple">
 400 <li><tt class="docutils literal"><span class="pre">mouse().button</span></tt> returns <tt class="docutils literal"><span class="pre">{left,</span> <span class="pre">right,</span> <span class="pre">middle}</span></tt> where
 401 each property is <tt class="docutils literal"><span class="pre">true</span></tt> if the mouse button was pressed,
 402 <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</li>
 403 </ul>
 404 </blockquote>
 405 <p>Known browser bugs:</p>
 406 <blockquote>
 407 <ul>
 408 <li><p class="first">Current versions of Safari won't signal <tt class="docutils literal"><span class="pre">'ondblclick'</span></tt>
 409 when attached via <tt class="docutils literal"><span class="pre">connect()</span></tt> (<a class="reference" href="http://bugs.webkit.org/show_bug.cgi?id=7790">Safari Bug 7790</a>).</p>
 410 </li>
 411 <li><p class="first">In Safari &lt; 2.0.4, calling <tt class="docutils literal"><span class="pre">preventDefault()</span></tt> or <tt class="docutils literal"><span class="pre">stop()</span></tt>
 412 in <tt class="docutils literal"><span class="pre">'onclick'</span></tt> events signalled from <tt class="docutils literal"><span class="pre">&lt;a&gt;</span></tt> tags does not
 413 prevent the browser from following those links.</p>
 414 </li>
 415 <li><p class="first">Mac browsers don't report right-click consistently. Firefox
 416 signals the slot and sets <tt class="docutils literal"><span class="pre">modifier().ctrl</span></tt> to true,
 417 Opera signals the slot and sets <tt class="docutils literal"><span class="pre">modifier().meta</span></tt> to
 418 <tt class="docutils literal"><span class="pre">true</span></tt>, and Safari doesn't signal the slot at all
 419 (<a class="reference" href="http://bugs.webkit.org/show_bug.cgi?id=6595">Safari Bug 6595</a>).</p>
 420 <p>To find a right-click in Safari, Firefox, and IE, you can
 421 connect an element to <tt class="docutils literal"><span class="pre">'oncontextmenu'</span></tt>. This doesn't
 422 work in Opera.</p>
 423 </li>
 424 </ul>
 425 </blockquote>
 426 <dl class="docutils">
 427 <dt><em>Availability</em>:</dt>
 428 <dd>Available in MochiKit 1.3.1+</dd>
 429 </dl>
 430 </blockquote>
 431 <p>
 432 <a name="fn-relatedtarget"></a>
 433 <a class="mochidef reference" href="#fn-relatedtarget">relatedTarget()</a>:</p>
 434 <blockquote>
 435 <p>Returns the document element that the mouse has moved to. This is
 436 generated for <tt class="docutils literal"><span class="pre">'onmouseover'</span></tt> and <tt class="docutils literal"><span class="pre">'onmouseout'</span></tt> events.</p>
 437 <dl class="docutils">
 438 <dt><em>Availability</em>:</dt>
 439 <dd>Available in MochiKit 1.3.1+</dd>
 440 </dl>
 441 </blockquote>
 442 <p>
 443 <a name="fn-confirmunload"></a>
 444 <a class="mochidef reference" href="#fn-confirmunload">confirmUnload(msg)</a>:</p>
 445 <blockquote>
 446 <p>In browsers that support the <tt class="docutils literal"><span class="pre">'onbeforeunload'</span></tt> event (IE and
 447 Firefox), calling this in the event handler will show a dialog box
 448 that allows the user to confirm or cancel the navigation away from
 449 the page.</p>
 450 <dl class="docutils">
 451 <dt><em>Availability</em>:</dt>
 452 <dd>Available in MochiKit 1.4+</dd>
 453 </dl>
 454 </blockquote>
 455 </div>
 456 </div>
 457 <div class="section">
 458 <h1><a id="authors" name="authors">Authors</a></h1>
 459 <ul class="simple">
 460 <li>Jonathan Gardner &lt;<a class="reference" href="mailto:jgardner&#64;jonathangardner.net">jgardner&#64;jonathangardner.net</a>&gt;</li>
 461 <li>Beau Hartshorne &lt;<a class="reference" href="mailto:beau&#64;hartshornesoftware.com">beau&#64;hartshornesoftware.com</a>&gt;</li>
 462 <li>Bob Ippolito &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;</li>
 463 </ul>
 464 </div>
 465 <div class="section">
 466 <h1><a id="copyright" name="copyright">Copyright</a></h1>
 467 <p>Copyright 2006 Jonathan Gardner &lt;<a class="reference" href="mailto:jgardner&#64;jonathangardner.net">jgardner&#64;jonathangardner.net</a>&gt;, Beau
 468 Hartshorne &lt;<a class="reference" href="mailto:beau&#64;hartshornesoftware.com">beau&#64;hartshornesoftware.com</a>&gt;, and Bob Ippolito
 469 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;.  This program is dual-licensed free software; you
 470 can redistribute it and/or modify it under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT
 471 License</a> or the <a class="reference" href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License v2.1</a>.</p>
 472 </div>
 473 </div>
 474
 475 </body>
 476 </html>