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 | |
26 | goog.provide('goog.events.EventTarget'); |
27 | |
28 | goog.require('goog.Disposable'); |
29 | goog.require('goog.asserts'); |
30 | goog.require('goog.events'); |
31 | goog.require('goog.events.Event'); |
32 | goog.require('goog.events.Listenable'); |
33 | goog.require('goog.events.ListenerMap'); |
34 | goog.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 | */ |
70 | goog.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 | }; |
97 | goog.inherits(goog.events.EventTarget, goog.Disposable); |
98 | goog.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 | */ |
107 | goog.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 | */ |
117 | goog.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 | */ |
127 | goog.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 | */ |
151 | goog.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 | */ |
175 | goog.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 */ |
182 | goog.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 | */ |
208 | goog.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 */ |
217 | goog.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 */ |
227 | goog.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 */ |
236 | goog.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 */ |
244 | goog.events.EventTarget.prototype.unlistenByKey = function(key) { |
245 | return this.eventTargetListeners_.removeByKey(key); |
246 | }; |
247 | |
248 | |
249 | /** @override */ |
250 | goog.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 */ |
262 | goog.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 */ |
294 | goog.events.EventTarget.prototype.getListeners = function(type, capture) { |
295 | return this.eventTargetListeners_.getListeners(String(type), capture); |
296 | }; |
297 | |
298 | |
299 | /** @override */ |
300 | goog.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 */ |
308 | goog.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 | */ |
321 | goog.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 | */ |
330 | goog.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 | */ |
350 | goog.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 | }; |