Add ol.Observable for on, once, un, and unByKey methods

src/ol/observable.exports

@@ -0,0 +1,4 @@
+@exportProperty ol.Observable.prototype.on
+@exportProperty ol.Observable.prototype.once
+@exportProperty ol.Observable.prototype.un
+@exportProperty ol.Observable.prototype.unByKey

src/ol/observable.js

@@ -0,0 +1,70 @@
+goog.provide('ol.Observable');
+
+goog.require('goog.events');
+goog.require('goog.events.EventTarget');
+
+
+
+/**
+ * An event target providing convenient methods for listener registration
+ * and unregistration.
+ * @constructor
+ * @extends {goog.events.EventTarget}
+ * @todo stability experimental
+ */
+ol.Observable = function() {
+  goog.base(this);
+
+};
+goog.inherits(ol.Observable, goog.events.EventTarget);
+
+
+/**
+ * Listen for a certain type of event.
+ * @param {string|Array.<string>} type The event type or array of event types.
+ * @param {function(?): ?} listener The listener function.
+ * @param {Object=} opt_scope Object is whose scope to call
+ *     the listener.
+ * @return {goog.events.Key} Unique key for the listener.
+ * @todo stability experimental
+ */
+ol.Observable.prototype.on = function(type, listener, opt_scope) {
+  return goog.events.listen(this, type, listener, false, opt_scope);
+};
+
+
+/**
+ * Listen once for a certain type of event.
+ * @param {string|Array.<string>} type The event type or array of event types.
+ * @param {function(?): ?} listener The listener function.
+ * @param {Object=} opt_scope Object is whose scope to call
+ *     the listener.
+ * @return {goog.events.Key} Unique key for the listener.
+ * @todo stability experimental
+ */
+ol.Observable.prototype.once = function(type, listener, opt_scope) {
+  return goog.events.listenOnce(this, type, listener, false, opt_scope);
+};
+
+
+/**
+ * Unlisten for a certain type of event.
+ * @param {string|Array.<string>} type The event type or array of event types.
+ * @param {function(?): ?} listener The listener function.
+ * @param {Object=} opt_scope Object is whose scope to call
+ *     the listener.
+ * @todo stability experimental
+ */
+ol.Observable.prototype.un = function(type, listener, opt_scope) {
+  goog.events.unlisten(this, type, listener, false, opt_scope);
+};
+
+
+/**
+ * Removes an event listener using the key returned by `on()` or `once()`.
+ * @param {goog.events.Key} key Key.
+ * @todo stability experimental
+ */
+ol.Observable.prototype.unByKey = function(key) {
+  goog.events.unlistenByKey(key);
+};

test/spec/ol/observable.test.js

@@ -0,0 +1,172 @@
+goog.provide('ol.test.Observable');
+
+describe('ol.Observable', function() {
+
+  describe('constructor', function() {
+
+    it('creates a new observable', function() {
+      var observable = new ol.Observable();
+      expect(observable).to.be.a(ol.Observable);
+      expect(observable).to.be.a(goog.events.EventTarget);
+    });
+
+  });
+
+  describe('#on()', function() {
+    var observable, listener;
+    beforeEach(function() {
+      observable = new ol.Observable();
+      listener = sinon.spy();
+    });
+
+    it('registers a listener for events of the given type', function() {
+      observable.on('foo', listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(2);
+    });
+
+    it('accepts an array of event types', function() {
+      observable.on(['foo', 'bar'], listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.dispatchEvent('bar');
+      expect(listener.callCount).to.be(2);
+    });
+
+    it('accepts an optional `this` arg for the listener', function() {
+      var thisArg = {};
+      observable.on('foo', listener, thisArg);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+      expect(listener.calledOn(thisArg)).to.be(true);
+    });
+
+    it('returns a listener key', function() {
+      var key = observable.on('foo', listener);
+
+      expect(key).to.be.a(goog.events.Listener);
+    });
+
+  });
+
+  describe('#once()', function() {
+    var observable, listener;
+    beforeEach(function() {
+      observable = new ol.Observable();
+      listener = sinon.spy();
+    });
+
+    it('registers a listener that is only called once', function() {
+      observable.once('foo', listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(1);
+    });
+
+    it('accepts an array of event types (called once for each)', function() {
+      observable.once(['foo', 'bar'], listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(1);
+
+      observable.dispatchEvent('bar');
+      expect(listener.callCount).to.be(2);
+
+      observable.dispatchEvent('bar');
+      expect(listener.callCount).to.be(2);
+    });
+
+    it('accepts an optional `this` arg for the listener', function() {
+      var thisArg = {};
+      observable.once('foo', listener, thisArg);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+      expect(listener.calledOn(thisArg)).to.be(true);
+    });
+
+    it('returns a listener key', function() {
+      var key = observable.once('foo', listener);
+
+      expect(key).to.be.a(goog.events.Listener);
+    });
+
+  });
+
+  describe('#un()', function() {
+    var observable, listener;
+    beforeEach(function() {
+      observable = new ol.Observable();
+      listener = sinon.spy();
+    });
+
+    it('unregisters a previously registered listener', function() {
+      observable.on('foo', listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.un('foo', listener);
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+    });
+
+    it('accepts a `this` arg', function() {
+      var thisArg = {};
+      observable.on('foo', listener, thisArg);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      // will not unregister without the same thisArg
+      observable.un('foo', listener);
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(2);
+
+      // properly unregister by providing the same thisArg
+      observable.un('foo', listener, thisArg);
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(2);
+    });
+
+  });
+
+  describe('#unByKey()', function() {
+    var observable, listener;
+    beforeEach(function() {
+      observable = new ol.Observable();
+      listener = sinon.spy();
+    });
+
+    it('unregisters a listener given the key returned by `on`', function() {
+      var key = observable.on('foo', listener);
+
+      observable.dispatchEvent('foo');
+      expect(listener.calledOnce).to.be(true);
+
+      observable.unByKey(key);
+      observable.dispatchEvent('foo');
+      expect(listener.callCount).to.be(1);
+    });
+
+  });
+
+});
+
+
+goog.require('goog.events.EventTarget');
+goog.require('goog.events.Listener');
+goog.require('ol.Observable');