Merge pull request #348 from fs-webdev/tile-drawing-event

Added pre-draw event for tiles to allow applications to alter the image ...

src/drawer.js

@@ -1228,6 +1228,25 @@ function drawTiles( drawer, lastDrawn ){
         tileSource,
         collectionTileSource;
 
+    // We need a callback to give image manipulation a chance to happen
+    var drawingHandler = function(args) {
+        if (drawer.viewer) {
+          /**
+           * This event is fired just before the tile is drawn giving the application a chance to alter the image.
+           *
+           * NOTE: This event is only fired when the drawer is using a <canvas>.
+           *
+           * @event tile-drawing
+           * @memberof OpenSeadragon.Viewer
+           * @type {object}
+           * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+           * @property {OpenSeadragon.Tile} tile
+           * @property {?Object} userData - 'context', 'tile' and 'rendered'.
+           */
+            drawer.viewer.raiseEvent('tile-drawing', args);
+        }
+    };
+
     for ( i = lastDrawn.length - 1; i >= 0; i-- ) {
         tile = lastDrawn[ i ];
 
@@ -1299,10 +1318,10 @@ function drawTiles( drawer, lastDrawn ){
                 // specifically, don't save,rotate,restore every time we draw a tile
                 if( drawer.viewport.degrees !== 0 ) {
                     offsetForRotation( tile, drawer.canvas, drawer.context, drawer.viewport.degrees );
-                    tile.drawCanvas( drawer.context );
+                    tile.drawCanvas( drawer.context, drawingHandler );
                     restoreRotationChanges( tile, drawer.canvas, drawer.context );
                 } else {
-                    tile.drawCanvas( drawer.context );
+                    tile.drawCanvas( drawer.context, drawingHandler );
                 }
             } else {
                 tile.drawHTML( drawer.canvas );

src/tile.js

@@ -231,8 +231,10 @@ $.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{
      * Renders the tile in a canvas-based context.
      * @function
      * @param {Canvas} context
+     * @param {Function} method for firing the drawing event. drawingHandler({context, tile, rendered})
+     * where <code>rendered</code> is the context with the pre-drawn image.
      */
-    drawCanvas: function( context ) {
+    drawCanvas: function( context, drawingHandler ) {
 
         var position = this.position,
             size     = this.size,
@@ -280,6 +282,9 @@ $.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{
 
         rendered = TILE_CACHE[ this.url ];
 
+        // This gives the application a chance to make image manipulation changes as we are rendering the image
+        drawingHandler({context: context, tile: this, rendered: rendered});
+
         //rendered.save();
         context.drawImage(
             rendered.canvas,

test/events.js

@@ -280,4 +280,23 @@
         viewer.open( '/test/data/testpattern.dzi' );
     } );
 
+    // ----------
+    asyncTest( 'tile-drawing event', function () {
+        var tileDrawing = function ( event ) {
+            viewer.removeHandler( 'tile-drawing', tileDrawing );
+            ok( event, 'Event handler should be invoked' );
+            if ( event ) {
+                // Make sure we have the expected elements set
+                ok(event.context, "Context should be set");
+                ok(event.tile, "Tile should be set");
+                ok(event.rendered, "Rendered should be set");
+            }
+            viewer.close();
+            start();
+        };
+
+        viewer.addHandler( 'tile-drawing', tileDrawing );
+        viewer.open( '/test/data/testpattern.dzi' );
+    } );
+
 } )();