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 implementation of {@link goog.events.Listenable} that does
17
 * not need to be disposed.
18
 */
19

20
goog.provide('goog.labs.events.NonDisposableEventTarget');
21

22

23
goog.require('goog.array');
24
goog.require('goog.asserts');
25
goog.require('goog.events.Event');
26
goog.require('goog.events.Listenable');
27
goog.require('goog.events.ListenerMap');
28
goog.require('goog.object');
29

30

31

32
/**
33
 * An implementation of {@code goog.events.Listenable} with full W3C
34
 * EventTarget-like support (capture/bubble mechanism, stopping event
35
 * propagation, preventing default actions).
36
 *
37
 * You may subclass this class to turn your class into a Listenable.
38
 *
39
 * Unlike {@link goog.events.EventTarget}, this class does not implement
40
 * {@link goog.disposable.IDisposable}. Instances of this class that have had
41
 * It is not necessary to call {@link goog.dispose}
42
 * or {@link #removeAllListeners} in order for an instance of this class
43
 * to be garbage collected.
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.labs.events.NonDisposableEventTarget();
54
 *   function handleEvent(e) {
55
 *     alert('Type: ' + e.type + '; Target: ' + e.target);
56
 *   }
57
 *   source.listen('foo', handleEvent);
58
 *   source.dispatchEvent('foo'); // will call handleEvent
59
 * </pre>
60
 *
61
 * TODO(chrishenry|johnlenz): Consider a more modern, less viral
62
 * (not based on inheritance) replacement of goog.Disposable, which will allow
63
 * goog.events.EventTarget to not be disposable.
64
 *
65
 * @constructor
66
 * @implements {goog.events.Listenable}
67
 * @final
68
 */
69
goog.labs.events.NonDisposableEventTarget = function() {
70
  /**
71
   * Maps of event type to an array of listeners.
72
   * @private {!goog.events.ListenerMap}
73
   */
74
  this.eventTargetListeners_ = new goog.events.ListenerMap(this);
75
};
76
goog.events.Listenable.addImplementation(
77
    goog.labs.events.NonDisposableEventTarget);
78

79

80
/**
81
 * An artificial cap on the number of ancestors you can have. This is mainly
82
 * for loop detection.
83
 * @const {number}
84
 * @private
85
 */
86
goog.labs.events.NonDisposableEventTarget.MAX_ANCESTORS_ = 1000;
87

88

89
/**
90
 * Parent event target, used during event bubbling.
91
 * @private {goog.events.Listenable}
92
 */
93
goog.labs.events.NonDisposableEventTarget.prototype.parentEventTarget_ = null;
94

95

96
/** @override */
97
goog.labs.events.NonDisposableEventTarget.prototype.getParentEventTarget =
98
    function() {
99
  return this.parentEventTarget_;
100
};
101

102

103
/**
104
 * Sets the parent of this event target to use for capture/bubble
105
 * mechanism.
106
 * @param {goog.events.Listenable} parent Parent listenable (null if none).
107
 */
108
goog.labs.events.NonDisposableEventTarget.prototype.setParentEventTarget =
109
    function(parent) {
110
  this.parentEventTarget_ = parent;
111
};
112

113

114
/** @override */
115
goog.labs.events.NonDisposableEventTarget.prototype.dispatchEvent = function(
116
    e) {
117
  this.assertInitialized_();
118
  var ancestorsTree, ancestor = this.getParentEventTarget();
119
  if (ancestor) {
120
    ancestorsTree = [];
121
    var ancestorCount = 1;
122
    for (; ancestor; ancestor = ancestor.getParentEventTarget()) {
123
      ancestorsTree.push(ancestor);
124
      goog.asserts.assert(
125
          (++ancestorCount <
126
           goog.labs.events.NonDisposableEventTarget.MAX_ANCESTORS_),
127
          'infinite loop');
128
    }
129
  }
130

131
  return goog.labs.events.NonDisposableEventTarget.dispatchEventInternal_(
132
      this, e, ancestorsTree);
133
};
134

135

136
/** @override */
137
goog.labs.events.NonDisposableEventTarget.prototype.listen = function(
138
    type, listener, opt_useCapture, opt_listenerScope) {
139
  this.assertInitialized_();
140
  return this.eventTargetListeners_.add(
141
      String(type), listener, false /* callOnce */, opt_useCapture,
142
      opt_listenerScope);
143
};
144

145

146
/** @override */
147
goog.labs.events.NonDisposableEventTarget.prototype.listenOnce = function(
148
    type, listener, opt_useCapture, opt_listenerScope) {
149
  return this.eventTargetListeners_.add(
150
      String(type), listener, true /* callOnce */, opt_useCapture,
151
      opt_listenerScope);
152
};
153

154

155
/** @override */
156
goog.labs.events.NonDisposableEventTarget.prototype.unlisten = function(
157
    type, listener, opt_useCapture, opt_listenerScope) {
158
  return this.eventTargetListeners_.remove(
159
      String(type), listener, opt_useCapture, opt_listenerScope);
160
};
161

162

163
/** @override */
164
goog.labs.events.NonDisposableEventTarget.prototype.unlistenByKey = function(
165
    key) {
166
  return this.eventTargetListeners_.removeByKey(key);
167
};
168

169

170
/** @override */
171
goog.labs.events.NonDisposableEventTarget.prototype.removeAllListeners =
172
    function(opt_type) {
173
  return this.eventTargetListeners_.removeAll(opt_type);
174
};
175

176

177
/** @override */
178
goog.labs.events.NonDisposableEventTarget.prototype.fireListeners = function(
179
    type, capture, eventObject) {
180
  // TODO(chrishenry): Original code avoids array creation when there
181
  // is no listener, so we do the same. If this optimization turns
182
  // out to be not required, we can replace this with
183
  // getListeners(type, capture) instead, which is simpler.
184
  var listenerArray = this.eventTargetListeners_.listeners[String(type)];
185
  if (!listenerArray) {
186
    return true;
187
  }
188
  listenerArray = goog.array.clone(listenerArray);
189

190
  var rv = true;
191
  for (var i = 0; i < listenerArray.length; ++i) {
192
    var listener = listenerArray[i];
193
    // We might not have a listener if the listener was removed.
194
    if (listener && !listener.removed && listener.capture == capture) {
195
      var listenerFn = listener.listener;
196
      var listenerHandler = listener.handler || listener.src;
197

198
      if (listener.callOnce) {
199
        this.unlistenByKey(listener);
200
      }
201
      rv = listenerFn.call(listenerHandler, eventObject) !== false && rv;
202
    }
203
  }
204

205
  return rv && eventObject.returnValue_ != false;
206
};
207

208

209
/** @override */
210
goog.labs.events.NonDisposableEventTarget.prototype.getListeners = function(
211
    type, capture) {
212
  return this.eventTargetListeners_.getListeners(String(type), capture);
213
};
214

215

216
/** @override */
217
goog.labs.events.NonDisposableEventTarget.prototype.getListener = function(
218
    type, listener, capture, opt_listenerScope) {
219
  return this.eventTargetListeners_.getListener(
220
      String(type), listener, capture, opt_listenerScope);
221
};
222

223

224
/** @override */
225
goog.labs.events.NonDisposableEventTarget.prototype.hasListener = function(
226
    opt_type, opt_capture) {
227
  var id = goog.isDef(opt_type) ? String(opt_type) : undefined;
228
  return this.eventTargetListeners_.hasListener(id, opt_capture);
229
};
230

231

232
/**
233
 * Asserts that the event target instance is initialized properly.
234
 * @private
235
 */
236
goog.labs.events.NonDisposableEventTarget.prototype.assertInitialized_ =
237
    function() {
238
  goog.asserts.assert(
239
      this.eventTargetListeners_,
240
      'Event target is not initialized. Did you call the superclass ' +
241
          '(goog.labs.events.NonDisposableEventTarget) constructor?');
242
};
243

244

245
/**
246
 * Dispatches the given event on the ancestorsTree.
247
 *
248
 * TODO(chrishenry): Look for a way to reuse this logic in
249
 * goog.events, if possible.
250
 *
251
 * @param {!Object} target The target to dispatch on.
252
 * @param {goog.events.Event|Object|string} e The event object.
253
 * @param {Array<goog.events.Listenable>=} opt_ancestorsTree The ancestors
254
 *     tree of the target, in reverse order from the closest ancestor
255
 *     to the root event target. May be null if the target has no ancestor.
256
 * @return {boolean} If anyone called preventDefault on the event object (or
257
 *     if any of the listeners returns false) this will also return false.
258
 * @private
259
 */
260
goog.labs.events.NonDisposableEventTarget.dispatchEventInternal_ = function(
261
    target, e, opt_ancestorsTree) {
262
  var type = e.type || /** @type {string} */ (e);
263

264
  // If accepting a string or object, create a custom event object so that
265
  // preventDefault and stopPropagation work with the event.
266
  if (goog.isString(e)) {
267
    e = new goog.events.Event(e, target);
268
  } else if (!(e instanceof goog.events.Event)) {
269
    var oldEvent = e;
270
    e = new goog.events.Event(type, target);
271
    goog.object.extend(e, oldEvent);
272
  } else {
273
    e.target = e.target || target;
274
  }
275

276
  var rv = true, currentTarget;
277

278
  // Executes all capture listeners on the ancestors, if any.
279
  if (opt_ancestorsTree) {
280
    for (var i = opt_ancestorsTree.length - 1; !e.propagationStopped_ && i >= 0;
281
         i--) {
282
      currentTarget = e.currentTarget = opt_ancestorsTree[i];
283
      rv = currentTarget.fireListeners(type, true, e) && rv;
284
    }
285
  }
286

287
  // Executes capture and bubble listeners on the target.
288
  if (!e.propagationStopped_) {
289
    currentTarget = e.currentTarget = target;
290
    rv = currentTarget.fireListeners(type, true, e) && rv;
291
    if (!e.propagationStopped_) {
292
      rv = currentTarget.fireListeners(type, false, e) && rv;
293
    }
294
  }
295

296
  // Executes all bubble listeners on the ancestors, if any.
297
  if (opt_ancestorsTree) {
298
    for (i = 0; !e.propagationStopped_ && i < opt_ancestorsTree.length; i++) {
299
      currentTarget = e.currentTarget = opt_ancestorsTree[i];
300
      rv = currentTarget.fireListeners(type, false, e) && rv;
301
    }
302
  }
303

304
  return rv;
305
};
306

307