Update OpenSeadragon.Placement to be serializable.

src/openseadragon.js

@@ -154,7 +154,7 @@
   *       created.
   *     * placement a string to define the relative position to the viewport.
   *       Only used if no width and height are specified. Default: 'TOP_LEFT'.
-  *       See {@link OpenSeadragon.OverlayPlacement} for possible values.
+  *       See {@link OpenSeadragon.Placement} for possible values.
   *
   * @property {String} [xmlPath=null]
   *     <strong>DEPRECATED</strong>. A relative path to load a DZI file from the server.
@@ -842,6 +842,21 @@ if (typeof define === 'function' && define.amd) {
         return true;
     };
 
+    /**
+     * Shim around Object.freeze. Does nothing if Object.freeze is not supported.
+     * @param {Object} obj The object to freeze.
+     * @return {Object} obj The frozen object.
+     */
+    $.freezeObject = function(obj) {
+        if (Object.freeze) {
+            $.freezeObject = Object.freeze;
+        } else {
+            $.freezeObject = function(obj) {
+                return obj;
+            };
+        }
+        return $.freezeObject(obj);
+    };
 
     /**
      * True if the browser supports the HTML5 canvas element

src/overlay.js

@@ -37,6 +37,8 @@
     /**
      * An enumeration of positions that an overlay may be assigned relative to
      * the viewport.
+     * It is identical to OpenSeadragon.Placement but is kept for backward
+     * compatibility.
      * @member OverlayPlacement
      * @memberof OpenSeadragon
      * @static
@@ -51,17 +53,7 @@
      * @property {Number} BOTTOM_LEFT
      * @property {Number} LEFT
      */
-    $.OverlayPlacement = {
+    $.OverlayPlacement = $.Placement;
-        CENTER:       0,
-        TOP_LEFT:     1,
-        TOP:          2,
-        TOP_RIGHT:    3,
-        RIGHT:        4,
-        BOTTOM_RIGHT: 5,
-        BOTTOM:       6,
-        BOTTOM_LEFT:  7,
-        LEFT:         8
-    };
 
     /**
      * @class Overlay
@@ -75,7 +67,7 @@
      * is specified, the overlay will keep a constant size independently of the
      * zoom. If a {@link OpenSeadragon.Rect} is specified, the overlay size will
      * be adjusted when the zoom changes.
-     * @param {OpenSeadragon.OverlayPlacement} [options.placement=OpenSeadragon.OverlayPlacement.TOP_LEFT]
+     * @param {OpenSeadragon.Placement} [options.placement=OpenSeadragon.Placement.TOP_LEFT]
      * Relative position to the viewport.
      * Only used if location is a {@link OpenSeadragon.Point}.
      * @param {OpenSeadragon.Overlay.OnDrawCallback} [options.onDraw]
@@ -126,8 +118,7 @@
         this.style      = options.element.style;
         // rects are always top-left
         this.placement  = options.location instanceof $.Point ?
-            options.placement :
+            options.placement : $.Placement.TOP_LEFT;
-            $.OverlayPlacement.TOP_LEFT;
         this.onDraw = options.onDraw;
         this.checkResize = options.checkResize === undefined ?
             true : options.checkResize;
@@ -138,42 +129,23 @@
 
         /**
          * @function
-         * @param {OpenSeadragon.OverlayPlacement} position
+         * @param {OpenSeadragon.Point} position
          * @param {OpenSeadragon.Point} size
          */
-        adjust: function( position, size ) {
+        adjust: function(position, size) {
-            switch ( this.placement ) {
+            var properties = $.Placement.properties[this.placement];
-                case $.OverlayPlacement.TOP_LEFT:
+            if (!properties) {
-                    break;
+                return;
-                case $.OverlayPlacement.TOP:
+            }
-                    position.x -= size.x / 2;
+            if (properties.isHorizontallyCentered) {
-                    break;
+                position.x -= size.x / 2;
-                case $.OverlayPlacement.TOP_RIGHT:
+            } else if (properties.isRight) {
-                    position.x -= size.x;
+                position.x -= size.x;
-                    break;
+            }
-                case $.OverlayPlacement.RIGHT:
+            if (properties.isVerticallyCentered) {
-                    position.x -= size.x;
+                position.y -= size.y / 2;
-                    position.y -= size.y / 2;
+            } else if (properties.isBottom) {
-                    break;
+                position.y -= size.y;
-                case $.OverlayPlacement.BOTTOM_RIGHT:
-                    position.x -= size.x;
-                    position.y -= size.y;
-                    break;
-                case $.OverlayPlacement.BOTTOM:
-                    position.x -= size.x / 2;
-                    position.y -= size.y;
-                    break;
-                case $.OverlayPlacement.BOTTOM_LEFT:
-                    position.y -= size.y;
-                    break;
-                case $.OverlayPlacement.LEFT:
-                    position.y -= size.y / 2;
-                    break;
-                default:
-                case $.OverlayPlacement.CENTER:
-                    position.x -= size.x / 2;
-                    position.y -= size.y / 2;
-                    break;
             }
         },
 
@@ -298,7 +270,7 @@
         /**
          * @function
          * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location
-         * @param {OpenSeadragon.OverlayPlacement} position
+         * @param {OpenSeadragon.Placement} position
          */
         update: function( location, placement ) {
             this.scales     = location instanceof $.Rect;
@@ -310,8 +282,7 @@
             );
             // rects are always top-left
             this.placement  = location instanceof $.Point ?
-                placement :
+                placement : $.Placement.TOP_LEFT;
-                $.OverlayPlacement.TOP_LEFT;
         },
 
         /**

src/placement.js

@@ -47,79 +47,90 @@
      * @property {OpenSeadragon.Placement} BOTTOM_LEFT
      * @property {OpenSeadragon.Placement} LEFT
      */
-    $.Placement = {
+    $.Placement = $.freezeObject({
-        CENTER: {
+        CENTER:       0,
-            isLeft: false,
+        TOP_LEFT:     1,
-            isHorizontallyCentered: true,
+        TOP:          2,
-            isRight: false,
+        TOP_RIGHT:    3,
-            isTop: false,
+        RIGHT:        4,
-            isVerticallyCentered: true,
+        BOTTOM_RIGHT: 5,
-            isBottom: false
+        BOTTOM:       6,
-        },
+        BOTTOM_LEFT:  7,
-        TOP_LEFT: {
+        LEFT:         8,
-            isLeft: true,
+        properties: {
-            isHorizontallyCentered: false,
+            0: {
-            isRight: false,
+                isLeft: false,
-            isTop: true,
+                isHorizontallyCentered: true,
-            isVerticallyCentered: false,
+                isRight: false,
-            isBottom: false
+                isTop: false,
-        },
+                isVerticallyCentered: true,
-        TOP: {
+                isBottom: false
-            isLeft: false,
+            },
-            isHorizontallyCentered: true,
+            1: {
-            isRight: false,
+                isLeft: true,
-            isTop: true,
+                isHorizontallyCentered: false,
-            isVerticallyCentered: false,
+                isRight: false,
-            isBottom: false
+                isTop: true,
-        },
+                isVerticallyCentered: false,
-        TOP_RIGHT: {
+                isBottom: false
-            isLeft: false,
+            },
-            isHorizontallyCentered: false,
+            2: {
-            isRight: true,
+                isLeft: false,
-            isTop: true,
+                isHorizontallyCentered: true,
-            isVerticallyCentered: false,
+                isRight: false,
-            isBottom: false
+                isTop: true,
-        },
+                isVerticallyCentered: false,
-        RIGHT: {
+                isBottom: false
-            isLeft: false,
+            },
-            isHorizontallyCentered: false,
+            3: {
-            isRight: true,
+                isLeft: false,
-            isTop: false,
+                isHorizontallyCentered: false,
-            isVerticallyCentered: true,
+                isRight: true,
-            isBottom: false
+                isTop: true,
-        },
+                isVerticallyCentered: false,
-        BOTTOM_RIGHT: {
+                isBottom: false
-            isLeft: false,
+            },
-            isHorizontallyCentered: false,
+            4: {
-            isRight: true,
+                isLeft: false,
-            isTop: false,
+                isHorizontallyCentered: false,
-            isVerticallyCentered: false,
+                isRight: true,
-            isBottom: true
+                isTop: false,
-        },
+                isVerticallyCentered: true,
-        BOTTOM: {
+                isBottom: false
-            isLeft: false,
+            },
-            isHorizontallyCentered: true,
+            5: {
-            isRight: false,
+                isLeft: false,
-            isTop: false,
+                isHorizontallyCentered: false,
-            isVerticallyCentered: false,
+                isRight: true,
-            isBottom: true
+                isTop: false,
-        },
+                isVerticallyCentered: false,
-        BOTTOM_LEFT: {
+                isBottom: true
-            isLeft: true,
+            },
-            isHorizontallyCentered: false,
+            6: {
-            isRight: false,
+                isLeft: false,
-            isTop: false,
+                isHorizontallyCentered: true,
-            isVerticallyCentered: false,
+                isRight: false,
-            isBottom: true
+                isTop: false,
-        },
+                isVerticallyCentered: false,
-        LEFT: {
+                isBottom: true
-            isLeft: true,
+            },
-            isHorizontallyCentered: false,
+            7: {
-            isRight: false,
+                isLeft: true,
-            isTop: false,
+                isHorizontallyCentered: false,
-            isVerticallyCentered: true,
+                isRight: false,
-            isBottom: false
+                isTop: false,
+                isVerticallyCentered: false,
+                isBottom: true
+            },
+            8: {
+                isLeft: true,
+                isHorizontallyCentered: false,
+                isRight: false,
+                isTop: false,
+                isVerticallyCentered: true,
+                isBottom: false
+            }
         }
-    };
+    });
 
 }(OpenSeadragon));

src/tiledimage.js

@@ -556,13 +556,14 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
      */
     fitInBounds: function(bounds, anchor, immediately) {
         anchor = anchor || $.Placement.CENTER;
+        var anchorProperties = $.Placement.properties[anchor];
         if (bounds.getAspectRatio() > this.contentAspectX) {
             // We will have margins on the X axis
             var targetWidth = bounds.height * this.contentAspectX;
             var marginLeft = 0;
-            if (anchor.isHorizontallyCentered) {
+            if (anchorProperties.isHorizontallyCentered) {
                 marginLeft = (bounds.width - targetWidth) / 2;
-            } else if (anchor.isRight) {
+            } else if (anchorProperties.isRight) {
                 marginLeft = bounds.width - targetWidth;
             }
             this.setPosition(
@@ -573,9 +574,9 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
             // We will have margins on the Y axis
             var targetHeight = bounds.width / this.contentAspectX;
             var marginTop = 0;
-            if (anchor.isVerticallyCentered) {
+            if (anchorProperties.isVerticallyCentered) {
                 marginTop = (bounds.height - targetHeight) / 2;
-            } else if (anchor.isBottom) {
+            } else if (anchorProperties.isBottom) {
                 marginTop = bounds.height - targetHeight;
             }
             this.setPosition(

src/viewer.js

@@ -1785,7 +1785,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      *      the element which will be overlayed. Or an Object specifying the configuration for the overlay
      * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location - The point or
      *      rectangle which will be overlayed. This is a viewport relative location.
-     * @param {OpenSeadragon.OverlayPlacement} placement - The position of the
+     * @param {OpenSeadragon.Placement} 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
@@ -1827,7 +1827,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
          * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
          * @property {Element} element - The overlay element.
          * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location
-         * @property {OpenSeadragon.OverlayPlacement} placement
+         * @property {OpenSeadragon.Placement} placement
          * @property {?Object} userData - Arbitrary subscriber-defined object.
          */
         this.raiseEvent( 'add-overlay', {
@@ -1846,7 +1846,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      *      the element which is overlayed.
      * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location - The point or
      *      rectangle which will be overlayed. This is a viewport relative location.
-     * @param {OpenSeadragon.OverlayPlacement} placement - The position of the
+     * @param {OpenSeadragon.Placement} placement - The position of the
      *      viewport which the location coordinates will be treated as relative
      *      to.
      * @return {OpenSeadragon.Viewer} Chainable.
@@ -1872,7 +1872,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
              * Viewer which raised the event.
              * @property {Element} element
              * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location
-             * @property {OpenSeadragon.OverlayPlacement} placement
+             * @property {OpenSeadragon.Placement} placement
              * @property {?Object} userData - Arbitrary subscriber-defined object.
              */
             this.raiseEvent( 'update-overlay', {
@@ -2222,8 +2222,8 @@ function getOverlayObject( viewer, overlay ) {
     }
 
     var placement = overlay.placement;
-    if ( placement && ( $.type( placement ) === "string" ) ) {
+    if (placement && $.type(placement) === "string") {
-        placement = $.OverlayPlacement[ overlay.placement.toUpperCase() ];
+        placement = $.Placement[overlay.placement.toUpperCase()];
     }
 
     return new $.Overlay({

test/modules/overlays.js

@@ -397,6 +397,7 @@
             checkFixedOverlayPosition( new OpenSeadragon.Point( 0, 0 ),
                 "with TOP_LEFT placement." );
 
+            // Check that legacy OpenSeadragon.OverlayPlacement is still working
             viewer.updateOverlay( "overlay", scalableOverlayLocation,
                 OpenSeadragon.OverlayPlacement.CENTER );
             viewer.updateOverlay( "fixed-overlay", fixedOverlayLocation,
@@ -407,10 +408,11 @@
                 checkFixedOverlayPosition( new OpenSeadragon.Point( -35, -30 ),
                     "with CENTER placement." );
 
+                // Check that new OpenSeadragon.Placement is working
                 viewer.updateOverlay( "overlay", scalableOverlayLocation,
-                    OpenSeadragon.OverlayPlacement.BOTTOM_RIGHT );
+                    OpenSeadragon.Placement.BOTTOM_RIGHT );
                 viewer.updateOverlay( "fixed-overlay", fixedOverlayLocation,
-                    OpenSeadragon.OverlayPlacement.BOTTOM_RIGHT );
+                    OpenSeadragon.Placement.BOTTOM_RIGHT );
                 setTimeout( function() {
                     checkScalableOverlayPosition( "with BOTTOM_RIGHT placement." );
                     checkFixedOverlayPosition( new OpenSeadragon.Point( -70, -60 ),