Commit | Line | Data |
---|---|---|
6a1aa64f DV |
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="blah"</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 "bubble" 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 "bubble" 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 "printable" 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">'@'}</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 < 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"><a></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 <<a class="reference" href="mailto:jgardner@jonathangardner.net">jgardner@jonathangardner.net</a>></li> | |
461 | <li>Beau Hartshorne <<a class="reference" href="mailto:beau@hartshornesoftware.com">beau@hartshornesoftware.com</a>></li> | |
462 | <li>Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>></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 <<a class="reference" href="mailto:jgardner@jonathangardner.net">jgardner@jonathangardner.net</a>>, Beau | |
468 | Hartshorne <<a class="reference" href="mailto:beau@hartshornesoftware.com">beau@hartshornesoftware.com</a>>, and Bob Ippolito | |
469 | <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>>. 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> |