From d346d165f8409f5a0caa1c024f74dc749abd6546 Mon Sep 17 00:00:00 2001 From: Ian Gilman Date: Tue, 4 Nov 2014 11:53:39 -0800 Subject: [PATCH] Updated documentation --- changelog.txt | 3 +- src/drawer.js | 129 ++++++++++--------------------------------- src/navigator.js | 5 +- src/openseadragon.js | 2 +- src/tilecache.js | 50 ++++++++++------- src/tiledimage.js | 48 ++++++++++------ src/viewer.js | 44 ++++----------- src/viewport.js | 23 ++++++-- src/world.js | 32 +++-------- 9 files changed, 131 insertions(+), 205 deletions(-) diff --git a/changelog.txt b/changelog.txt index f4f2c205..ddb10df9 100644 --- a/changelog.txt +++ b/changelog.txt @@ -5,6 +5,7 @@ OPENSEADRAGON CHANGELOG * True multi-image mode (#450) * BREAKING CHANGE: Navigator no longer sends an open event when its viewer opens + * BREAKING CHANGE: Viewer.drawers and Viewer.drawersContainer no longer exist * DEPRECATION: use Viewer.addTiledImage instead of Viewer.addLayer * addTiledImage supports positioning config properties * DEPRECATION: use World.getItemAt instead of Viewer.getLayerAtLevel @@ -17,7 +18,6 @@ OPENSEADRAGON CHANGELOG * DEPRECATION: use World.resetItems instead of Drawer.reset * DEPRECATION: use Drawer.clear and World.update instead of Drawer.update * DEPRECATION: the layersAspectRatioEpsilon option is no longer necessary - * DEPRECATION: Viewer.drawers and Viewer.drawersContainer no longer exist * 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 remove-layer event is now World's remove-item event @@ -31,6 +31,7 @@ OPENSEADRAGON CHANGELOG * Rect and Point now have clone functions * New Viewport method for managing homeBounds as well as constraints: setHomeBounds * Viewport.open supports positioning config properties +* Margins option to push the home region in from the edges of the Viewer (#505) 1.2.0: (in progress) diff --git a/src/drawer.js b/src/drawer.js index fd1cd730..969c0e06 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -36,15 +36,17 @@ /** * @class Drawer - * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}. - * * @memberof OpenSeadragon - * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source. - * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. - * @param {Element} element - Parent element. + * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}. + * @param {Object} options - Options for this Drawer. + * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer. + * @param {OpenSeadragon.Viewport} options.viewport - Reference to Viewer viewport. + * @param {Element} options.element - Parent element. + * @param {Number} [options.opacity=1] - See opacity in {@link OpenSeadragon.Options} for details. + * @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details. */ $.Drawer = function( options ) { - var self = this; + var _this = this; $.console.assert( options.viewer, "[Drawer] options.viewer is required" ); @@ -117,7 +119,7 @@ $.Drawer = function( options ) { // We need a callback to give image manipulation a chance to happen this._drawingHandler = function(args) { - if (self.viewer) { + if (_this.viewer) { /** * This event is fired just before the tile is drawn giving the application a chance to alter the image. * @@ -130,80 +132,34 @@ $.Drawer = function( options ) { * @property {OpenSeadragon.Tile} tile * @property {?Object} userData - 'context', 'tile' and 'rendered'. */ - self.viewer.raiseEvent('tile-drawing', args); + _this.viewer.raiseEvent('tile-drawing', args); } }; }; $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ - - /** - * Adds an html element as an overlay to the current viewport. Useful for - * highlighting words or areas of interest on an image or other zoomable - * interface. - * @method - * @param {Element|String|Object} element - A reference to an element or an id for - * 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. - * @fires OpenSeadragon.Viewer.event:add-overlay - * @deprecated - use {@link OpenSeadragon.Viewer#addOverlay} instead. - */ + // deprecated addOverlay: function( element, location, placement, onDraw ) { $.console.error("drawer.addOverlay is deprecated. Use viewer.addOverlay instead."); this.viewer.addOverlay( element, location, placement, onDraw ); return this; }, - /** - * Updates the overlay represented by the reference to the element or - * element id moving it to the new location, relative to the new placement. - * @method - * @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. - * @return {OpenSeadragon.Drawer} Chainable. - * @fires OpenSeadragon.Viewer.event:update-overlay - * @deprecated - use {@link OpenSeadragon.Viewer#updateOverlay} instead. - */ + // deprecated updateOverlay: function( element, location, placement ) { $.console.error("drawer.updateOverlay is deprecated. Use viewer.updateOverlay instead."); this.viewer.updateOverlay( element, location, placement ); return this; }, - /** - * Removes and overlay identified by the reference element or element id - * and schedules and update. - * @method - * @param {Element|String} element - A reference to the element or an - * element id which represent the ovelay content to be removed. - * @return {OpenSeadragon.Drawer} Chainable. - * @fires OpenSeadragon.Viewer.event:remove-overlay - * @deprecated - use {@link OpenSeadragon.Viewer#removeOverlay} instead. - */ + // deprecated removeOverlay: function( element ) { $.console.error("drawer.removeOverlay is deprecated. Use viewer.removeOverlay instead."); this.viewer.removeOverlay( element ); return this; }, - /** - * Removes all currently configured Overlays from this Drawer and schedules - * and update. - * @method - * @return {OpenSeadragon.Drawer} Chainable. - * @fires OpenSeadragon.Viewer.event:clear-overlay - * @deprecated - use {@link OpenSeadragon.Viewer#clearOverlays} instead. - */ + // deprecated clearOverlays: function() { $.console.error("drawer.clearOverlays is deprecated. Use viewer.clearOverlays instead."); this.viewer.clearOverlays(); @@ -212,7 +168,6 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ /** * Set the opacity of the drawer. - * @method * @param {Number} opacity * @return {OpenSeadragon.Drawer} Chainable. */ @@ -224,60 +179,37 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ /** * Get the opacity of the drawer. - * @method * @returns {Number} */ getOpacity: function() { return this.opacity; }, - /** - * Returns whether the Drawer is scheduled for an update at the - * soonest possible opportunity. - * @method - * @returns {Boolean} - Whether the Drawer is scheduled for an update at the - * soonest possible opportunity. - */ + // deprecated needsUpdate: function() { $.console.error( "[Drawer.needsUpdate] this function is deprecated." ); return false; }, - /** - * Returns the total number of tiles that have been loaded by this Drawer. - * @method - * @returns {Number} - The total number of tiles that have been loaded by - * this Drawer. - */ + // deprecated numTilesLoaded: function() { $.console.error( "[Drawer.numTilesLoaded] this function is deprecated." ); return 0; }, - /** - * Clears all tiles and triggers an update on the next call to - * Drawer.prototype.update(). - * @method - * @return {OpenSeadragon.Drawer} Chainable. - */ + // deprecated reset: function() { $.console.error( "[Drawer.reset] this function is deprecated." ); return this; }, - /** - * Forces the Drawer to update. - * @method - * @return {OpenSeadragon.Drawer} Chainable. - */ + // deprecated update: function() { $.console.error( "[Drawer.update] this function is deprecated." ); return this; }, /** - * Returns whether rotation is supported or not. - * @method * @return {Boolean} True if rotation is supported. */ canRotate: function() { @@ -286,8 +218,6 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ /** * Destroy the drawer (unload current loaded tiles) - * @method - * @return null */ destroy: function() { //force unloading of current canvas (1x1 will be gc later, trick not necessarily needed) @@ -295,6 +225,9 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ this.canvas.height = 1; }, + /** + * Clears the Drawer so it's ready to draw another frame. + */ clear: function() { this.canvas.innerHTML = ""; if ( this.useCanvas ) { @@ -308,6 +241,10 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } }, + /** + * Draws the given tile. + * @param {OpenSeadragon.Tile} tile - The tile to draw. + */ drawTile: function( tile ) { if ( this.useCanvas ) { // TODO do this in a more performant way @@ -324,9 +261,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } }, - /** - * @private - */ + // private drawDebugInfo: function( tile, count, i ){ if ( this.useCanvas ) { this.context.save(); @@ -399,9 +334,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } }, - /** - * @private - */ + // private debugRect: function(rect) { if ( this.useCanvas ) { this.context.save(); @@ -420,9 +353,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } }, - /** - * @private - */ + // private _offsetForRotation: function( tile, degrees ){ var cx = this.canvas.width / 2, cy = this.canvas.height / 2, @@ -437,9 +368,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ tile.position.y = py; }, - /** - * @private - */ + // private _restoreRotationChanges: function( tile ){ var cx = this.canvas.width / 2, cy = this.canvas.height / 2, diff --git a/src/navigator.js b/src/navigator.js index 5f8eb89d..2cadc03f 100644 --- a/src/navigator.js +++ b/src/navigator.js @@ -344,10 +344,7 @@ $.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, /* }, - /** - * Overrides Viewer.addTiledImage - * @private - */ + // overrides Viewer.addTiledImage addTiledImage: function(options) { var original = options.originalTiledImage; delete options.original; diff --git a/src/openseadragon.js b/src/openseadragon.js index 91a7231d..14221847 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -2251,7 +2251,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ info: nullfunction, warn: nullfunction, error: nullfunction, - assert: nullfunction + assert: nullfunction }; diff --git a/src/tilecache.js b/src/tilecache.js index 7228eff6..71a8f25a 100644 --- a/src/tilecache.js +++ b/src/tilecache.js @@ -34,17 +34,22 @@ (function( $ ){ -var TileRecord = function( params ) { - $.console.assert( params, "[TileCache.cacheTile] params is required" ); - $.console.assert( params.tile, "[TileCache.cacheTile] params.tile is required" ); - $.console.assert( params.tiledImage, "[TileCache.cacheTile] params.tiledImage is required" ); - this.tile = params.tile; - this.tiledImage = params.tiledImage; +// private +var TileRecord = function( options ) { + $.console.assert( options, "[TileCache.cacheTile] options is required" ); + $.console.assert( options.tile, "[TileCache.cacheTile] options.tile is required" ); + $.console.assert( options.tiledImage, "[TileCache.cacheTile] options.tiledImage is required" ); + this.tile = options.tile; + this.tiledImage = options.tiledImage; }; /** * @class TileCache - * @classdesc + * @memberof OpenSeadragon + * @classdesc Stores all the tiles displayed in a {@link OpenSeadragon.Viewer}. + * @param {Object} options - Configuration for this TileCache. + * @param {Number} [options.maxImageCacheCount] - See maxImageCacheCount in + * {@link OpenSeadragon.Options} for details. */ $.TileCache = function( options ) { options = options || {}; @@ -55,21 +60,29 @@ $.TileCache = function( options ) { $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{ /** - * Returns the total number of tiles that have been loaded by this TileCache. - * @method - * @returns {Number} - The total number of tiles that have been loaded by - * this TileCache. + * @returns {Number} The total number of tiles that have been loaded by + * this TileCache. */ numTilesLoaded: function() { return this._tilesLoaded.length; }, - cacheTile: function( params ) { - $.console.assert( params, "[TileCache.cacheTile] params is required" ); - $.console.assert( params.tile, "[TileCache.cacheTile] params.tile is required" ); - $.console.assert( params.tiledImage, "[TileCache.cacheTile] params.tiledImage is required" ); + /** + * Caches the specified tile, removing an old tile if necessary to stay under the + * maxImageCacheCount specified on construction. + * @param {Object} options - Tile info. + * @param {OpenSeadragon.Tile} options.tile - The tile to cache. + * @param {OpenSeadragon.TiledImage} options.tiledImage - The TiledImage that owns that tile. + * @param {Number} [options.cutoff=0] - If adding this tile goes over the cache max count, this + * function will release an old tile. The cutoff option specifies a tile level at or below which + * tiles will not be released. + */ + cacheTile: function( options ) { + $.console.assert( options, "[TileCache.cacheTile] options is required" ); + $.console.assert( options.tile, "[TileCache.cacheTile] options.tile is required" ); + $.console.assert( options.tiledImage, "[TileCache.cacheTile] options.tiledImage is required" ); - var cutoff = params.cutoff || 0; + var cutoff = options.cutoff || 0; var insertionIndex = this._tilesLoaded.length; if ( this._tilesLoaded.length >= this._maxImageCacheCount ) { @@ -108,14 +121,13 @@ $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{ } this._tilesLoaded[ insertionIndex ] = new TileRecord({ - tile: params.tile, - tiledImage: params.tiledImage + tile: options.tile, + tiledImage: options.tiledImage }); }, /** * Clears all tiles associated with the specified tiledImage. - * @method */ clearTilesFor: function( tiledImage ) { var tileRecord; diff --git a/src/tiledimage.js b/src/tiledimage.js index e2afbed5..dea44ef0 100644 --- a/src/tiledimage.js +++ b/src/tiledimage.js @@ -36,16 +36,35 @@ /** * @class TiledImage + * @memberof OpenSeadragon * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}. * A new instance is created for each TileSource opened. - * - * @memberof OpenSeadragon + * @param {Object} options - Configuration for this TiledImage. + * @param {OpenSeadragon.TileSource} options.source - The TileSource that defines this TiledImage. + * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this TiledImage. + * @param {OpenSeadragon.TileCache} options.tileCache - The TileCache for this TiledImage to use. + * @param {OpenSeadragon.Drawer} options.drawer - The Drawer for this TiledImage to draw onto. + * @param {OpenSeadragon.ImageLoader} options.imageLoader - The ImageLoader for this TiledImage to use. + * @param {Number} [options.x=0] - Left position, in world coordinates. + * @param {Number} [options.y=0] - Top position, in world coordinates. + * @param {Number} [options.width=1] - Width, in world coordinates. + * @param {Number} [options.height] - Height, in world coordinates. + * @param {Number} [options.minZoomImageRatio] - See {@link OpenSeadragon.Options}. + * @param {Boolean} [options.wrapHorizontal] - See {@link OpenSeadragon.Options}. + * @param {Boolean} [options.wrapVertical] - See {@link OpenSeadragon.Options}. + * @param {Boolean} [options.immediateRender] - See {@link OpenSeadragon.Options}. + * @param {Number} [options.blendTime] - See {@link OpenSeadragon.Options}. + * @param {Boolean} [options.alwaysBlend] - See {@link OpenSeadragon.Options}. + * @param {Number} [options.minPixelRatio] - See {@link OpenSeadragon.Options}. + * @param {Boolean} [options.debugMode] - See {@link OpenSeadragon.Options}. + * @param {String|Boolean} [options.crossOriginPolicy] - See {@link OpenSeadragon.Options}. */ $.TiledImage = function( options ) { $.console.assert( options.tileCache, "[TiledImage] options.tileCache is required" ); $.console.assert( options.drawer, "[TiledImage] options.drawer is required" ); $.console.assert( options.viewer, "[TiledImage] options.viewer is required" ); $.console.assert( options.imageLoader, "[TiledImage] options.imageLoader is required" ); + $.console.assert( options.source, "[TiledImage] options.source is required" ); this._tileCache = options.tileCache; delete options.tileCache; @@ -109,11 +128,8 @@ $.TiledImage = function( options ) { $.TiledImage.prototype = /** @lends OpenSeadragon.TiledImage.prototype */{ /** - * Returns whether the TiledImage is scheduled for an update at the - * soonest possible opportunity. - * @method - * @returns {Boolean} - Whether the TiledImage is scheduled for an update at the - * soonest possible opportunity. + * @returns {Boolean} Whether the TiledImage is scheduled for an update at the + * soonest possible opportunity. */ needsUpdate: function() { return this.updateAgain; @@ -121,42 +137,40 @@ $.TiledImage.prototype = /** @lends OpenSeadragon.TiledImage.prototype */{ /** * Clears all tiles and triggers an update on the next call to - * TiledImage.prototype.update(). - * @method - * @return {OpenSeadragon.TiledImage} Chainable. + * {@link OpenSeadragon.TiledImage#update}. */ reset: function() { this._tileCache.clearTilesFor(this); this.lastResetTime = $.now(); this.updateAgain = true; - return this; }, /** * Forces the TiledImage to update. - * @method - * @return {OpenSeadragon.TiledImage} Chainable. */ update: function() { this.midUpdate = true; updateViewport( this ); this.midUpdate = false; - return this; }, /** - * Destroy the TiledImage (unload current loaded tiles) - * @method - * @return null + * Destroy the TiledImage (unload current loaded tiles). */ destroy: function() { this.reset(); }, + /** + * @returns {OpenSeadragon.Rect} This TiledImage's bounds in world coordinates. + */ getWorldBounds: function() { return new $.Rect( this._worldX, this._worldY, this._worldWidth, this._worldHeight ); }, + /** + * @returns {OpenSeadragon.Point} This TiledImage's content size, in original pixels. + */ getContentSize: function() { return new $.Point(this.source.dimensions.x, this.source.dimensions.y); } diff --git a/src/viewer.js b/src/viewer.js index c0a6d900..727cbf9d 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -539,17 +539,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, return !!this.world.getItemCount(); }, - /** - * @private - */ + // deprecated openDzi: function ( dzi ) { $.console.error( "[Viewer.openDzi] this function is deprecated; use Viewer.open() instead." ); return this.open( dzi ); }, - /** - * @private - */ + // deprecated openTileSource: function ( tileSource ) { $.console.error( "[Viewer.openTileSource] this function is deprecated; use Viewer.open() instead." ); return this.open( tileSource ); @@ -1329,24 +1325,21 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } ); }, - /** - * @function - * @private - */ + // deprecated addLayer: function( options ) { - var self = this; + var _this = this; $.console.error( "[Viewer.addLayer] this function is deprecated; use Viewer.addTiledImage() instead." ); var optionsClone = $.extend({}, options, { success: function(event) { - self.raiseEvent("add-layer", { + _this.raiseEvent("add-layer", { options: options, drawer: event.item }); }, error: function(event) { - self.raiseEvent("add-layer-failed", event); + _this.raiseEvent("add-layer-failed", event); } }); @@ -1354,46 +1347,31 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, return this; }, - /** - * @function - * @private - */ + // deprecated getLayerAtLevel: function( level ) { $.console.error( "[Viewer.getLayerAtLevel] this function is deprecated; use World.getItemAt() instead." ); return this.world.getItemAt(level); }, - /** - * @function - * @private - */ + // deprecated getLevelOfLayer: function( drawer ) { $.console.error( "[Viewer.getLevelOfLayer] this function is deprecated; use World.getIndexOfItem() instead." ); return this.world.getIndexOfItem(drawer); }, - /** - * @function - * @private - */ + // deprecated getLayersCount: function() { $.console.error( "[Viewer.getLayersCount] this function is deprecated; use World.getItemCount() instead." ); return this.world.getItemCount(); }, - /** - * @function - * @private - */ + // deprecated setLayerLevel: function( drawer, level ) { $.console.error( "[Viewer.setLayerLevel] this function is deprecated; use World.setItemIndex() instead." ); return this.world.setItemIndex(drawer, level); }, - /** - * @function - * @private - */ + // deprecated removeLayer: function( drawer ) { $.console.error( "[Viewer.removeLayer] this function is deprecated; use World.removeItem() instead." ); return this.world.removeItem(drawer); diff --git a/src/viewport.js b/src/viewport.js index fab50455..2ecb4a8d 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -37,10 +37,23 @@ /** * @class Viewport - * @classdesc Handles coordinate-related functionality (zoom, pan, rotation, etc.) for an {@link OpenSeadragon.Viewer}. - * A new instance is created for each TileSource opened (see {@link OpenSeadragon.Viewer#viewport}). - * * @memberof OpenSeadragon + * @classdesc Handles coordinate-related functionality (zoom, pan, rotation, etc.) + * for an {@link OpenSeadragon.Viewer}. + * @param {Object} options - Options for this Viewport. + * @param {Object} [margins] - See viewportMargins in {@link OpenSeadragon.Options}. + * @param {Number} [springStiffness] - See springStiffness in {@link OpenSeadragon.Options}. + * @param {Number} [animationTime] - See animationTime in {@link OpenSeadragon.Options}. + * @param {Number} [minZoomImageRatio] - See minZoomImageRatio in {@link OpenSeadragon.Options}. + * @param {Number} [maxZoomPixelRatio] - See maxZoomPixelRatio in {@link OpenSeadragon.Options}. + * @param {Number} [visibilityRatio] - See visibilityRatio in {@link OpenSeadragon.Options}. + * @param {Boolean} [wrapHorizontal] - See wrapHorizontal in {@link OpenSeadragon.Options}. + * @param {Boolean} [wrapVertical] - See wrapVertical in {@link OpenSeadragon.Options}. + * @param {Number} [defaultZoomLevel] - See defaultZoomLevel in {@link OpenSeadragon.Options}. + * @param {Number} [minZoomLevel] - See minZoomLevel in {@link OpenSeadragon.Options}. + * @param {Number} [maxZoomLevel] - See maxZoomLevel in {@link OpenSeadragon.Options}. + * @param {Number} [degrees] - See degrees in {@link OpenSeadragon.Options}. + * @param {Boolean} [homeFillsViewer] - See homeFillsViewer in {@link OpenSeadragon.Options}. */ $.Viewport = function( options ) { @@ -933,9 +946,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ return this._pixelFromPoint(point, this.getBounds( current )); }, - /** - * @private - */ + // private _pixelFromPoint: function( point, bounds ) { return point.minus( bounds.getTopLeft() diff --git a/src/world.js b/src/world.js index 3b39861f..3e4d3924 100644 --- a/src/world.js +++ b/src/world.js @@ -35,14 +35,12 @@ (function( $ ){ /** - * Keeps track of all of the tiled images in the scene. - * * @class World - * @classdesc - * * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource - * @param {OpenSeadragon.Options} options - World options. + * @classdesc Keeps track of all of the tiled images in the scene. + * @param {Object} options - World options. + * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this World. **/ $.World = function( options ) { $.console.assert( options.viewer, "[World] options.viewer is required" ); @@ -59,7 +57,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W /** * Add the specified item. * @param {OpenSeadragon.TiledImage} item - The item to add. - * @param {Number} options.index - index for the item (optional). + * @param {Number} [options.index] - Index for the item. If not specified, goes at the top. * @fires OpenSeadragon.World.event:add-item */ addItem: function( item, options ) { @@ -83,7 +81,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W * @memberOf OpenSeadragon.World * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the World which raised the event. - * @property {OpenSeadragon.Drawer} item - The item that has been added + * @property {OpenSeadragon.TiledImage} item - The item that has been added. * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'add-item', { @@ -112,7 +110,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W }, /** - * Get the number of items used. * @returns {Number} The number of items used. */ getItemCount: function() { @@ -164,7 +161,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W /** * Remove an item. - * @function * @param {OpenSeadragon.TiledImage} item - The item to remove. * @fires OpenSeadragon.World.event:remove-item */ @@ -184,7 +180,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W /** * Remove all items. - * @function * @fires OpenSeadragon.World.event:remove-item */ removeAll: function() { @@ -200,7 +195,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W /** * Clears all tiles and triggers updates for all items. - * @function */ resetItems: function() { for ( var i = 0; i < this._items.length; i++ ) { @@ -210,7 +204,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W /** * Updates (i.e. draws) all items. - * @function */ update: function() { for ( var i = 0; i < this._items.length; i++ ) { @@ -221,7 +214,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W }, /** - * @function * @returns {Boolean} true if any items need updating. */ needsUpdate: function() { @@ -234,8 +226,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W }, /** - * @function - * @returns {OpenSeadragon.Rect} the smallest rectangle that encloses all items, in world coordinates. + * @returns {OpenSeadragon.Rect} The smallest rectangle that encloses all items, in world coordinates. */ getHomeBounds: function() { return this._homeBounds.clone(); @@ -245,17 +236,13 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W * To facilitate zoom constraints, we keep track of the pixel density of the * densest item in the World (i.e. the item whose content size to world size * ratio is the highest) and save it as this "content factor". - * @function * @returns {Number} the number of content units per world unit. */ getContentFactor: function() { return this._contentFactor; }, - /** - * @function - * @private - */ + // private _figureSizes: function() { if ( !this._items.length ) { this._homeBounds = new $.Rect(0, 0, 1, 1); @@ -284,10 +271,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W this._homeBounds.height * this._contentFactor); }, - /** - * @function - * @private - */ + // private _raiseRemoveItem: function(item) { /** * Raised when a item is removed.