lib/goog/events/eventtarget.js

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 A disposable implementation of a custom
17 * listenable/event target. See also: documentation for
18 * {@code goog.events.Listenable}.
19 *
20 * @author arv@google.com (Erik Arvidsson) [Original implementation]
21 * @see ../demos/eventtarget.html
22 * @see goog.events.Listenable
23 */
24
25goog.provide('goog.events.EventTarget');
26
27goog.require('goog.Disposable');
28goog.require('goog.asserts');
29goog.require('goog.events');
30goog.require('goog.events.Event');
31goog.require('goog.events.Listenable');
32goog.require('goog.events.ListenerMap');
33goog.require('goog.object');
34
35
36
37/**
38 * An implementation of {@code goog.events.Listenable} with full W3C
39 * EventTarget-like support (capture/bubble mechanism, stopping event
40 * propagation, preventing default actions).
41 *
42 * You may subclass this class to turn your class into a Listenable.
43 *
44 * Unless propagation is stopped, an event dispatched by an
45 * EventTarget will bubble to the parent returned by
46 * {@code getParentEventTarget}. To set the parent, call
47 * {@code setParentEventTarget}. Subclasses that don't support
48 * changing the parent can override the setter to throw an error.
49 *
50 * Example usage:
51 * <pre>
52 * var source = new goog.events.EventTarget();
53 * function handleEvent(e) {
54 * alert('Type: ' + e.type + '; Target: ' + e.target);
55 * }
56 * source.listen('foo', handleEvent);
57 * // Or: goog.events.listen(source, 'foo', handleEvent);
58 * ...
59 * source.dispatchEvent('foo'); // will call handleEvent
60 * ...
61 * source.unlisten('foo', handleEvent);
62 * // Or: goog.events.unlisten(source, 'foo', handleEvent);
63 * </pre>
64 *
65 * @constructor
66 * @extends {goog.Disposable}
67 * @implements {goog.events.Listenable}
68 */
69goog.events.EventTarget = function() {
70 goog.Disposable.call(this);
71
72 /**
73 * Maps of event type to an array of listeners.
74 * @private {!goog.events.ListenerMap}
75 */
76 this.eventTargetListeners_ = new goog.events.ListenerMap(this);
77
78 /**
79 * The object to use for event.target. Useful when mixing in an
80 * EventTarget to another object.
81 * @private {!Object}
82 */
83 this.actualEventTarget_ = this;
84
85 /**
86 * Parent event target, used during event bubbling.
87 *
88 * TODO(chrishenry): Change this to goog.events.Listenable. This
89 * currently breaks people who expect getParentEventTarget to return
90 * goog.events.EventTarget.
91 *
92 * @private {goog.events.EventTarget}
93 */
94 this.parentEventTarget_ = null;
95};
96goog.inherits(goog.events.EventTarget, goog.Disposable);
97goog.events.Listenable.addImplementation(goog.events.EventTarget);
98
99
100/**
101 * An artificial cap on the number of ancestors you can have. This is mainly
102 * for loop detection.
103 * @const {number}
104 * @private
105 */
106goog.events.EventTarget.MAX_ANCESTORS_ = 1000;
107
108
109/**
110 * Returns the parent of this event target to use for bubbling.
111 *
112 * @return {goog.events.EventTarget} The parent EventTarget or null if
113 * there is no parent.
114 * @override
115 */
116goog.events.EventTarget.prototype.getParentEventTarget = function() {
117 return this.parentEventTarget_;
118};
119
120
121/**
122 * Sets the parent of this event target to use for capture/bubble
123 * mechanism.
124 * @param {goog.events.EventTarget} parent Parent listenable (null if none).
125 */
126goog.events.EventTarget.prototype.setParentEventTarget = function(parent) {
127 this.parentEventTarget_ = parent;
128};
129
130
131/**
132 * Adds an event listener to the event target. The same handler can only be
133 * added once per the type. Even if you add the same handler multiple times
134 * using the same type then it will only be called once when the event is
135 * dispatched.
136 *
137 * @param {string} type The type of the event to listen for.
138 * @param {function(?):?|{handleEvent:function(?):?}|null} handler The function
139 * to handle the event. The handler can also be an object that implements
140 * the handleEvent method which takes the event object as argument.
141 * @param {boolean=} opt_capture In DOM-compliant browsers, this determines
142 * whether the listener is fired during the capture or bubble phase
143 * of the event.
144 * @param {Object=} opt_handlerScope Object in whose scope to call
145 * the listener.
146 * @deprecated Use {@code #listen} instead, when possible. Otherwise, use
147 * {@code goog.events.listen} if you are passing Object
148 * (instead of Function) as handler.
149 */
150goog.events.EventTarget.prototype.addEventListener = function(
151 type, handler, opt_capture, opt_handlerScope) {
152 goog.events.listen(this, type, handler, opt_capture, opt_handlerScope);
153};
154
155
156/**
157 * Removes an event listener from the event target. The handler must be the
158 * same object as the one added. If the handler has not been added then
159 * nothing is done.
160 *
161 * @param {string} type The type of the event to listen for.
162 * @param {function(?):?|{handleEvent:function(?):?}|null} handler The function
163 * to handle the event. The handler can also be an object that implements
164 * the handleEvent method which takes the event object as argument.
165 * @param {boolean=} opt_capture In DOM-compliant browsers, this determines
166 * whether the listener is fired during the capture or bubble phase
167 * of the event.
168 * @param {Object=} opt_handlerScope Object in whose scope to call
169 * the listener.
170 * @deprecated Use {@code #unlisten} instead, when possible. Otherwise, use
171 * {@code goog.events.unlisten} if you are passing Object
172 * (instead of Function) as handler.
173 */
174goog.events.EventTarget.prototype.removeEventListener = function(
175 type, handler, opt_capture, opt_handlerScope) {
176 goog.events.unlisten(this, type, handler, opt_capture, opt_handlerScope);
177};
178
179
180/** @override */
181goog.events.EventTarget.prototype.dispatchEvent = function(e) {
182 this.assertInitialized_();
183
184 var ancestorsTree, ancestor = this.getParentEventTarget();
185 if (ancestor) {
186 ancestorsTree = [];
187 var ancestorCount = 1;
188 for (; ancestor; ancestor = ancestor.getParentEventTarget()) {
189 ancestorsTree.push(ancestor);
190 goog.asserts.assert(
191 (++ancestorCount < goog.events.EventTarget.MAX_ANCESTORS_),
192 'infinite loop');
193 }
194 }
195
196 return goog.events.EventTarget.dispatchEventInternal_(
197 this.actualEventTarget_, e, ancestorsTree);
198};
199
200
201/**
202 * Removes listeners from this object. Classes that extend EventTarget may
203 * need to override this method in order to remove references to DOM Elements
204 * and additional listeners.
205 * @override
206 */
207goog.events.EventTarget.prototype.disposeInternal = function() {
208 goog.events.EventTarget.superClass_.disposeInternal.call(this);
209
210 this.removeAllListeners();
211 this.parentEventTarget_ = null;
212};
213
214
215/** @override */
216goog.events.EventTarget.prototype.listen = function(
217 type, listener, opt_useCapture, opt_listenerScope) {
218 this.assertInitialized_();
219 return this.eventTargetListeners_.add(
220 String(type), listener, false /* callOnce */, opt_useCapture,
221 opt_listenerScope);
222};
223
224
225/** @override */
226goog.events.EventTarget.prototype.listenOnce = function(
227 type, listener, opt_useCapture, opt_listenerScope) {
228 return this.eventTargetListeners_.add(
229 String(type), listener, true /* callOnce */, opt_useCapture,
230 opt_listenerScope);
231};
232
233
234/** @override */
235goog.events.EventTarget.prototype.unlisten = function(
236 type, listener, opt_useCapture, opt_listenerScope) {
237 return this.eventTargetListeners_.remove(
238 String(type), listener, opt_useCapture, opt_listenerScope);
239};
240
241
242/** @override */
243goog.events.EventTarget.prototype.unlistenByKey = function(key) {
244 return this.eventTargetListeners_.removeByKey(key);
245};
246
247
248/** @override */
249goog.events.EventTarget.prototype.removeAllListeners = function(opt_type) {
250 // TODO(chrishenry): Previously, removeAllListeners can be called on
251 // uninitialized EventTarget, so we preserve that behavior. We
252 // should remove this when usages that rely on that fact are purged.
253 if (!this.eventTargetListeners_) {
254 return 0;
255 }
256 return this.eventTargetListeners_.removeAll(opt_type);
257};
258
259
260/** @override */
261goog.events.EventTarget.prototype.fireListeners = function(
262 type, capture, eventObject) {
263 // TODO(chrishenry): Original code avoids array creation when there
264 // is no listener, so we do the same. If this optimization turns
265 // out to be not required, we can replace this with
266 // getListeners(type, capture) instead, which is simpler.
267 var listenerArray = this.eventTargetListeners_.listeners[String(type)];
268 if (!listenerArray) {
269 return true;
270 }
271 listenerArray = listenerArray.concat();
272
273 var rv = true;
274 for (var i = 0; i < listenerArray.length; ++i) {
275 var listener = listenerArray[i];
276 // We might not have a listener if the listener was removed.
277 if (listener && !listener.removed && listener.capture == capture) {
278 var listenerFn = listener.listener;
279 var listenerHandler = listener.handler || listener.src;
280
281 if (listener.callOnce) {
282 this.unlistenByKey(listener);
283 }
284 rv = listenerFn.call(listenerHandler, eventObject) !== false && rv;
285 }
286 }
287
288 return rv && eventObject.returnValue_ != false;
289};
290
291
292/** @override */
293goog.events.EventTarget.prototype.getListeners = function(type, capture) {
294 return this.eventTargetListeners_.getListeners(String(type), capture);
295};
296
297
298/** @override */
299goog.events.EventTarget.prototype.getListener = function(
300 type, listener, capture, opt_listenerScope) {
301 return this.eventTargetListeners_.getListener(
302 String(type), listener, capture, opt_listenerScope);
303};
304
305
306/** @override */
307goog.events.EventTarget.prototype.hasListener = function(
308 opt_type, opt_capture) {
309 var id = goog.isDef(opt_type) ? String(opt_type) : undefined;
310 return this.eventTargetListeners_.hasListener(id, opt_capture);
311};
312
313
314/**
315 * Sets the target to be used for {@code event.target} when firing
316 * event. Mainly used for testing. For example, see
317 * {@code goog.testing.events.mixinListenable}.
318 * @param {!Object} target The target.
319 */
320goog.events.EventTarget.prototype.setTargetForTesting = function(target) {
321 this.actualEventTarget_ = target;
322};
323
324
325/**
326 * Asserts that the event target instance is initialized properly.
327 * @private
328 */
329goog.events.EventTarget.prototype.assertInitialized_ = function() {
330 goog.asserts.assert(
331 this.eventTargetListeners_,
332 'Event target is not initialized. Did you call the superclass ' +
333 '(goog.events.EventTarget) constructor?');
334};
335
336
337/**
338 * Dispatches the given event on the ancestorsTree.
339 *
340 * @param {!Object} target The target to dispatch on.
341 * @param {goog.events.Event|Object|string} e The event object.
342 * @param {Array<goog.events.Listenable>=} opt_ancestorsTree The ancestors
343 * tree of the target, in reverse order from the closest ancestor
344 * to the root event target. May be null if the target has no ancestor.
345 * @return {boolean} If anyone called preventDefault on the event object (or
346 * if any of the listeners returns false) this will also return false.
347 * @private
348 */
349goog.events.EventTarget.dispatchEventInternal_ = function(
350 target, e, opt_ancestorsTree) {
351 var type = e.type || /** @type {string} */ (e);
352
353 // If accepting a string or object, create a custom event object so that
354 // preventDefault and stopPropagation work with the event.
355 if (goog.isString(e)) {
356 e = new goog.events.Event(e, target);
357 } else if (!(e instanceof goog.events.Event)) {
358 var oldEvent = e;
359 e = new goog.events.Event(type, target);
360 goog.object.extend(e, oldEvent);
361 } else {
362 e.target = e.target || target;
363 }
364
365 var rv = true, currentTarget;
366
367 // Executes all capture listeners on the ancestors, if any.
368 if (opt_ancestorsTree) {
369 for (var i = opt_ancestorsTree.length - 1; !e.propagationStopped_ && i >= 0;
370 i--) {
371 currentTarget = e.currentTarget = opt_ancestorsTree[i];
372 rv = currentTarget.fireListeners(type, true, e) && rv;
373 }
374 }
375
376 // Executes capture and bubble listeners on the target.
377 if (!e.propagationStopped_) {
378 currentTarget = e.currentTarget = target;
379 rv = currentTarget.fireListeners(type, true, e) && rv;
380 if (!e.propagationStopped_) {
381 rv = currentTarget.fireListeners(type, false, e) && rv;
382 }
383 }
384
385 // Executes all bubble listeners on the ancestors, if any.
386 if (opt_ancestorsTree) {
387 for (i = 0; !e.propagationStopped_ && i < opt_ancestorsTree.length; i++) {
388 currentTarget = e.currentTarget = opt_ancestorsTree[i];
389 rv = currentTarget.fireListeners(type, false, e) && rv;
390 }
391 }
392
393 return rv;
394};