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