Docs and naming changes for collection mode

changelog.txt

@@ -19,9 +19,11 @@ OPENSEADRAGON CHANGELOG
     * DEPRECATION: use Drawer.clear and World.update instead of Drawer.update
     * DEPRECATION: the layersAspectRatioEpsilon option is no longer necessary
     * DEPRECATION: Viewer's add-layer event is now World's add-item event
-    * DEPRECATION: Viewer's layer-level-changed event is now World's item-index-changed event
+    * DEPRECATION: Viewer's layer-level-changed event is now World's item-index-change event
     * DEPRECATION: Viewer's remove-layer event is now World's remove-item event
     * DEPRECATION: Viewer's add-layer-failed event is now add-item-failed
+    * DEPRECATION: TileSourceCollection has been retired in favor of World
+    * DEPRECATION: collectionMode no longer draws outlines or reflections for items
     * Drawer has been split into three classes:
         * TiledImage, tile management and positioning for a single tiled image
         * TileCache, tile caching for all images

src/navigator.js

@@ -239,7 +239,7 @@ $.Navigator = function( options ){
         }
     });
 
-    viewer.world.addHandler("item-index-changed", function(event) {
+    viewer.world.addHandler("item-index-change", function(event) {
         var item = _this.world.getItemAt(event.previousIndex);
         _this.world.setItemIndex(item, event.newIndex);
     });

src/openseadragon.js

@@ -531,14 +531,21 @@
   * @property {Number} [referenceStripSizeRatio=0.2]
   *
   * @property {Boolean} [collectionMode=false]
+  *     Set to true to have the viewer arrange your TiledImages in a grid or line.
   *
   * @property {Number} [collectionRows=3]
+  *     If collectionMode is true, specifies how many rows the grid should have. Use 1 to make a line.
+  *     If collectionLayout is 'vertical', specifies how many columns instead.
   *
   * @property {String} [collectionLayout='horizontal']
+  *     If collectionMode is true, specifies whether to arrange vertically or horizontally.
   *
   * @property {Number} [collectionTileSize=800]
+  *     If collectionMode is true, specifies the size, in world coordinates, for each TiledImage to fit into.
+  *     The TiledImage will be centered within a square of the specified size.
   *
   * @property {Number} [collectionTileMargin=80]
+  *     If collectionMode is true, specifies the margin, in world coordinates, between each TiledImage.
   *
   * @property {String|Boolean} [crossOriginPolicy=false]
   *      Valid values are 'Anonymous', 'use-credentials', and false. If false, canvas requests will

src/tiledimage.js

@@ -166,10 +166,16 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
     /**
      * @returns {OpenSeadragon.Rect} This TiledImage's bounds in world coordinates.
      */
-    getWorldBounds: function() {
+    getBounds: function() {
         return new $.Rect( this._worldX, this._worldY, this._worldWidth, this._worldHeight );
     },
 
+    // deprecated
+    getWorldBounds: function() {
+        $.console.error('[TiledImage.getWorldBounds] is deprecated; use TiledImage.getBounds instead');
+        return this.getBounds();
+    },
+
     /**
      * @returns {OpenSeadragon.Point} This TiledImage's content size, in original pixels.
      */
@@ -178,7 +184,9 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
     },
 
     /**
-     * @fires OpenSeadragon.TiledImage.event:bounds-changed
+     * Sets the TiledImage's position in the world.
+     * @param {OpenSeadragon.Point} position - The new position, in world coordinates.
+     * @fires OpenSeadragon.TiledImage.event:bounds-change
      */
     setPosition: function(position) {
         if (this._worldX === position.x && this._worldY === position.y) {
@@ -188,11 +196,13 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
         this._worldX = position.x;
         this._worldY = position.y;
         this.updateAgain = true;
-        this._raiseBoundsChanged();
+        this._raiseBoundsChange();
     },
 
     /**
-     * @fires OpenSeadragon.TiledImage.event:bounds-changed
+     * Sets the TiledImage's width in the world, adjusting the height to match based on aspect ratio.
+     * @param {Number} width - The new width, in world coordinates.
+     * @fires OpenSeadragon.TiledImage.event:bounds-change
      */
     setWidth: function(width) {
         if (this._worldWidth === width) {
@@ -201,11 +211,13 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
 
         this._setScale(width);
         this.updateAgain = true;
-        this._raiseBoundsChanged();
+        this._raiseBoundsChange();
     },
 
     /**
-     * @fires OpenSeadragon.TiledImage.event:bounds-changed
+     * Sets the TiledImage's height in the world, adjusting the width to match based on aspect ratio.
+     * @param {Number} height - The new height, in world coordinates.
+     * @fires OpenSeadragon.TiledImage.event:bounds-change
      */
     setHeight: function(height) {
         if (this._worldHeight === height) {
@@ -214,25 +226,27 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
 
         this._setScale(height / this.normHeight);
         this.updateAgain = true;
-        this._raiseBoundsChanged();
+        this._raiseBoundsChange();
     },
 
+    // private
     _setScale: function(scale) {
         this._scale = scale;
         this._worldWidth = this._scale;
         this._worldHeight = this.normHeight * this._scale;
     },
 
-    _raiseBoundsChanged: function() {
+    // private
+    _raiseBoundsChange: function() {
         /**
          * Raised when the TiledImage's bounds are changed.
-         * @event bounds-changed
+         * @event bounds-change
          * @memberOf OpenSeadragon.TiledImage
          * @type {object}
          * @property {OpenSeadragon.World} eventSource - A reference to the TiledImage which raised the event.
          * @property {?Object} userData - Arbitrary subscriber-defined object.
          */
-        this.raiseEvent('bounds-changed');
+        this.raiseEvent('bounds-change');
     }
 });
 

src/tilesourcecollection.js

@@ -34,110 +34,9 @@
 
 (function( $ ){
 
-/**
+// deprecated
- * @class TileSourceCollection
- * @memberof OpenSeadragon
- * @extends OpenSeadragon.TileSource
- */
 $.TileSourceCollection = function( tileSize, tileSources, rows, layout  ) {
-    var options;
+    $.console.error('TileSourceCollection is deprecated; use World instead');
-
-    if( $.isPlainObject( tileSize ) ){
-        options = tileSize;
-    }else{
-        options = {
-            tileSize: arguments[ 0 ],
-            tileSources: arguments[ 1 ],
-            rows: arguments[ 2 ],
-            layout: arguments[ 3 ]
 };
-    }
-
-    if( !options.layout ){
-        options.layout = 'horizontal';
-    }
-
-    var minLevel = 0,
-        levelSize = 1.0,
-        tilesPerRow = Math.ceil( options.tileSources.length / options.rows ),
-        longSide = tilesPerRow >= options.rows ?
-            tilesPerRow :
-            options.rows;
-
-    if( 'horizontal' == options.layout ){
-        options.width = ( options.tileSize ) * tilesPerRow;
-        options.height = ( options.tileSize ) * options.rows;
-    } else {
-        options.height = ( options.tileSize ) * tilesPerRow;
-        options.width = ( options.tileSize ) * options.rows;
-    }
-
-    options.tileOverlap = -options.tileMargin;
-    options.tilesPerRow = tilesPerRow;
-
-    //Set min level to avoid loading sublevels since collection is a
-    //different kind of abstraction
-
-    while( levelSize  <  ( options.tileSize ) * longSide ){
-        //$.console.log( '%s levelSize %s minLevel %s', options.tileSize * longSide, levelSize, minLevel );
-        levelSize = levelSize * 2.0;
-        minLevel++;
-    }
-    options.minLevel = minLevel;
-
-    //for( var name in options ){
-    //    $.console.log( 'Collection %s %s', name, options[ name ] );
-    //}
-
-    $.TileSource.apply( this, [ options ] );
-
-};
-
-$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TileSourceCollection.prototype */{
-
-    /**
-     * @function
-     * @param {Number} level
-     * @param {Number} x
-     * @param {Number} y
-     */
-    getTileBounds: function( level, x, y ) {
-        var dimensionsScaled = this.dimensions.times( this.getLevelScale( level ) ),
-            px = this.tileSize * x - this.tileOverlap,
-            py = this.tileSize * y - this.tileOverlap,
-            sx = this.tileSize + 1 * this.tileOverlap,
-            sy = this.tileSize + 1 * this.tileOverlap,
-            scale = 1.0 / dimensionsScaled.x;
-
-        sx = Math.min( sx, dimensionsScaled.x - px );
-        sy = Math.min( sy, dimensionsScaled.y - py );
-
-        return new $.Rect( px * scale, py * scale, sx * scale, sy * scale );
-    },
-
-    /**
-     *
-     * @function
-     */
-    configure: function( data, url ){
-        return;
-    },
-
-
-    /**
-     * @function
-     * @param {Number} level
-     * @param {Number} x
-     * @param {Number} y
-     */
-    getTileUrl: function( level, x, y ) {
-        //$.console.log([  level, '/', x, '_', y ].join( '' ));
-        return null;
-    }
-
-
-
-});
-
 
 }( OpenSeadragon ));

src/viewer.js

@@ -405,13 +405,13 @@ $.Viewer = function( options ) {
         THIS[ _this.hash ].forceRedraw = true;
     });
 
-    this.world.addHandler('home-bounds-changed', function(event) {
+    this.world.addHandler('home-bounds-change', function(event) {
         if (_this.viewport) {
             _this.viewport.setHomeBounds(_this.world.getHomeBounds(), _this.world.getContentFactor());
         }
     });
 
-    this.world.addHandler('item-index-changed', function(event) {
+    this.world.addHandler('item-index-change', function(event) {
         // For backwards compatibility, we maintain the source property
         _this.source = _this.world.getItemAt(0).source;
     });
@@ -1300,7 +1300,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             });
 
             if (_this.collectionMode) {
-                _this.world.layout({
+                _this.world.arrange({
                     rows: _this.collectionRows,
                     layout: _this.collectionLayout,
                     tileSize: _this.collectionTileSize,

src/world.js

@@ -59,6 +59,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
      * @param {OpenSeadragon.TiledImage} item - The item to add.
      * @param {Number} [options.index] - Index for the item. If not specified, goes at the top.
      * @fires OpenSeadragon.World.event:add-item
+     * @fires OpenSeadragon.World.event:home-bounds-change
      */
     addItem: function( item, options ) {
         var _this = this;
@@ -78,7 +79,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
         this._needsUpdate = true;
 
         // TODO: remove handler when removing item from world
-        item.addHandler('bounds-changed', function(event) {
+        item.addHandler('bounds-change', function(event) {
             _this._figureSizes();
         });
 
@@ -127,7 +128,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
      * Change the index of a item so that it appears over or under others.
      * @param {OpenSeadragon.TiledImage} item - The item to move.
      * @param {Number} index - The new index.
-     * @fires OpenSeadragon.World.event:item-index-changed
+     * @fires OpenSeadragon.World.event:item-index-change
      */
     setItemIndex: function( item, index ) {
         $.console.assert(item, "[World.setItemIndex] item is required");
@@ -149,7 +150,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
 
         /**
          * Raised when the order of the indexes has been changed.
-         * @event item-index-changed
+         * @event item-index-change
          * @memberOf OpenSeadragon.World
          * @type {object}
          * @property {OpenSeadragon.World} eventSource - A reference to the World which raised the event.
@@ -159,7 +160,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
          * @property {Number} newIndex - The new index of the item
          * @property {?Object} userData - Arbitrary subscriber-defined object.
          */
-        this.raiseEvent( 'item-index-changed', {
+        this.raiseEvent( 'item-index-change', {
             item: item,
             previousIndex: oldIndex,
             newIndex: index
@@ -170,6 +171,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
      * Remove an item.
      * @param {OpenSeadragon.TiledImage} item - The item to remove.
      * @fires OpenSeadragon.World.event:remove-item
+     * @fires OpenSeadragon.World.event:home-bounds-change
      */
     removeItem: function( item ) {
         $.console.assert(item, "[World.removeItem] item is required");
@@ -188,6 +190,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
     /**
      * Remove all items.
      * @fires OpenSeadragon.World.event:remove-item
+     * @fires OpenSeadragon.World.event:home-bounds-change
      */
     removeAll: function() {
         var removedItems = this._items;
@@ -249,11 +252,21 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
         return this._contentFactor;
     },
 
-    layout: function(config) {
+    /**
-        var layout = config.layout || $.DEFAULT_SETTINGS.collectionLayout;
+     * Arranges all of the TiledImages with the specified settings.
-        var rows = config.rows || $.DEFAULT_SETTINGS.collectionRows;
+     * @param {Object} options - Specifies how to arrange.
-        var tileSize = config.tileSize || $.DEFAULT_SETTINGS.collectionTileSize;
+     * @param {String} [options.layout] - See collectionLayout in {@link OpenSeadragon.Options}.
-        var tileMargin = config.tileMargin || $.DEFAULT_SETTINGS.collectionTileMargin;
+     * @param {Number} [options.rows] - See collectionRows in {@link OpenSeadragon.Options}.
+     * @param {Number} [options.tileSize] - See collectionTileSize in {@link OpenSeadragon.Options}.
+     * @param {Number} [options.tileMargin] - See collectionTileMargin in {@link OpenSeadragon.Options}.
+     * @fires OpenSeadragon.World.event:home-bounds-change
+     */
+    arrange: function(options) {
+        options = options || {};
+        var layout = options.layout || $.DEFAULT_SETTINGS.collectionLayout;
+        var rows = options.rows || $.DEFAULT_SETTINGS.collectionRows;
+        var tileSize = options.tileSize || $.DEFAULT_SETTINGS.collectionTileSize;
+        var tileMargin = options.tileMargin || $.DEFAULT_SETTINGS.collectionTileMargin;
         var increment = tileSize + tileMargin;
         var wrap = Math.ceil(this._items.length / rows);
         var x = 0;
@@ -271,7 +284,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
             }
 
             item = this._items[i];
-            box = item.getWorldBounds();
+            box = item.getBounds();
             if (box.width > box.height) {
                 width = tileSize;
             } else {
@@ -301,7 +314,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
             this._homeBounds = new $.Rect(0, 0, 1, 1);
             this._contentSize = new $.Point(1, 1);
         } else {
-            var bounds = this._items[0].getWorldBounds();
+            var bounds = this._items[0].getBounds();
             this._contentFactor = this._items[0].getContentSize().x / bounds.width;
             var left = bounds.x;
             var top = bounds.y;
@@ -309,7 +322,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
             var bottom = bounds.y + bounds.height;
             var box;
             for ( var i = 1; i < this._items.length; i++ ) {
-                box = this._items[i].getWorldBounds();
+                box = this._items[i].getBounds();
                 this._contentFactor = Math.max(this._contentFactor, this._items[i].getContentSize().x / box.width);
                 left = Math.min( left, box.x );
                 top = Math.min( top, box.y );
@@ -325,13 +338,13 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
         if (!this._homeBounds.equals(oldHomeBounds)) {
             /**
              * Raised when the home bounds change.
-             * @event home-bounds-changed
+             * @event home-bounds-change
              * @memberOf OpenSeadragon.World
              * @type {object}
              * @property {OpenSeadragon.World} eventSource - A reference to the World which raised the event.
              * @property {?Object} userData - Arbitrary subscriber-defined object.
              */
-            this.raiseEvent('home-bounds-changed');
+            this.raiseEvent('home-bounds-change');
         }
     },
 

test/multi-image.js

@@ -63,9 +63,9 @@
                     equal( viewer.world.getItemAt( 2 ), item2,
                         "The item at index 2 should be the second added item." );
 
-                    viewer.world.addHandler( "item-index-changed",
+                    viewer.world.addHandler( "item-index-change",
                         function itemIndexChangedHandler( event ) {
-                            viewer.world.removeHandler( "item-index-changed",
+                            viewer.world.removeHandler( "item-index-change",
                                 itemIndexChangedHandler );
                             equal( event.item, item2,
                                 "The item which changed index should be item2" );