Merge pull request #160 from lukemurray/custom_zoom_handler

Add the option for a zoom handler callback

src/drawer.js

@@ -161,30 +161,50 @@ $.Drawer.prototype = {
      * highlighting words or areas of interest on an image or other zoomable
      * interface.
      * @method
-     * @param {Element|String} element - A reference to an element or an id for
+     * @param {Element|String|Object} element - A reference to an element or an id for
-     *      the element which will overlayed.
+     *      the element which will overlayed. Or an Object specifying the configuration for the overlay
      * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location - The point or
      *      rectangle which will be overlayed.
      * @param {OpenSeadragon.OverlayPlacement} placement - The position of the
      *      viewport which the location coordinates will be treated as relative
      *      to.
+     * @param {function} onDraw - If supplied the callback is called when the overlay 
+     *      needs to be drawn. It it the responsibility of the callback to do any drawing/positioning.
+     *      It is passed position, size and element.
      */
-    addOverlay: function( element, location, placement ) {
+    addOverlay: function( element, location, placement, onDraw ) {
-        element = $.getElement( element );
+        var options;
+        if( $.isPlainObject( element ) ){
+            options = element;
+        } else {
+            options = {
+                element: element,
+                location: location,
+                placement: placement,
+                onDraw: onDraw
+            };
+        }
+
+        element = $.getElement(options.element);
 
         if ( getOverlayIndex( this.overlays, element ) >= 0 ) {
             // they're trying to add a duplicate overlay
             return;
         }
 
-        this.overlays.push( new $.Overlay( element, location, placement ) );
+        this.overlays.push( new $.Overlay({
+            element: element,
+            location: options.location,
+            placement: options.placement,
+            onDraw: options.onDraw
+        }) );
         this.updateAgain = true;
         if( this.viewer ){
             this.viewer.raiseEvent( 'add-overlay', {
                 viewer: this.viewer,
                 element: element,
-                location: location,
+                location: options.location,
-                placement: placement
+                placement: options.placement
             });
         }
         return this;
@@ -423,14 +443,20 @@ $.Drawer.prototype = {
         //we need to translate to viewport coordinates
         rect = drawer.viewport.imageToViewportRectangle( rect );
     }
+    
     if( overlay.placement ){
-        return new $.Overlay(
+        return new $.Overlay({
-            element,
+            element: element,
-            drawer.viewport.pointFromPixel(rect),
+            location: drawer.viewport.pointFromPixel(rect),
-            $.OverlayPlacement[overlay.placement.toUpperCase()]
+            placement: $.OverlayPlacement[overlay.placement.toUpperCase()],
-        );
+            onDraw: overlay.onDraw
+        });
     }else{
-        return new $.Overlay( element, rect );
+        return new $.Overlay({
+            element: element,
+            location: rect,
+            onDraw: overlay.onDraw
+        });
     }
 
 }

src/overlay.js

@@ -57,27 +57,40 @@
      * @class
      */
     $.Overlay = function( element, location, placement ) {
-        this.element    = element;
+
-        this.scales     = location instanceof $.Rect;
+        var options;
+        if( $.isPlainObject( element ) ){
+            options = element;
+        } else{
+            options = {
+                element: element,
+                location: location,
+                placement: placement
+            };
+        }
+        
+        this.element    = options.element;
+        this.scales     = options.location instanceof $.Rect;
         this.bounds     = new $.Rect(
-            location.x,
+            options.location.x,
-            location.y,
+            options.location.y,
-            location.width,
+            options.location.width,
-            location.height
+            options.location.height
         );
         this.position   = new $.Point(
-            location.x,
+            options.location.x,
-            location.y
+            options.location.y
         );
         this.size       = new $.Point(
-            location.width,
+            options.location.width,
-            location.height
+            options.location.height
         );
-        this.style      = element.style;
+        this.style      = options.element.style;
         // rects are always top-left
-        this.placement  = location instanceof $.Point ?
+        this.placement  = options.location instanceof $.Point ?
-            placement :
+            options.placement :
             $.OverlayPlacement.TOP_LEFT;
+        this.onDraw = options.onDraw;
     };
 
     $.Overlay.prototype = {
@@ -184,6 +197,11 @@
             position = position.apply( Math.floor );
             size     = size.apply( Math.ceil );
 
+            // call the onDraw callback if there is one to allow, this allows someone to overwrite
+            // the drawing/positioning/sizing of the overlay
+            if (this.onDraw) {
+                this.onDraw(position, size, element);
+            } else {
                 style.left     = position.x + "px";
                 style.top      = position.y + "px";
                 style.position = "absolute";
@@ -193,6 +211,7 @@
                     style.width  = size.x + "px";
                     style.height = size.y + "px";
                 }
+            }
         },
 
         /**