Debian Codegraph @

closure-library/closure/goog/events/events.js

raw
1 // Copyright 2005 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview An event manager for both native browser event
17 * targets and custom JavaScript event targets
18 * ({@code goog.events.Listenable}). This provides an abstraction
19 * over browsers' event systems.
20 *
21 * It also provides a simulation of W3C event model's capture phase in
22 * Internet Explorer (IE 8 and below). Caveat: the simulation does not
23 * interact well with listeners registered directly on the elements
24 * (bypassing goog.events) or even with listeners registered via
25 * goog.events in a separate JS binary. In these cases, we provide
26 * no ordering guarantees.
27 *
28 * The listeners will receive a "patched" event object. Such event object
29 * contains normalized values for certain event properties that differs in
30 * different browsers.
31 *
32 * Example usage:
33 * <pre>
34 * goog.events.listen(myNode, 'click', function(e) { alert('woo') });
35 * goog.events.listen(myNode, 'mouseover', mouseHandler, true);
36 * goog.events.unlisten(myNode, 'mouseover', mouseHandler, true);
37 * goog.events.removeAll(myNode);
38 * </pre>
39 *
40 * in IE and event object patching]
41 * @author [email protected] (Erik Arvidsson)
42 *
43 * @see ../demos/events.html
44 * @see ../demos/event-propagation.html
45 * @see ../demos/stopevent.html
46 */
47
48 // IMPLEMENTATION NOTES:
49 // goog.events stores an auxiliary data structure on each EventTarget
50 // source being listened on. This allows us to take advantage of GC,
51 // having the data structure GC'd when the EventTarget is GC'd. This
52 // GC behavior is equivalent to using W3C DOM Events directly.
53
54 goog.provide('goog.events');
55 goog.provide('goog.events.CaptureSimulationMode');
56 goog.provide('goog.events.Key');
57 goog.provide('goog.events.ListenableType');
58
59 goog.require('goog.asserts');
60 goog.require('goog.debug.entryPointRegistry');
61 goog.require('goog.events.BrowserEvent');
62 goog.require('goog.events.BrowserFeature');
63 goog.require('goog.events.Listenable');
64 goog.require('goog.events.ListenerMap');
65
66 goog.forwardDeclare('goog.debug.ErrorHandler');
67 goog.forwardDeclare('goog.events.EventWrapper');
68
69
70 /**
71 * @typedef {number|goog.events.ListenableKey}
72 */
73 goog.events.Key;
74
75
76 /**
77 * @typedef {EventTarget|goog.events.Listenable}
78 */
79 goog.events.ListenableType;
80
81
82 /**
83 * Property name on a native event target for the listener map
84 * associated with the event target.
85 * @private @const {string}
86 */
87 goog.events.LISTENER_MAP_PROP_ = 'closure_lm_' + ((Math.random() * 1e6) | 0);
88
89
90 /**
91 * String used to prepend to IE event types.
92 * @const
93 * @private
94 */
95 goog.events.onString_ = 'on';
96
97
98 /**
99 * Map of computed "on<eventname>" strings for IE event types. Caching
100 * this removes an extra object allocation in goog.events.listen which
101 * improves IE6 performance.
102 * @const
103 * @dict
104 * @private
105 */
106 goog.events.onStringMap_ = {};
107
108
109 /**
110 * @enum {number} Different capture simulation mode for IE8-.
111 */
112 goog.events.CaptureSimulationMode = {
113 /**
114 * Does not perform capture simulation. Will asserts in IE8- when you
115 * add capture listeners.
116 */
117 OFF_AND_FAIL: 0,
118
119 /**
120 * Does not perform capture simulation, silently ignore capture
121 * listeners.
122 */
123 OFF_AND_SILENT: 1,
124
125 /**
126 * Performs capture simulation.
127 */
128 ON: 2
129 };
130
131
132 /**
133 * @define {number} The capture simulation mode for IE8-. By default,
134 * this is ON.
135 */
136 goog.define('goog.events.CAPTURE_SIMULATION_MODE', 2);
137
138
139 /**
140 * Estimated count of total native listeners.
141 * @private {number}
142 */
143 goog.events.listenerCountEstimate_ = 0;
144
145
146 /**
147 * Adds an event listener for a specific event on a native event
148 * target (such as a DOM element) or an object that has implemented
149 * {@link goog.events.Listenable}. A listener can only be added once
150 * to an object and if it is added again the key for the listener is
151 * returned. Note that if the existing listener is a one-off listener
152 * (registered via listenOnce), it will no longer be a one-off
153 * listener after a call to listen().
154 *
155 * @param {EventTarget|goog.events.Listenable} src The node to listen
156 * to events on.
157 * @param {string|Array<string>|
158 * !goog.events.EventId<EVENTOBJ>|!Array<!goog.events.EventId<EVENTOBJ>>}
159 * type Event type or array of event types.
160 * @param {function(this:T, EVENTOBJ):?|{handleEvent:function(?):?}|null}
161 * listener Callback method, or an object with a handleEvent function.
162 * WARNING: passing an Object is now softly deprecated.
163 * @param {(boolean|!AddEventListenerOptions)=} opt_options
164 * @param {T=} opt_handler Element in whose scope to call the listener.
165 * @return {goog.events.Key} Unique key for the listener.
166 * @template T,EVENTOBJ
167 */
168 goog.events.listen = function(src, type, listener, opt_options, opt_handler) {
169 if (opt_options && opt_options.once) {
170 return goog.events.listenOnce(
171 src, type, listener, opt_options, opt_handler);
172 }
173 if (goog.isArray(type)) {
174 for (var i = 0; i < type.length; i++) {
175 goog.events.listen(src, type[i], listener, opt_options, opt_handler);
176 }
177 return null;
178 }
179
180 listener = goog.events.wrapListener(listener);
181 if (goog.events.Listenable.isImplementedBy(src)) {
182 var capture =
183 goog.isObject(opt_options) ? !!opt_options.capture : !!opt_options;
184 return src.listen(
185 /** @type {string|!goog.events.EventId} */ (type), listener, capture,
186 opt_handler);
187 } else {
188 return goog.events.listen_(
189 /** @type {!EventTarget} */ (src), type, listener,
190 /* callOnce */ false, opt_options, opt_handler);
191 }
192 };
193
194
195 /**
196 * Adds an event listener for a specific event on a native event
197 * target. A listener can only be added once to an object and if it
198 * is added again the key for the listener is returned.
199 *
200 * Note that a one-off listener will not change an existing listener,
201 * if any. On the other hand a normal listener will change existing
202 * one-off listener to become a normal listener.
203 *
204 * @param {EventTarget} src The node to listen to events on.
205 * @param {string|?goog.events.EventId<EVENTOBJ>} type Event type.
206 * @param {!Function} listener Callback function.
207 * @param {boolean} callOnce Whether the listener is a one-off
208 * listener or otherwise.
209 * @param {(boolean|!AddEventListenerOptions)=} opt_options
210 * @param {Object=} opt_handler Element in whose scope to call the listener.
211 * @return {goog.events.ListenableKey} Unique key for the listener.
212 * @template EVENTOBJ
213 * @private
214 */
215 goog.events.listen_ = function(
216 src, type, listener, callOnce, opt_options, opt_handler) {
217 if (!type) {
218 throw new Error('Invalid event type');
219 }
220
221 var capture =
222 goog.isObject(opt_options) ? !!opt_options.capture : !!opt_options;
223 if (capture && !goog.events.BrowserFeature.HAS_W3C_EVENT_SUPPORT) {
224 if (goog.events.CAPTURE_SIMULATION_MODE ==
225 goog.events.CaptureSimulationMode.OFF_AND_FAIL) {
226 goog.asserts.fail('Can not register capture listener in IE8-.');
227 return null;
228 } else if (
229 goog.events.CAPTURE_SIMULATION_MODE ==
230 goog.events.CaptureSimulationMode.OFF_AND_SILENT) {
231 return null;
232 }
233 }
234
235 var listenerMap = goog.events.getListenerMap_(src);
236 if (!listenerMap) {
237 src[goog.events.LISTENER_MAP_PROP_] = listenerMap =
238 new goog.events.ListenerMap(src);
239 }
240
241 var listenerObj = /** @type {goog.events.Listener} */ (
242 listenerMap.add(type, listener, callOnce, capture, opt_handler));
243
244 // If the listenerObj already has a proxy, it has been set up
245 // previously. We simply return.
246 if (listenerObj.proxy) {
247 return listenerObj;
248 }
249
250 var proxy = goog.events.getProxy();
251 listenerObj.proxy = proxy;
252
253 proxy.src = src;
254 proxy.listener = listenerObj;
255
256 // Attach the proxy through the browser's API
257 if (src.addEventListener) {
258 // Don't pass an object as `capture` if the browser doesn't support that.
259 if (!goog.events.BrowserFeature.PASSIVE_EVENTS) {
260 opt_options = capture;
261 }
262 // Don't break tests that expect a boolean.
263 if (opt_options === undefined) opt_options = false;
264 src.addEventListener(type.toString(), proxy, opt_options);
265 } else if (src.attachEvent) {
266 // The else if above used to be an unconditional else. It would call
267 // exception on IE11, spoiling the day of some callers. The previous
268 // incarnation of this code, from 2007, indicates that it replaced an
269 // earlier still version that caused excess allocations on IE6.
270 src.attachEvent(goog.events.getOnString_(type.toString()), proxy);
271 } else if (src.addListener && src.removeListener) {
272 // In IE, MediaQueryList uses addListener() insteadd of addEventListener. In
273 // Safari, there is no global for the MediaQueryList constructor, so we just
274 // check whether the object "looks like" MediaQueryList.
275 goog.asserts.assert(
276 type === 'change', 'MediaQueryList only has a change event');
277 src.addListener(proxy);
278 } else {
279 throw new Error('addEventListener and attachEvent are unavailable.');
280 }
281
282 goog.events.listenerCountEstimate_++;
283 return listenerObj;
284 };
285
286
287 /**
288 * Helper function for returning a proxy function.
289 * @return {!Function} A new or reused function object.
290 */
291 goog.events.getProxy = function() {
292 var proxyCallbackFunction = goog.events.handleBrowserEvent_;
293 // Use a local var f to prevent one allocation.
294 var f =
295 goog.events.BrowserFeature.HAS_W3C_EVENT_SUPPORT ? function(eventObject) {
296 return proxyCallbackFunction.call(f.src, f.listener, eventObject);
297 } : function(eventObject) {
298 var v = proxyCallbackFunction.call(f.src, f.listener, eventObject);
299 // NOTE(chrishenry): In IE, we hack in a capture phase. However, if
300 // there is inline event handler which tries to prevent default (for
301 // example <a href="..." onclick="return false">...</a>) in a
302 // descendant element, the prevent default will be overridden
303 // by this listener if this listener were to return true. Hence, we
304 // return undefined.
305 if (!v) return v;
306 };
307 return f;
308 };
309
310
311 /**
312 * Adds an event listener for a specific event on a native event
313 * target (such as a DOM element) or an object that has implemented
314 * {@link goog.events.Listenable}. After the event has fired the event
315 * listener is removed from the target.
316 *
317 * If an existing listener already exists, listenOnce will do
318 * nothing. In particular, if the listener was previously registered
319 * via listen(), listenOnce() will not turn the listener into a
320 * one-off listener. Similarly, if there is already an existing
321 * one-off listener, listenOnce does not modify the listeners (it is
322 * still a once listener).
323 *
324 * @param {EventTarget|goog.events.Listenable} src The node to listen
325 * to events on.
326 * @param {string|Array<string>|
327 * !goog.events.EventId<EVENTOBJ>|!Array<!goog.events.EventId<EVENTOBJ>>}
328 * type Event type or array of event types.
329 * @param {function(this:T, EVENTOBJ):?|{handleEvent:function(?):?}|null}
330 * listener Callback method.
331 * @param {(boolean|!AddEventListenerOptions)=} opt_options
332 * @param {T=} opt_handler Element in whose scope to call the listener.
333 * @return {goog.events.Key} Unique key for the listener.
334 * @template T,EVENTOBJ
335 */
336 goog.events.listenOnce = function(
337 src, type, listener, opt_options, opt_handler) {
338 if (goog.isArray(type)) {
339 for (var i = 0; i < type.length; i++) {
340 goog.events.listenOnce(src, type[i], listener, opt_options, opt_handler);
341 }
342 return null;
343 }
344
345 listener = goog.events.wrapListener(listener);
346 if (goog.events.Listenable.isImplementedBy(src)) {
347 var capture =
348 goog.isObject(opt_options) ? !!opt_options.capture : !!opt_options;
349 return src.listenOnce(
350 /** @type {string|!goog.events.EventId} */ (type), listener, capture,
351 opt_handler);
352 } else {
353 return goog.events.listen_(
354 /** @type {!EventTarget} */ (src), type, listener,
355 /* callOnce */ true, opt_options, opt_handler);
356 }
357 };
358
359
360 /**
361 * Adds an event listener with a specific event wrapper on a DOM Node or an
362 * object that has implemented {@link goog.events.Listenable}. A listener can
363 * only be added once to an object.
364 *
365 * @param {EventTarget|goog.events.Listenable} src The target to
366 * listen to events on.
367 * @param {goog.events.EventWrapper} wrapper Event wrapper to use.
368 * @param {function(this:T, ?):?|{handleEvent:function(?):?}|null} listener
369 * Callback method, or an object with a handleEvent function.
370 * @param {boolean=} opt_capt Whether to fire in capture phase (defaults to
371 * false).
372 * @param {T=} opt_handler Element in whose scope to call the listener.
373 * @template T
374 */
375 goog.events.listenWithWrapper = function(
376 src, wrapper, listener, opt_capt, opt_handler) {
377 wrapper.listen(src, listener, opt_capt, opt_handler);
378 };
379
380
381 /**
382 * Removes an event listener which was added with listen().
383 *
384 * @param {EventTarget|goog.events.Listenable} src The target to stop
385 * listening to events on.
386 * @param {string|Array<string>|
387 * !goog.events.EventId<EVENTOBJ>|!Array<!goog.events.EventId<EVENTOBJ>>}
388 * type Event type or array of event types to unlisten to.
389 * @param {function(?):?|{handleEvent:function(?):?}|null} listener The
390 * listener function to remove.
391 * @param {(boolean|!EventListenerOptions)=} opt_options
392 * whether the listener is fired during the capture or bubble phase of the
393 * event.
394 * @param {Object=} opt_handler Element in whose scope to call the listener.
395 * @return {?boolean} indicating whether the listener was there to remove.
396 * @template EVENTOBJ
397 */
398 goog.events.unlisten = function(src, type, listener, opt_options, opt_handler) {
399 if (goog.isArray(type)) {
400 for (var i = 0; i < type.length; i++) {
401 goog.events.unlisten(src, type[i], listener, opt_options, opt_handler);
402 }
403 return null;
404 }
405 var capture =
406 goog.isObject(opt_options) ? !!opt_options.capture : !!opt_options;
407
408 listener = goog.events.wrapListener(listener);
409 if (goog.events.Listenable.isImplementedBy(src)) {
410 return src.unlisten(
411 /** @type {string|!goog.events.EventId} */ (type), listener, capture,
412 opt_handler);
413 }
414
415 if (!src) {
416 // TODO(chrishenry): We should tighten the API to only accept
417 // non-null objects, or add an assertion here.
418 return false;
419 }
420
421 var listenerMap = goog.events.getListenerMap_(
422 /** @type {!EventTarget} */ (src));
423 if (listenerMap) {
424 var listenerObj = listenerMap.getListener(
425 /** @type {string|!goog.events.EventId} */ (type), listener, capture,
426 opt_handler);
427 if (listenerObj) {
428 return goog.events.unlistenByKey(listenerObj);
429 }
430 }
431
432 return false;
433 };
434
435
436 /**
437 * Removes an event listener which was added with listen() by the key
438 * returned by listen().
439 *
440 * @param {goog.events.Key} key The key returned by listen() for this
441 * event listener.
442 * @return {boolean} indicating whether the listener was there to remove.
443 */
444 goog.events.unlistenByKey = function(key) {
445 // TODO(chrishenry): Remove this check when tests that rely on this
446 // are fixed.
447 if (goog.isNumber(key)) {
448 return false;
449 }
450
451 var listener = key;
452 if (!listener || listener.removed) {
453 return false;
454 }
455
456 var src = listener.src;
457 if (goog.events.Listenable.isImplementedBy(src)) {
458 return /** @type {!goog.events.Listenable} */ (src).unlistenByKey(listener);
459 }
460
461 var type = listener.type;
462 var proxy = listener.proxy;
463 if (src.removeEventListener) {
464 src.removeEventListener(type, proxy, listener.capture);
465 } else if (src.detachEvent) {
466 src.detachEvent(goog.events.getOnString_(type), proxy);
467 } else if (src.addListener && src.removeListener) {
468 src.removeListener(proxy);
469 }
470 goog.events.listenerCountEstimate_--;
471
472 var listenerMap = goog.events.getListenerMap_(
473 /** @type {!EventTarget} */ (src));
474 // TODO(chrishenry): Try to remove this conditional and execute the
475 // first branch always. This should be safe.
476 if (listenerMap) {
477 listenerMap.removeByKey(listener);
478 if (listenerMap.getTypeCount() == 0) {
479 // Null the src, just because this is simple to do (and useful
480 // for IE <= 7).
481 listenerMap.src = null;
482 // We don't use delete here because IE does not allow delete
483 // on a window object.
484 src[goog.events.LISTENER_MAP_PROP_] = null;
485 }
486 } else {
487 /** @type {!goog.events.Listener} */ (listener).markAsRemoved();
488 }
489
490 return true;
491 };
492
493
494 /**
495 * Removes an event listener which was added with listenWithWrapper().
496 *
497 * @param {EventTarget|goog.events.Listenable} src The target to stop
498 * listening to events on.
499 * @param {goog.events.EventWrapper} wrapper Event wrapper to use.
500 * @param {function(?):?|{handleEvent:function(?):?}|null} listener The
501 * listener function to remove.
502 * @param {boolean=} opt_capt In DOM-compliant browsers, this determines
503 * whether the listener is fired during the capture or bubble phase of the
504 * event.
505 * @param {Object=} opt_handler Element in whose scope to call the listener.
506 */
507 goog.events.unlistenWithWrapper = function(
508 src, wrapper, listener, opt_capt, opt_handler) {
509 wrapper.unlisten(src, listener, opt_capt, opt_handler);
510 };
511
512
513 /**
514 * Removes all listeners from an object. You can also optionally
515 * remove listeners of a particular type.
516 *
517 * @param {Object|undefined} obj Object to remove listeners from. Must be an
518 * EventTarget or a goog.events.Listenable.
519 * @param {string|!goog.events.EventId=} opt_type Type of event to remove.
520 * Default is all types.
521 * @return {number} Number of listeners removed.
522 */
523 goog.events.removeAll = function(obj, opt_type) {
524 // TODO(chrishenry): Change the type of obj to
525 // (!EventTarget|!goog.events.Listenable).
526
527 if (!obj) {
528 return 0;
529 }
530
531 if (goog.events.Listenable.isImplementedBy(obj)) {
532 return /** @type {?} */ (obj).removeAllListeners(opt_type);
533 }
534
535 var listenerMap = goog.events.getListenerMap_(
536 /** @type {!EventTarget} */ (obj));
537 if (!listenerMap) {
538 return 0;
539 }
540
541 var count = 0;
542 var typeStr = opt_type && opt_type.toString();
543 for (var type in listenerMap.listeners) {
544 if (!typeStr || type == typeStr) {
545 // Clone so that we don't need to worry about unlistenByKey
546 // changing the content of the ListenerMap.
547 var listeners = listenerMap.listeners[type].concat();
548 for (var i = 0; i < listeners.length; ++i) {
549 if (goog.events.unlistenByKey(listeners[i])) {
550 ++count;
551 }
552 }
553 }
554 }
555 return count;
556 };
557
558
559 /**
560 * Gets the listeners for a given object, type and capture phase.
561 *
562 * @param {Object} obj Object to get listeners for.
563 * @param {string|!goog.events.EventId} type Event type.
564 * @param {boolean} capture Capture phase?.
565 * @return {Array<!goog.events.Listener>} Array of listener objects.
566 */
567 goog.events.getListeners = function(obj, type, capture) {
568 if (goog.events.Listenable.isImplementedBy(obj)) {
569 return /** @type {!goog.events.Listenable} */ (obj).getListeners(
570 type, capture);
571 } else {
572 if (!obj) {
573 // TODO(chrishenry): We should tighten the API to accept
574 // !EventTarget|goog.events.Listenable, and add an assertion here.
575 return [];
576 }
577
578 var listenerMap = goog.events.getListenerMap_(
579 /** @type {!EventTarget} */ (obj));
580 return listenerMap ? listenerMap.getListeners(type, capture) : [];
581 }
582 };
583
584
585 /**
586 * Gets the goog.events.Listener for the event or null if no such listener is
587 * in use.
588 *
589 * @param {EventTarget|goog.events.Listenable} src The target from
590 * which to get listeners.
591 * @param {?string|!goog.events.EventId<EVENTOBJ>} type The type of the event.
592 * @param {function(EVENTOBJ):?|{handleEvent:function(?):?}|null} listener The
593 * listener function to get.
594 * @param {boolean=} opt_capt In DOM-compliant browsers, this determines
595 * whether the listener is fired during the
596 * capture or bubble phase of the event.
597 * @param {Object=} opt_handler Element in whose scope to call the listener.
598 * @return {goog.events.ListenableKey} the found listener or null if not found.
599 * @template EVENTOBJ
600 */
601 goog.events.getListener = function(src, type, listener, opt_capt, opt_handler) {
602 // TODO(chrishenry): Change type from ?string to string, or add assertion.
603 type = /** @type {string} */ (type);
604 listener = goog.events.wrapListener(listener);
605 var capture = !!opt_capt;
606 if (goog.events.Listenable.isImplementedBy(src)) {
607 return src.getListener(type, listener, capture, opt_handler);
608 }
609
610 if (!src) {
611 // TODO(chrishenry): We should tighten the API to only accept
612 // non-null objects, or add an assertion here.
613 return null;
614 }
615
616 var listenerMap = goog.events.getListenerMap_(
617 /** @type {!EventTarget} */ (src));
618 if (listenerMap) {
619 return listenerMap.getListener(type, listener, capture, opt_handler);
620 }
621 return null;
622 };
623
624
625 /**
626 * Returns whether an event target has any active listeners matching the
627 * specified signature. If either the type or capture parameters are
628 * unspecified, the function will match on the remaining criteria.
629 *
630 * @param {EventTarget|goog.events.Listenable} obj Target to get
631 * listeners for.
632 * @param {string|!goog.events.EventId=} opt_type Event type.
633 * @param {boolean=} opt_capture Whether to check for capture or bubble-phase
634 * listeners.
635 * @return {boolean} Whether an event target has one or more listeners matching
636 * the requested type and/or capture phase.
637 */
638 goog.events.hasListener = function(obj, opt_type, opt_capture) {
639 if (goog.events.Listenable.isImplementedBy(obj)) {
640 return obj.hasListener(opt_type, opt_capture);
641 }
642
643 var listenerMap = goog.events.getListenerMap_(
644 /** @type {!EventTarget} */ (obj));
645 return !!listenerMap && listenerMap.hasListener(opt_type, opt_capture);
646 };
647
648
649 /**
650 * Provides a nice string showing the normalized event objects public members
651 * @param {Object} e Event Object.
652 * @return {string} String of the public members of the normalized event object.
653 */
654 goog.events.expose = function(e) {
655 var str = [];
656 for (var key in e) {
657 if (e[key] && e[key].id) {
658 str.push(key + ' = ' + e[key] + ' (' + e[key].id + ')');
659 } else {
660 str.push(key + ' = ' + e[key]);
661 }
662 }
663 return str.join('\n');
664 };
665
666
667 /**
668 * Returns a string with on prepended to the specified type. This is used for IE
669 * which expects "on" to be prepended. This function caches the string in order
670 * to avoid extra allocations in steady state.
671 * @param {string} type Event type.
672 * @return {string} The type string with 'on' prepended.
673 * @private
674 */
675 goog.events.getOnString_ = function(type) {
676 if (type in goog.events.onStringMap_) {
677 return goog.events.onStringMap_[type];
678 }
679 return goog.events.onStringMap_[type] = goog.events.onString_ + type;
680 };
681
682
683 /**
684 * Fires an object's listeners of a particular type and phase
685 *
686 * @param {Object} obj Object whose listeners to call.
687 * @param {string|!goog.events.EventId} type Event type.
688 * @param {boolean} capture Which event phase.
689 * @param {Object} eventObject Event object to be passed to listener.
690 * @return {boolean} True if all listeners returned true else false.
691 */
692 goog.events.fireListeners = function(obj, type, capture, eventObject) {
693 if (goog.events.Listenable.isImplementedBy(obj)) {
694 return /** @type {!goog.events.Listenable} */ (obj).fireListeners(
695 type, capture, eventObject);
696 }
697
698 return goog.events.fireListeners_(obj, type, capture, eventObject);
699 };
700
701
702 /**
703 * Fires an object's listeners of a particular type and phase.
704 * @param {Object} obj Object whose listeners to call.
705 * @param {string|!goog.events.EventId} type Event type.
706 * @param {boolean} capture Which event phase.
707 * @param {Object} eventObject Event object to be passed to listener.
708 * @return {boolean} True if all listeners returned true else false.
709 * @private
710 */
711 goog.events.fireListeners_ = function(obj, type, capture, eventObject) {
712 /** @type {boolean} */
713 var retval = true;
714
715 var listenerMap = goog.events.getListenerMap_(
716 /** @type {EventTarget} */ (obj));
717 if (listenerMap) {
718 // TODO(chrishenry): Original code avoids array creation when there
719 // is no listener, so we do the same. If this optimization turns
720 // out to be not required, we can replace this with
721 // listenerMap.getListeners(type, capture) instead, which is simpler.
722 var listenerArray = listenerMap.listeners[type.toString()];
723 if (listenerArray) {
724 listenerArray = listenerArray.concat();
725 for (var i = 0; i < listenerArray.length; i++) {
726 var listener = listenerArray[i];
727 // We might not have a listener if the listener was removed.
728 if (listener && listener.capture == capture && !listener.removed) {
729 var result = goog.events.fireListener(listener, eventObject);
730 retval = retval && (result !== false);
731 }
732 }
733 }
734 }
735 return retval;
736 };
737
738
739 /**
740 * Fires a listener with a set of arguments
741 *
742 * @param {goog.events.Listener} listener The listener object to call.
743 * @param {Object} eventObject The event object to pass to the listener.
744 * @return {*} Result of listener.
745 */
746 goog.events.fireListener = function(listener, eventObject) {
747 var listenerFn = listener.listener;
748 var listenerHandler = listener.handler || listener.src;
749
750 if (listener.callOnce) {
751 goog.events.unlistenByKey(listener);
752 }
753 return listenerFn.call(listenerHandler, eventObject);
754 };
755
756
757 /**
758 * Gets the total number of listeners currently in the system.
759 * @return {number} Number of listeners.
760 * @deprecated This returns estimated count, now that Closure no longer
761 * stores a central listener registry. We still return an estimation
762 * to keep existing listener-related tests passing. In the near future,
763 * this function will be removed.
764 */
765 goog.events.getTotalListenerCount = function() {
766 return goog.events.listenerCountEstimate_;
767 };
768
769
770 /**
771 * Dispatches an event (or event like object) and calls all listeners
772 * listening for events of this type. The type of the event is decided by the
773 * type property on the event object.
774 *
775 * If any of the listeners returns false OR calls preventDefault then this
776 * function will return false. If one of the capture listeners calls
777 * stopPropagation, then the bubble listeners won't fire.
778 *
779 * @param {goog.events.Listenable} src The event target.
780 * @param {goog.events.EventLike} e Event object.
781 * @return {boolean} If anyone called preventDefault on the event object (or
782 * if any of the handlers returns false) this will also return false.
783 * If there are no handlers, or if all handlers return true, this returns
784 * true.
785 */
786 goog.events.dispatchEvent = function(src, e) {
787 goog.asserts.assert(
788 goog.events.Listenable.isImplementedBy(src),
789 'Can not use goog.events.dispatchEvent with ' +
790 'non-goog.events.Listenable instance.');
791 return src.dispatchEvent(e);
792 };
793
794
795 /**
796 * Installs exception protection for the browser event entry point using the
797 * given error handler.
798 *
799 * @param {goog.debug.ErrorHandler} errorHandler Error handler with which to
800 * protect the entry point.
801 */
802 goog.events.protectBrowserEventEntryPoint = function(errorHandler) {
803 goog.events.handleBrowserEvent_ =
804 errorHandler.protectEntryPoint(goog.events.handleBrowserEvent_);
805 };
806
807
808 /**
809 * Handles an event and dispatches it to the correct listeners. This
810 * function is a proxy for the real listener the user specified.
811 *
812 * @param {goog.events.Listener} listener The listener object.
813 * @param {Event=} opt_evt Optional event object that gets passed in via the
814 * native event handlers.
815 * @return {*} Result of the event handler.
816 * @this {EventTarget} The object or Element that fired the event.
817 * @private
818 */
819 goog.events.handleBrowserEvent_ = function(listener, opt_evt) {
820 if (listener.removed) {
821 return true;
822 }
823
824 // Synthesize event propagation if the browser does not support W3C
825 // event model.
826 if (!goog.events.BrowserFeature.HAS_W3C_EVENT_SUPPORT) {
827 var ieEvent = opt_evt ||
828 /** @type {Event} */ (goog.getObjectByName('window.event'));
829 var evt = new goog.events.BrowserEvent(ieEvent, this);
830 /** @type {*} */
831 var retval = true;
832
833 if (goog.events.CAPTURE_SIMULATION_MODE ==
834 goog.events.CaptureSimulationMode.ON) {
835 // If we have not marked this event yet, we should perform capture
836 // simulation.
837 if (!goog.events.isMarkedIeEvent_(ieEvent)) {
838 goog.events.markIeEvent_(ieEvent);
839
840 var ancestors = [];
841 for (var parent = evt.currentTarget; parent;
842 parent = parent.parentNode) {
843 ancestors.push(parent);
844 }
845
846 // Fire capture listeners.
847 var type = listener.type;
848 for (var i = ancestors.length - 1; !evt.propagationStopped_ && i >= 0;
849 i--) {
850 evt.currentTarget = ancestors[i];
851 var result =
852 goog.events.fireListeners_(ancestors[i], type, true, evt);
853 retval = retval && result;
854 }
855
856 // Fire bubble listeners.
857 //
858 // We can technically rely on IE to perform bubble event
859 // propagation. However, it turns out that IE fires events in
860 // opposite order of attachEvent registration, which broke
861 // some code and tests that rely on the order. (While W3C DOM
862 // Level 2 Events TR leaves the event ordering unspecified,
863 // modern browsers and W3C DOM Level 3 Events Working Draft
864 // actually specify the order as the registration order.)
865 for (var i = 0; !evt.propagationStopped_ && i < ancestors.length; i++) {
866 evt.currentTarget = ancestors[i];
867 var result =
868 goog.events.fireListeners_(ancestors[i], type, false, evt);
869 retval = retval && result;
870 }
871 }
872 } else {
873 retval = goog.events.fireListener(listener, evt);
874 }
875 return retval;
876 }
877
878 // Otherwise, simply fire the listener.
879 return goog.events.fireListener(
880 listener, new goog.events.BrowserEvent(opt_evt, this));
881 };
882
883
884 /**
885 * This is used to mark the IE event object so we do not do the Closure pass
886 * twice for a bubbling event.
887 * @param {Event} e The IE browser event.
888 * @private
889 */
890 goog.events.markIeEvent_ = function(e) {
891 // Only the keyCode and the returnValue can be changed. We use keyCode for
892 // non keyboard events.
893 // event.returnValue is a bit more tricky. It is undefined by default. A
894 // boolean false prevents the default action. In a window.onbeforeunload and
895 // the returnValue is non undefined it will be alerted. However, we will only
896 // modify the returnValue for keyboard events. We can get a problem if non
897 // closure events sets the keyCode or the returnValue
898
899 var useReturnValue = false;
900
901 if (e.keyCode == 0) {
902 // We cannot change the keyCode in case that srcElement is input[type=file].
903 // We could test that that is the case but that would allocate 3 objects.
904 // If we use try/catch we will only allocate extra objects in the case of a
905 // failure.
906
907 try {
908 e.keyCode = -1;
909 return;
910 } catch (ex) {
911 useReturnValue = true;
912 }
913 }
914
915 if (useReturnValue ||
916 /** @type {boolean|undefined} */ (e.returnValue) == undefined) {
917 e.returnValue = true;
918 }
919 };
920
921
922 /**
923 * This is used to check if an IE event has already been handled by the Closure
924 * system so we do not do the Closure pass twice for a bubbling event.
925 * @param {Event} e The IE browser event.
926 * @return {boolean} True if the event object has been marked.
927 * @private
928 */
929 goog.events.isMarkedIeEvent_ = function(e) {
930 return e.keyCode < 0 || e.returnValue != undefined;
931 };
932
933
934 /**
935 * Counter to create unique event ids.
936 * @private {number}
937 */
938 goog.events.uniqueIdCounter_ = 0;
939
940
941 /**
942 * Creates a unique event id.
943 *
944 * @param {string} identifier The identifier.
945 * @return {string} A unique identifier.
946 * @idGenerator {unique}
947 */
948 goog.events.getUniqueId = function(identifier) {
949 return identifier + '_' + goog.events.uniqueIdCounter_++;
950 };
951
952
953 /**
954 * @param {EventTarget} src The source object.
955 * @return {goog.events.ListenerMap} A listener map for the given
956 * source object, or null if none exists.
957 * @private
958 */
959 goog.events.getListenerMap_ = function(src) {
960 var listenerMap = src[goog.events.LISTENER_MAP_PROP_];
961 // IE serializes the property as well (e.g. when serializing outer
962 // HTML). So we must check that the value is of the correct type.
963 return listenerMap instanceof goog.events.ListenerMap ? listenerMap : null;
964 };
965
966
967 /**
968 * Expando property for listener function wrapper for Object with
969 * handleEvent.
970 * @private @const {string}
971 */
972 goog.events.LISTENER_WRAPPER_PROP_ =
973 '__closure_events_fn_' + ((Math.random() * 1e9) >>> 0);
974
975
976 /**
977 * @param {Object|Function} listener The listener function or an
978 * object that contains handleEvent method.
979 * @return {!Function} Either the original function or a function that
980 * calls obj.handleEvent. If the same listener is passed to this
981 * function more than once, the same function is guaranteed to be
982 * returned.
983 */
984 goog.events.wrapListener = function(listener) {
985 goog.asserts.assert(listener, 'Listener can not be null.');
986
987 if (goog.isFunction(listener)) {
988 return listener;
989 }
990
991 goog.asserts.assert(
992 listener.handleEvent, 'An object listener must have handleEvent method.');
993 if (!listener[goog.events.LISTENER_WRAPPER_PROP_]) {
994 listener[goog.events.LISTENER_WRAPPER_PROP_] = function(e) {
995 return /** @type {?} */ (listener).handleEvent(e);
996 };
997 }
998 return listener[goog.events.LISTENER_WRAPPER_PROP_];
999 };
1000
1001
1002 // Register the browser event handler as an entry point, so that
1003 // it can be monitored for exception handling, etc.
1004 goog.debug.entryPointRegistry.register(
1005 /**
1006 * @param {function(!Function): !Function} transformer The transforming
1007 * function.
1008 */
1009 function(transformer) {
1010 goog.events.handleBrowserEvent_ =
1011 transformer(goog.events.handleBrowserEvent_);
1012 });