Merge pull request #887 from avandecreme/eventsource

Add addOnceHandler method to EventSource.

src/eventsource.js

@@ -56,7 +56,31 @@ $.EventSource = function() {
 /** @lends OpenSeadragon.EventSource.prototype */
 $.EventSource.prototype = {
 
-    // TODO: Add a method 'one' which automatically unbinds a listener after the first triggered event that matches.
+    /**
+     * Add an event handler to be triggered only once (or a given number of times)
+     * for a given event.
+     * @function
+     * @param {String} eventName - Name of event to register.
+     * @param {OpenSeadragon.EventHandler} handler - Function to call when event
+     * is triggered.
+     * @param {Object} [userData=null] - Arbitrary object to be passed unchanged
+     * to the handler.
+     * @param {Number} [times=1] - The number of times to handle the event
+     * before removing it.
+     */
+    addOnceHandler: function(eventName, handler, userData, times) {
+        var self = this;
+        times = times || 1;
+        var count = 0;
+        var onceHandler = function(event) {
+            count++;
+            if (count === times) {
+                self.removeHandler(eventName, onceHandler);
+            }
+            handler(event);
+        };
+        this.addHandler(eventName, onceHandler, userData);
+    },
 
     /**
      * Add an event handler for a given event.

test/modules/events.js

@@ -949,6 +949,59 @@
         viewer.open( '/test/data/testpattern.dzi' );
     } );
 
+    // ----------
+    test('EventSource: addOnceHandler', function() {
+        var eventSource = new OpenSeadragon.EventSource();
+        var userData = 'data';
+        var eventData = {
+            foo: 1
+        };
+        var handlerCalledCount = 0;
+        eventSource.addOnceHandler('test-event', function(event) {
+            handlerCalledCount++;
+            strictEqual(event.foo, eventData.foo,
+                'Event data should be transmitted to the event.');
+            strictEqual(event.userData, userData,
+                'User data should be transmitted to the event.');
+        }, userData);
+        strictEqual(0, handlerCalledCount,
+            'Handler should not have been called yet.');
+        eventSource.raiseEvent('test-event', eventData);
+        strictEqual(1, handlerCalledCount,
+            'Handler should have been called once.');
+        eventSource.raiseEvent('test-event', eventData);
+        strictEqual(1, handlerCalledCount,
+            'Handler should still have been called once.');
+    });
+
+    // ----------
+    test('EventSource: addOnceHandler 2 times', function() {
+        var eventSource = new OpenSeadragon.EventSource();
+        var userData = 'data';
+        var eventData = {
+            foo: 1
+        };
+        var handlerCalledCount = 0;
+        eventSource.addOnceHandler('test-event', function(event) {
+            handlerCalledCount++;
+            strictEqual(event.foo, eventData.foo,
+                'Event data should be transmitted to the event.');
+            strictEqual(event.userData, userData,
+                'User data should be transmitted to the event.');
+        }, userData, 2);
+        strictEqual(0, handlerCalledCount,
+            'Handler should not have been called yet.');
+        eventSource.raiseEvent('test-event', eventData);
+        strictEqual(1, handlerCalledCount,
+            'Handler should have been called once.');
+        eventSource.raiseEvent('test-event', eventData);
+        strictEqual(2, handlerCalledCount,
+            'Handler should have been called twice.');
+        eventSource.raiseEvent('test-event', eventData);
+        strictEqual(2, handlerCalledCount,
+            'Handler should still have been called twice.');
+    });
+
     // ----------
     asyncTest( 'Viewer: tile-drawing event', function () {
         var tileDrawing = function ( event ) {