From 70b91d57ec8f6d7557ea790a1b2f17792a568d80 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Fri, 15 Nov 2013 22:19:53 -0800 Subject: [PATCH 01/18] Updated doclets for jsdoc3 Updated so jsdoc3 parser picks everything up. Added event docs. Lots of documentation content needed... --- src/button.js | 87 +++++++++++++- src/buttongroup.js | 7 +- src/control.js | 5 +- src/controldock.js | 5 +- src/displayrectangle.js | 3 +- src/drawer.js | 78 ++++++++++++- src/dzitilesource.js | 9 +- src/eventsource.js | 22 +++- src/iiif1_1tilesource.js | 11 +- src/iiiftilesource.js | 87 +++++++------- src/legacytilesource.js | 11 +- src/mousetracker.js | 29 ++--- src/navigator.js | 7 +- src/openseadragon.js | 77 +++++++------ src/osmtilesource.js | 8 +- src/overlay.js | 7 +- src/point.js | 5 +- src/profiler.js | 5 +- src/rectangle.js | 5 +- src/spring.js | 5 +- src/tile.js | 5 +- src/tilesource.js | 35 +++++- src/tilesourcecollection.js | 8 +- src/tmstilesource.js | 8 +- src/viewer.js | 219 ++++++++++++++++++++++++++++++++++-- src/viewport.js | 59 +++++++++- 26 files changed, 627 insertions(+), 180 deletions(-) diff --git a/src/button.js b/src/button.js index 8a09cdb0..1cc819ef 100644 --- a/src/button.js +++ b/src/button.js @@ -36,6 +36,8 @@ /** * An enumeration of button states including, REST, GROUP, HOVER, and DOWN + * @member ButtonState + * @memberof OpenSeadragon * @static */ $.ButtonState = { @@ -49,7 +51,8 @@ $.ButtonState = { * Manages events, hover states for individual buttons, tool-tips, as well * as fading the bottons out when the user has not interacted with them * for a specified period. - * @class + * @class Button + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Object} options * @param {String} options.tooltip Provides context help for the button we the @@ -178,6 +181,14 @@ $.Button = function( options ) { enterHandler: function( event ) { if ( event.insideElementPressed ) { inTo( _this, $.ButtonState.DOWN ); + /** + * @event enter + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "enter", { originalEvent: event.originalEvent } ); } else if ( !event.buttonDownAny ) { inTo( _this, $.ButtonState.HOVER ); @@ -186,29 +197,69 @@ $.Button = function( options ) { focusHandler: function ( event ) { this.enterHandler( event ); + /** + * @event focus + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "focus", { originalEvent: event.originalEvent } ); }, exitHandler: function( event ) { outTo( _this, $.ButtonState.GROUP ); if ( event.insideElementPressed ) { + /** + * @event exit + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "exit", { originalEvent: event.originalEvent } ); } }, blurHandler: function ( event ) { this.exitHandler( event ); + /** + * @event blur + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "blur", { originalEvent: event.originalEvent } ); }, pressHandler: function ( event ) { inTo( _this, $.ButtonState.DOWN ); + /** + * @event press + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "press", { originalEvent: event.originalEvent } ); }, releaseHandler: function( event ) { if ( event.insideElementPressed && event.insideElementReleased ) { outTo( _this, $.ButtonState.HOVER ); + /** + * @event release + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); } else if ( event.insideElementPressed ) { outTo( _this, $.ButtonState.GROUP ); @@ -219,6 +270,14 @@ $.Button = function( options ) { clickHandler: function( event ) { if ( event.quick ) { + /** + * @event click + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent("click", { originalEvent: event.originalEvent }); } }, @@ -226,7 +285,23 @@ $.Button = function( options ) { keyHandler: function( event ){ //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode); if( 13 === event.keyCode ){ + /*** + * @event click + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "click", { originalEvent: event.originalEvent } ); + /*** + * @event release + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); return false; } @@ -238,13 +313,12 @@ $.Button = function( options ) { outTo( this, $.ButtonState.REST ); }; -$.extend( $.Button.prototype, $.EventSource.prototype, { +$.extend( $.Button.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.Button.prototype */{ /** * TODO: Determine what this function is intended to do and if it's actually * useful as an API point. * @function - * @name OpenSeadragon.Button.prototype.notifyGroupEnter */ notifyGroupEnter: function() { inTo( this, $.ButtonState.GROUP ); @@ -254,18 +328,23 @@ $.extend( $.Button.prototype, $.EventSource.prototype, { * TODO: Determine what this function is intended to do and if it's actually * useful as an API point. * @function - * @name OpenSeadragon.Button.prototype.notifyGroupExit */ notifyGroupExit: function() { outTo( this, $.ButtonState.REST ); }, + /** + * @function + */ disable: function(){ this.notifyGroupExit(); this.element.disabled = true; $.setElementOpacity( this.element, 0.2, true ); }, + /** + * @function + */ enable: function(){ this.element.disabled = false; $.setElementOpacity( this.element, 1.0, true ); diff --git a/src/buttongroup.js b/src/buttongroup.js index e6b51091..9f1ea2b5 100644 --- a/src/buttongroup.js +++ b/src/buttongroup.js @@ -35,7 +35,8 @@ (function( $ ){ /** * Manages events on groups of buttons. - * @class + * @class ButtonGroup + * @memberof OpenSeadragon * @param {Object} options - a dictionary of settings applied against the entire * group of buttons * @param {Array} options.buttons Array of buttons @@ -110,13 +111,12 @@ $.ButtonGroup = function( options ) { }).setTracking( true ); }; -$.ButtonGroup.prototype = { +$.ButtonGroup.prototype = /** @lends OpenSeadragon.ButtonGroup.prototype */{ /** * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function - * @name OpenSeadragon.ButtonGroup.prototype.emulateEnter */ emulateEnter: function() { this.tracker.enterHandler( { eventSource: this.tracker } ); @@ -126,7 +126,6 @@ $.ButtonGroup.prototype = { * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function - * @name OpenSeadragon.ButtonGroup.prototype.emulateExit */ emulateExit: function() { this.tracker.exitHandler( { eventSource: this.tracker } ); diff --git a/src/control.js b/src/control.js index ed682f85..3f0565a7 100644 --- a/src/control.js +++ b/src/control.js @@ -52,7 +52,8 @@ $.ControlAnchor = { * A Control represents any interface element which is meant to allow the user * to interact with the zoomable interface. Any control can be anchored to any * element. - * @class + * @class Control + * @memberof OpenSeadragon * @param {Element} element - the control element to be anchored in the container. * @param {Object } options - All required and optional settings for configuring a control element. * @param {OpenSeadragon.ControlAnchor} [options.anchor=OpenSeadragon.ControlAnchor.NONE] - the position of the control @@ -110,7 +111,7 @@ $.Control = function ( element, options, container ) { } }; -$.Control.prototype = { +$.Control.prototype = /** @lends OpenSeadragon.Control.prototype */{ /** * Removes the control from the container. diff --git a/src/controldock.js b/src/controldock.js index 94d0c224..ed6e60a0 100644 --- a/src/controldock.js +++ b/src/controldock.js @@ -34,7 +34,8 @@ (function( $ ){ /** - * @class + * @class ControlDock + * @memberof OpenSeadragon */ $.ControlDock = function( options ){ var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'], @@ -85,7 +86,7 @@ this.container.appendChild( this.controls.bottomleft ); }; - $.ControlDock.prototype = { + $.ControlDock.prototype = /** @lends OpenSeadragon.ControlDock.prototype */{ /** * @function diff --git a/src/displayrectangle.js b/src/displayrectangle.js index 389e9bbd..0b20b3d6 100644 --- a/src/displayrectangle.js +++ b/src/displayrectangle.js @@ -38,7 +38,8 @@ * A display rectanlge is very similar to the OpenSeadragon.Rect but adds two * fields, 'minLevel' and 'maxLevel' which denote the supported zoom levels * for this rectangle. - * @class + * @class DisplayRect + * @memberof OpenSeadragon * @extends OpenSeadragon.Rect * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. diff --git a/src/drawer.js b/src/drawer.js index 5a049469..85ae741b 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -48,7 +48,8 @@ var DEVICE_SCREEN = $.getWindowSize(), /** - * @class + * @class Drawer + * @memberof OpenSeadragon * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source. * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. * @param {Element} element - Reference to Viewer 'canvas'. @@ -153,7 +154,7 @@ $.Drawer = function( options ) { //this.profiler = new $.Profiler(); }; -$.Drawer.prototype = { +$.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ /** * Adds an html element as an overlay to the current viewport. Useful for @@ -199,6 +200,16 @@ $.Drawer.prototype = { }) ); this.updateAgain = true; if( this.viewer ){ + /** + * @event add-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location + * @property {OpenSeadragon.OverlayPlacement} placement + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'add-overlay', { element: element, location: options.location, @@ -230,6 +241,16 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event update-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location + * @property {OpenSeadragon.OverlayPlacement} placement + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'update-overlay', { element: element, location: location, @@ -259,6 +280,14 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event remove-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'remove-overlay', { element: element }); @@ -278,6 +307,13 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event clear-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'clear-overlay', {} ); } return this; @@ -471,6 +507,13 @@ function updateViewport( drawer ) { drawer.updateAgain = false; if( drawer.viewer ){ + /** + * @event update-viewport + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-viewport', {} ); } @@ -645,6 +688,21 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi if( drawer.viewer ){ + /** + * @event update-level + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} havedrawn + * @property {Object} level + * @property {Object} opacity + * @property {Object} visibility + * @property {Object} topleft + * @property {Object} bottomright + * @property {Object} currenttime + * @property {Object} best + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-level', { havedrawn: haveDrawn, level: level, @@ -708,6 +766,14 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le drawTile = drawLevel; if( drawer.viewer ){ + /** + * @event update-tile + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} tile + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-tile', { tile: tile }); @@ -1222,6 +1288,14 @@ function drawTiles( drawer, lastDrawn ){ } if( drawer.viewer ){ + /** + * @event tile-drawn + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} tile + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'tile-drawn', { tile: tile }); diff --git a/src/dzitilesource.js b/src/dzitilesource.js index 1bdfa9cf..9a3b1d03 100644 --- a/src/dzitilesource.js +++ b/src/dzitilesource.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class DziTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -92,14 +93,13 @@ $.DziTileSource = function( width, height, tileSize, tileOverlap, tilesUrl, file }; -$.extend( $.DziTileSource.prototype, $.TileSource.prototype, { +$.extend( $.DziTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.DziTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.DziTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -118,7 +118,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.DziTileSource.prototype.configure * @param {Object|XMLDocument} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -147,7 +146,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.DziTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y @@ -159,7 +157,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.DziTileSource.prototype.tileExists * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/eventsource.js b/src/eventsource.js index 4349c197..16abb4b8 100644 --- a/src/eventsource.js +++ b/src/eventsource.js @@ -34,23 +34,33 @@ (function($){ +/** + * Event handler method signature used by all OpenSeadragon events. + * + * @callback EventHandler + * @memberof OpenSeadragon + * @param {Object} event - See individual events for event properties passed. + */ + + /** * For use by classes which want to support custom, non-browser events. * TODO: Add a method 'one' which automatically unbinds a listener after * the first triggered event that matches. - * @class + * @class EventSource + * @memberof OpenSeadragon */ $.EventSource = function() { this.events = {}; }; -$.EventSource.prototype = { +$.EventSource.prototype = /** @lends OpenSeadragon.EventSource.prototype */{ /** * Add an event handler for a given event. * @function * @param {String} eventName - Name of event to register. - * @param {Function} handler - Function to call when event is triggered. + * @param {OpenSeadragon.EventHandler} handler - Function to call when event is triggered. * @param {Object} [userData=null] - Arbitrary object to be passed unchanged to the handler. */ addHandler: function ( eventName, handler, userData ) { @@ -67,7 +77,7 @@ $.EventSource.prototype = { * Remove a specific event handler for a given event. * @function * @param {String} eventName - Name of event for which the handler is to be removed. - * @param {Function} handler - Function to be removed. + * @param {OpenSeadragon.EventHandler} handler - Function to be removed. */ removeHandler: function ( eventName, handler ) { var events = this.events[ eventName ], @@ -104,7 +114,7 @@ $.EventSource.prototype = { }, /** - * Retrive the list of all handlers registered for a given event. + * Get a function which iterates the list of all handlers registered for a given event, calling the handler for each. * @function * @param {String} eventName - Name of event to get handlers for. */ @@ -133,7 +143,7 @@ $.EventSource.prototype = { * Trigger an event, optionally passing additional information. * @function * @param {String} eventName - Name of event to register. - * @param {Function} handler - Function to call when event is triggered. + * @param {Object} eventArgs - Event-specific data. */ raiseEvent: function( eventName, eventArgs ) { //uncomment if you want to get a log of all events diff --git a/src/iiif1_1tilesource.js b/src/iiif1_1tilesource.js index 6e022d3b..2f90355c 100644 --- a/src/iiif1_1tilesource.js +++ b/src/iiif1_1tilesource.js @@ -36,10 +36,10 @@ /** * A client implementation of the International Image Interoperability - * Format: Image API 1.1 - Please read more about the specification - * at + * Format: Image API 1.1 * - * @class + * @class IIIF1_1TileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ */ @@ -69,12 +69,11 @@ $.IIIF1_1TileSource = function( options ){ $.TileSource.apply( this, [ options ] ); }; -$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { +$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIF1_1TileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -91,7 +90,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.configure * @param {Object} data - the raw configuration */ // IIIF 1.1 Info Looks like this (XML syntax is no more): @@ -114,7 +112,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { * Responsible for retreiving the url which will return an image for the * region specified by the given x, y, and level components. * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.getTileUrl * @param {Number} level - z index * @param {Number} x * @param {Number} y diff --git a/src/iiiftilesource.js b/src/iiiftilesource.js index 99a07798..3050d9e2 100644 --- a/src/iiiftilesource.js +++ b/src/iiiftilesource.js @@ -43,10 +43,10 @@ /** * A client implementation of the International Image Interoperability - * Format: Image API Draft 0.2 - Please read more about the specification - * at + * Format: Image API Draft 0.2 * - * @class + * @class IIIFTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ */ @@ -81,12 +81,11 @@ $.IIIFTileSource = function( options ){ $.TileSource.apply( this, [ options ] ); }; -$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { +$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIFTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.supports + * @method * @param {Object|Array} data * @param {String} optional - url */ @@ -109,10 +108,9 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { ); }, - /** + /** * - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.configure + * @method * @param {Object|XMLDocument} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -152,8 +150,7 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { /** * Responsible for retreiving the url which will return an image for the * region speified by the given x, y, and level components. - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.getTileUrl + * @method * @param {Number} level - z index * @param {Number} x * @param {Number} y @@ -215,28 +212,28 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { * @private * @inner * @function - * - - - 1E34750D-38DB-4825-A38A-B60A345E591C - 6000 - 4000 - - 1 - 2 - 4 - - 1024 - 1024 - - jpg - png - - - native - grey - - + * @example + * + * + * 1E34750D-38DB-4825-A38A-B60A345E591C + * 6000 + * 4000 + * + * 1 + * 2 + * 4 + * + * 1024 + * 1024 + * + * jpg + * png + * + * + * native + * grey + * + * */ function configureFromXml( tileSource, xmlDoc ){ @@ -306,18 +303,18 @@ function parseXML( node, configuration, property ){ * @private * @inner * @function - * - { - "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1", - "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C", - "width" : 6000, - "height" : 4000, - "scale_factors" : [ 1, 2, 4 ], - "tile_width" : 1024, - "tile_height" : 1024, - "formats" : [ "jpg", "png" ], - "quality" : [ "native", "grey" ] - } + * @example + * { + * "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1", + * "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C", + * "width" : 6000, + * "height" : 4000, + * "scale_factors" : [ 1, 2, 4 ], + * "tile_width" : 1024, + * "tile_height" : 1024, + * "formats" : [ "jpg", "png" ], + * "quality" : [ "native", "grey" ] + * } */ function configureFromObject( tileSource, configuration ){ //the image_host property is not part of the iiif standard but is included here to diff --git a/src/legacytilesource.js b/src/legacytilesource.js index 6bc9ef89..a1cb47f5 100644 --- a/src/legacytilesource.js +++ b/src/legacytilesource.js @@ -41,7 +41,8 @@ * and generating a set of 'service' images like one or more thumbnails, a medium * resolution image and a high resolution image in standard web formats like * png or jpg. - * @class + * @class LegacyTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Array} levels An array of file descriptions, each is an object with * a 'url', a 'width', and a 'height'. Overriding classes can expect more @@ -96,12 +97,11 @@ $.LegacyTileSource = function( levels ) { this.levels = options.levels; }; -$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { +$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.LegacyTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.LegacyTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -119,7 +119,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.LegacyTileSource.prototype.configure * @param {Object|XMLDocument} configuration - the raw configuration * @param {String} dataUrl - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -144,7 +143,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getLevelScale * @param {Number} level */ getLevelScale: function ( level ) { @@ -159,7 +157,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getNumTiles * @param {Number} level */ getNumTiles: function( level ) { @@ -173,7 +170,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getTileAtPoint * @param {Number} level * @param {OpenSeadragon.Point} point */ @@ -188,7 +184,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { * server technologies, and various specifications for building image * pyramids, this method is here to allow easy integration. * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/mousetracker.js b/src/mousetracker.js index c2a7d446..95012f85 100644 --- a/src/mousetracker.js +++ b/src/mousetracker.js @@ -49,7 +49,8 @@ * The MouseTracker allows other classes to set handlers for common mouse * events on a specific element like, 'enter', 'exit', 'press', 'release', * 'scroll', 'click', and 'drag'. - * @class + * @class MouseTracker + * @memberof OpenSeadragon * @param {Object} options * Allows configurable properties to be entirely specified by passing * an options object to the constructor. The constructor also supports @@ -67,27 +68,27 @@ * @param {Number} options.stopDelay * The number of milliseconds without mouse move before the mouse stop * event is fired. - * @param {Function} options.enterHandler + * @param {OpenSeadragon.EventHandler} options.enterHandler * An optional handler for mouse enter. - * @param {Function} options.exitHandler + * @param {OpenSeadragon.EventHandler} options.exitHandler * An optional handler for mouse exit. - * @param {Function} options.pressHandler + * @param {OpenSeadragon.EventHandler} options.pressHandler * An optional handler for mouse press. - * @param {Function} options.releaseHandler + * @param {OpenSeadragon.EventHandler} options.releaseHandler * An optional handler for mouse release. - * @param {Function} options.moveHandler + * @param {OpenSeadragon.EventHandler} options.moveHandler * An optional handler for mouse move. - * @param {Function} options.scrollHandler + * @param {OpenSeadragon.EventHandler} options.scrollHandler * An optional handler for mouse scroll. - * @param {Function} options.clickHandler + * @param {OpenSeadragon.EventHandler} options.clickHandler * An optional handler for mouse click. - * @param {Function} options.dragHandler + * @param {OpenSeadragon.EventHandler} options.dragHandler * An optional handler for mouse drag. - * @param {Function} options.keyHandler + * @param {OpenSeadragon.EventHandler} options.keyHandler * An optional handler for keypress. - * @param {Function} options.focusHandler + * @param {OpenSeadragon.EventHandler} options.focusHandler * An optional handler for focus. - * @param {Function} options.blurHandler + * @param {OpenSeadragon.EventHandler} options.blurHandler * An optional handler for blur. * @param {Object} [options.userData=null] * Arbitrary object to be passed unchanged to any attached handler methods. @@ -188,7 +189,7 @@ }; - $.MouseTracker.prototype = { + $.MouseTracker.prototype = /** @lends OpenSeadragon.MouseTracker.prototype */{ /** * Clean up any events or objects created by the mouse tracker. @@ -374,7 +375,7 @@ * @param {OpenSeadragon.Point} event.position * The position of the event relative to the tracked element. * @param {Number} event.quick - * True only if the clickDistThreshold and clickDeltaThreshold are both pased. Useful for ignoring events. + * True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for ignoring events. * @param {Boolean} event.shift * True if the shift key was pressed during this event. * @param {Boolean} event.isTouchEvent diff --git a/src/navigator.js b/src/navigator.js index 8c8d344c..c90aafb0 100644 --- a/src/navigator.js +++ b/src/navigator.js @@ -40,8 +40,8 @@ * of reference in the larger viewport as to which portion of the image * is currently being examined. The navigator's viewport can be interacted * with using the keyboard or the mouse. - * @class - * @name OpenSeadragon.Navigator + * @class Navigator + * @memberof OpenSeadragon * @extends OpenSeadragon.Viewer * @extends OpenSeadragon.EventSource * @param {Object} options @@ -196,11 +196,10 @@ $.Navigator = function( options ){ }; -$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, { +$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, /** @lends OpenSeadragon.Navigator.prototype */{ /** * @function - * @name OpenSeadragon.Navigator.prototype.update */ update: function( viewport ){ diff --git a/src/openseadragon.js b/src/openseadragon.js index 7f452c25..661bca23 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -101,15 +101,15 @@ */ /** - * The root namespace for OpenSeadragon, this function also serves as a single - * point of instantiation for an {@link OpenSeadragon.Viewer}, including all - * combinations of out-of-the-box configurable features. All utility methods - * and classes are defined on or below this namespace. + * @module OpenSeadragon + */ + + /** + * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all + * combinations of out-of-the-box configurable features. * - * @namespace - * @function - * @name OpenSeadragon - * @exports $ as OpenSeadragon + * @function OpenSeadragon + * @memberof module:OpenSeadragon * * @param {Object} options All required and optional settings for instantiating * a new instance of an OpenSeadragon image viewer. @@ -274,6 +274,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; + +/** + * The root namespace for OpenSeadragon. All utility methods + * and classes are defined on or below this namespace. + * + * @namespace OpenSeadragon + */ + + (function( $ ){ @@ -298,9 +307,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isFunction - * @function - * @see jQuery + * @function isFunction + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isFunction = function( obj ) { return $.type(obj) === "function"; @@ -309,9 +318,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isArray - * @function - * @see jQuery + * @function isArray + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isArray = Array.isArray || function( obj ) { return $.type(obj) === "array"; @@ -321,9 +330,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * A crude way of determining if an object is a window. * Taken from jQuery 1.6.1 - * @name $.isWindow - * @function - * @see jQuery + * @function isWindow + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isWindow = function( obj ) { return obj && typeof obj === "object" && "setInterval" in obj; @@ -332,9 +341,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.type - * @function - * @see jQuery + * @function type + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.type = function( obj ) { return ( obj === null ) || ( obj === undefined ) ? @@ -345,9 +354,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isPlainObject - * @function - * @see jQuery + * @function isPlainObject + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isPlainObject = function( obj ) { // Must be an Object. @@ -376,9 +385,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isEmptyObject - * @function - * @see jQuery + * @function isEmptyObject + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isEmptyObject = function( obj ) { for ( var name in obj ) { @@ -390,8 +399,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * True if the browser supports the HTML5 canvas element - * @name $.supportsCanvas - * @property + * @member {Boolean} supportsCanvas + * @memberof OpenSeadragon */ $.supportsCanvas = (function () { var canvasElement = document.createElement( 'canvas' ); @@ -418,7 +427,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @see jQuery + * @function extend + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.extend = function() { var options, @@ -491,7 +502,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; - $.extend( $, { + $.extend( $, /** @lends OpenSeadragon */{ /** * These are the default values for the optional settings documented * in the {@link OpenSeadragon} constructor detail. @@ -1611,10 +1622,10 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * The current browser vendor, version, and related information regarding - * detected features. Features include
- * 'alpha' - Does the browser support image alpha + * detected features. Features include *'alpha'* - Does the browser support image alpha * transparency.
- * @name $.Browser + * @member {Object} Browser + * @memberof OpenSeadragon * @static */ $.Browser = { diff --git a/src/osmtilesource.js b/src/osmtilesource.js index 23c8d635..11cbc2d6 100644 --- a/src/osmtilesource.js +++ b/src/osmtilesource.js @@ -56,7 +56,8 @@ * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864 * pixels. * - * @class + * @class OsmTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -99,14 +100,13 @@ $.OsmTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) { }; -$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { +$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.OsmTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.OsmTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -120,7 +120,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.OsmTileSource.prototype.configure * @param {Object} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -133,7 +132,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.OsmTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/overlay.js b/src/overlay.js index b828ac9e..109f34c5 100644 --- a/src/overlay.js +++ b/src/overlay.js @@ -38,6 +38,8 @@ * An enumeration of positions that an overlay may be assigned relative * to the viewport including CENTER, TOP_LEFT (default), TOP, TOP_RIGHT, * RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT. + * @member OverlayPlacement + * @memberof OpenSeadragon * @static */ $.OverlayPlacement = { @@ -54,7 +56,8 @@ /** * An Overlay provides a - * @class + * @class Overlay + * @memberof OpenSeadragon */ $.Overlay = function( element, location, placement ) { @@ -93,7 +96,7 @@ this.onDraw = options.onDraw; }; - $.Overlay.prototype = { + $.Overlay.prototype = /** @lends OpenSeadragon.Overlay.prototype */{ /** * @function diff --git a/src/point.js b/src/point.js index 806f9fdb..285071e4 100644 --- a/src/point.js +++ b/src/point.js @@ -38,7 +38,8 @@ * A Point is really used as a 2-dimensional vector, equally useful for * representing a point on a plane, or the height and width of a plane * not requiring any other frame of reference. - * @class + * @class Point + * @memberof OpenSeadragon * @param {Number} [x] The vector component 'x'. Defaults to the origin at 0. * @param {Number} [y] The vector component 'y'. Defaults to the origin at 0. * @property {Number} [x] The vector component 'x'. @@ -49,7 +50,7 @@ $.Point = function( x, y ) { this.y = typeof ( y ) == "number" ? y : 0; }; -$.Point.prototype = { +$.Point.prototype = /** @lends OpenSeadragon.Point.prototype */{ /** * Add another Point to this point and return a new Point. diff --git a/src/profiler.js b/src/profiler.js index b7ed0712..1e229b2e 100644 --- a/src/profiler.js +++ b/src/profiler.js @@ -37,7 +37,8 @@ /** * A utility class useful for developers to establish baseline performance * metrics of rendering routines. - * @class + * @class Profiler + * @memberof OpenSeadragon * @property {Boolean} midUpdate * @property {Number} numUpdates * @property {Number} lastBeginTime @@ -66,7 +67,7 @@ $.Profiler = function() { this.maxIdleTime = 0; }; -$.Profiler.prototype = { +$.Profiler.prototype = /** @lends OpenSeadragon.Profiler.prototype */{ /** * @function diff --git a/src/rectangle.js b/src/rectangle.js index a3b1c7dd..819fa7a9 100644 --- a/src/rectangle.js +++ b/src/rectangle.js @@ -40,7 +40,8 @@ * (width, height). The latter component implies the equation of a simple * plane. * - * @class + * @class Rect + * @memberof OpenSeadragon * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. * @param {Number} width The vector component 'height'. @@ -57,7 +58,7 @@ $.Rect = function( x, y, width, height ) { this.height = typeof ( height ) == "number" ? height : 0; }; -$.Rect.prototype = { +$.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{ /** * The aspect ratio is simply the ratio of width to height. diff --git a/src/spring.js b/src/spring.js index 2ef2d220..353c5289 100644 --- a/src/spring.js +++ b/src/spring.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class Spring + * @memberof OpenSeadragon * @param {Object} options - Spring configuration settings. * @param {Number} options.initial - Initial value of spring, default to 0 so * spring is not in motion initally by default. @@ -90,7 +91,7 @@ $.Spring = function( options ) { }; }; -$.Spring.prototype = { +$.Spring.prototype = /** @lends OpenSeadragon.Spring.prototype */{ /** * @function diff --git a/src/tile.js b/src/tile.js index fc985d1e..21eea985 100644 --- a/src/tile.js +++ b/src/tile.js @@ -35,7 +35,8 @@ (function( $ ){ var TILE_CACHE = {}; /** - * @class + * @class Tile + * @memberof OpenSeadragon * @param {Number} level The zoom level this tile belongs to. * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. @@ -94,7 +95,7 @@ $.Tile = function(level, x, y, bounds, exists, url) { this.lastTouchTime = 0; }; -$.Tile.prototype = { +$.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{ /** * Provides a string representation of this tiles level and (x,y) diff --git a/src/tilesource.js b/src/tilesource.js index 7448ba42..58d13718 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -48,7 +48,8 @@ * By default the image pyramid is split into N layers where the images longest * side in M (in pixels), where N is the smallest integer which satisfies * 2^(N+1) >= M. - * @class + * @class TileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Number|Object|Array|String} width * If more than a single argument is supplied, the traditional use of @@ -166,7 +167,7 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve }; -$.TileSource.prototype = { +$.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ /** * @function @@ -297,6 +298,15 @@ $.TileSource.prototype = { } var $TileSource = $.TileSource.determineType( _this, data, url ); if ( !$TileSource ) { + /** + * @event open-failed + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } ); return; } @@ -304,6 +314,14 @@ $.TileSource.prototype = { options = $TileSource.prototype.configure.apply( _this, [ data, url ]); readySource = new $TileSource( options ); _this.ready = true; + /** + * @event ready + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {Object} tileSource + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'ready', { tileSource: readySource } ); }; @@ -344,6 +362,15 @@ $.TileSource.prototype = { msg = formattedExc + " attempting to load TileSource"; } + /*** + * @event open-failed + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: msg, source: url @@ -431,7 +458,7 @@ $.extend( true, $.TileSource.prototype, $.EventSource.prototype ); /** * Decides whether to try to process the response as xml, json, or hand back * the text - * @eprivate + * @private * @inner * @function * @param {XMLHttpRequest} xhr - the completed network request @@ -473,7 +500,7 @@ function processResponse( xhr ){ /** * Determines the TileSource Implementation by introspection of OpenSeadragon * namespace, calling each TileSource implementation of 'isType' - * @eprivate + * @private * @inner * @function * @param {Object|Array|Document} data - the tile source configuration object diff --git a/src/tilesourcecollection.js b/src/tilesourcecollection.js index 218b2e4c..52dcbd67 100644 --- a/src/tilesourcecollection.js +++ b/src/tilesourcecollection.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class TileSourceCollection + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource */ $.TileSourceCollection = function( tileSize, tileSources, rows, layout ) { @@ -92,11 +93,10 @@ $.TileSourceCollection = function( tileSize, tileSources, rows, layout ) { }; -$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { +$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TileSourceCollection.prototype */{ /** * @function - * @name OpenSeadragon.TileSourceCollection.prototype.getTileBounds * @param {Number} level * @param {Number} x * @param {Number} y @@ -118,7 +118,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.TileSourceCollection.prototype.configure */ configure: function( data, url ){ return; @@ -127,7 +126,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.TileSourceCollection.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/tmstilesource.js b/src/tmstilesource.js index 8c0f1780..42857d3e 100644 --- a/src/tmstilesource.js +++ b/src/tmstilesource.js @@ -47,7 +47,8 @@ * TMS tile scheme ( [ as supported by OpenLayers ] is described here * ( http://openlayers.org/dev/examples/tms.html ). * - * @class + * @class TmsTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -91,14 +92,13 @@ $.TmsTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) { }; -$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { +$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TmsTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.TmsTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -109,7 +109,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.TmsTileSource.prototype.configure * @param {Object} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -122,7 +121,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.TmsTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/viewer.js b/src/viewer.js index 3de2671c..577b112a 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -50,7 +50,8 @@ var THIS = {}, * The options below are given in order that they appeared in the constructor * as arguments and we translate a positional call into an idiomatic call. * - * @class + * @class Viewer + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock * @param {Object} options @@ -384,12 +385,11 @@ $.Viewer = function( options ) { }; -$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, { +$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** @lends OpenSeadragon.Viewer.prototype */{ /** * @function - * @name OpenSeadragon.Viewer.prototype.isOpen * @return {Boolean} */ isOpen: function () { @@ -400,7 +400,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * A deprecated function, renamed to 'open' to match event name and * match current 'close' method. * @function - * @name OpenSeadragon.Viewer.prototype.openDzi * @param {String} dzi xml string or the url to a DZI xml document. * @return {OpenSeadragon.Viewer} Chainable. * @@ -470,6 +469,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, openTileSource( _this, event.tileSource ); }); tileSource.addHandler( 'open-failed', function ( event ) { + /** + * @event open-failed + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', event ); }); @@ -483,6 +491,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, //inline configuration $TileSource = $.TileSource.determineType( _this, tileSource ); if ( !$TileSource ) { + /*** + * @event open-failed + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: tileSource @@ -534,6 +551,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, VIEWERS[ this.hash ] = null; delete VIEWERS[ this.hash ]; + /** + * @event close + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'close' ); return this; @@ -593,10 +617,19 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function * @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled + * @param {Boolean} enabled - true to enable, false to disable * @return {OpenSeadragon.Viewer} Chainable. */ setMouseNavEnabled: function( enabled ){ this.innerTracker.setTracking( enabled ); + /** + * @event mouse-enabled + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} enabled + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'mouse-enabled', { enabled: enabled } ); return this; }, @@ -631,6 +664,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } else { beginControlsAutoHide( this ); } + /** + * @event controls-enabled + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} enabled + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'controls-enabled', { enabled: enabled } ); return this; }, @@ -673,6 +714,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullPage: fullPage, preventDefaultAction: false }; + /** + * @event pre-full-page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullPage - True if entering full-page mode, false if exiting full-page mode. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-page mode change. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-page', fullPageEventArgs ); if ( fullPageEventArgs.preventDefaultAction ) { return this; @@ -818,6 +868,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } + /** + * @event full-page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullPage - True if changed to full-page mode, false if exited full-page mode. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'full-page', { fullPage: fullPage } ); return this; @@ -846,6 +904,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullScreen: fullScreen, preventDefaultAction: false }; + /** + * @event pre-full-screen + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullScreen - True if entering full-screen mode, false if exiting full-screen mode. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-screen mode change. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-screen', fullScreeEventArgs ); if ( fullScreeEventArgs.preventDefaultAction ) { return this; @@ -877,6 +944,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, _this.element.style.height = _this.fullPageStyleHeight; } } + /** + * @event full-screen + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullScreen - True if changed to full-screen mode, false if exited full-screen mode. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } ); }; $.addEvent( document, $.fullScreenEventName, onFullScreenChange ); @@ -903,10 +978,19 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function * @name OpenSeadragon.Viewer.prototype.setVisible + * @param {Boolean} visible * @return {OpenSeadragon.Viewer} Chainable. */ setVisible: function( visible ){ this.container.style.visibility = visible ? "" : "hidden"; + /** + * @event visible + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} visible + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'visible', { visible: visible } ); return this; }, @@ -1138,6 +1222,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, goToPage: function( page ){ //page is a 1 based index so normalize now //page = page; + /** + * @event page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} page - The page changed to (1-based). + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'page', { page: page } ); if( this.tileSources.length > page ){ @@ -1163,7 +1255,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Updates the sequence buttons. - * @function + * @function OpenSeadragon.Viewer.prototype._updateSequenceButtons * @private * @param {Number} Sequence Value */ @@ -1193,7 +1285,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Display a message in the viewport - * @function + * @function OpenSeadragon.Viewer.prototype._showMessage * @private * @param {String} text message */ @@ -1212,7 +1304,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Hide any currently displayed viewport message - * @function + * @function OpenSeadragon.Viewer.prototype._hideMessage * @private */ _hideMessage: function () { @@ -1407,6 +1499,14 @@ function openTileSource( viewer, source ) { } VIEWERS[ _this.hash ] = _this; + /** + * @event open + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {OpenSeadragon.TileSource} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open', { source: source } ); return _this; @@ -1512,6 +1612,18 @@ function onCanvasClick( event ) { ); this.viewport.applyConstraints(); } + /** + * @event canvas-click + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} quick - True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for differentiating between clicks and drags. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-click', { tracker: event.eventSource, position: event.position, @@ -1538,6 +1650,18 @@ function onCanvasDrag( event ) { this.viewport.applyConstraints(); } } + /** + * @event canvas-drag + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {OpenSeadragon.Point} delta - The x,y components of the difference between start drag and end drag. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-drag', { tracker: event.eventSource, position: event.position, @@ -1551,6 +1675,18 @@ function onCanvasRelease( event ) { if ( event.insideElementPressed && this.viewport ) { this.viewport.applyConstraints(); } + /** + * @event canvas-release + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-release', { tracker: event.eventSource, position: event.position, @@ -1570,6 +1706,18 @@ function onCanvasScroll( event ) { ); this.viewport.applyConstraints(); } + /** + * @event canvas-scroll + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Number} scroll - The scroll delta for the event. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-scroll', { tracker: event.eventSource, position: event.position, @@ -1588,6 +1736,18 @@ function onContainerExit( event ) { beginControlsAutoHide( this ); } } + /** + * @event container-exit + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-exit', { tracker: event.eventSource, position: event.position, @@ -1604,6 +1764,18 @@ function onContainerRelease( event ) { beginControlsAutoHide( this ); } } + /** + * @event container-release + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-release', { tracker: event.eventSource, position: event.position, @@ -1616,6 +1788,18 @@ function onContainerRelease( event ) { function onContainerEnter( event ) { THIS[ this.hash ].mouseInside = true; abortControlsAutoHide( this ); + /** + * @event container-enter + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-enter', { tracker: event.eventSource, position: event.position, @@ -1672,6 +1856,13 @@ function updateOnce( viewer ) { } if ( !THIS[ viewer.hash ].animating && animated ) { + /** + * @event animation-start + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-start" ); abortControlsAutoHide( viewer ); } @@ -1681,6 +1872,13 @@ function updateOnce( viewer ) { if( viewer.navigator ){ viewer.navigator.update( viewer.viewport ); } + /** + * @event animation + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation" ); } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) { viewer.drawer.update(); @@ -1691,6 +1889,13 @@ function updateOnce( viewer ) { } if ( THIS[ viewer.hash ].animating && !animated ) { + /** + * @event animation-finish + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-finish" ); if ( !THIS[ viewer.hash ].mouseInside ) { diff --git a/src/viewport.js b/src/viewport.js index 12fbd956..788aef13 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -36,7 +36,8 @@ /** - * @class + * @class Viewport + * @memberof OpenSeadragon */ $.Viewport = function( options ) { @@ -105,7 +106,7 @@ $.Viewport = function( options ) { this.update(); }; -$.Viewport.prototype = { +$.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function @@ -121,6 +122,14 @@ $.Viewport.prototype = { this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY ); if( this.viewer ){ + /** + * @event reset-size + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} contentSize + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'reset-size', { contentSize: contentSize }); @@ -167,6 +176,14 @@ $.Viewport.prototype = { */ goHome: function( immediately ) { if( this.viewer ){ + /** + * @event home + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'home', { immediately: immediately }); @@ -367,6 +384,14 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event constrain + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'constrain', { immediately: immediately }); @@ -518,6 +543,15 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event pan + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} center + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'pan', { center: center, immediately: immediately @@ -560,6 +594,16 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event zoom + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Number} zoom + * @property {OpenSeadragon.Point} refPoint + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'zoom', { zoom: zoom, refPoint: refPoint, @@ -576,7 +620,6 @@ $.Viewport.prototype = { * debug mode doesn't rotate yet, and overlay rotation is only * partially supported. * @function - * @name OpenSeadragon.Viewport.prototype.setRotation * @return {OpenSeadragon.Viewport} Chainable. */ setRotation: function( degrees ) { @@ -597,7 +640,6 @@ $.Viewport.prototype = { /** * Gets the current rotation in degrees. * @function - * @name OpenSeadragon.Viewport.prototype.getRotation * @return {Number} The current rotation in degrees. */ getRotation: function() { @@ -624,6 +666,15 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event resize + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} newContainerSize + * @property {Boolean} maintain + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'resize', { newContainerSize: newContainerSize, maintain: maintain From 54049927f0c4ce7c26d94759ba3108608a93ad02 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 18 Nov 2013 06:56:32 -0800 Subject: [PATCH 02/18] Updated doclets Changed event docs: Changed userData properties from optional to nullable. Removed optional type from preventDefaultAction properties. --- src/button.js | 18 ++++++++--------- src/drawer.js | 16 +++++++-------- src/mousetracker.js | 48 ++++++++++++++++++++++----------------------- src/tilesource.js | 6 +++--- src/viewer.js | 48 ++++++++++++++++++++++----------------------- src/viewport.js | 12 ++++++------ 6 files changed, 74 insertions(+), 74 deletions(-) diff --git a/src/button.js b/src/button.js index 1cc819ef..546958f1 100644 --- a/src/button.js +++ b/src/button.js @@ -187,7 +187,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "enter", { originalEvent: event.originalEvent } ); } else if ( !event.buttonDownAny ) { @@ -203,7 +203,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "focus", { originalEvent: event.originalEvent } ); }, @@ -217,7 +217,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "exit", { originalEvent: event.originalEvent } ); } @@ -231,7 +231,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "blur", { originalEvent: event.originalEvent } ); }, @@ -244,7 +244,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "press", { originalEvent: event.originalEvent } ); }, @@ -258,7 +258,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); } else if ( event.insideElementPressed ) { @@ -276,7 +276,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent("click", { originalEvent: event.originalEvent }); } @@ -291,7 +291,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "click", { originalEvent: event.originalEvent } ); /*** @@ -300,7 +300,7 @@ $.Button = function( options ) { * @type {object} * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); return false; diff --git a/src/drawer.js b/src/drawer.js index 85ae741b..5999d18e 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -208,7 +208,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @property {Element} element * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location * @property {OpenSeadragon.OverlayPlacement} placement - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'add-overlay', { element: element, @@ -249,7 +249,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @property {Element} element * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location * @property {OpenSeadragon.OverlayPlacement} placement - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'update-overlay', { element: element, @@ -286,7 +286,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Element} element - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'remove-overlay', { element: element @@ -312,7 +312,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'clear-overlay', {} ); } @@ -512,7 +512,7 @@ function updateViewport( drawer ) { * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'update-viewport', {} ); } @@ -701,7 +701,7 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi * @property {Object} bottomright * @property {Object} currenttime * @property {Object} best - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'update-level', { havedrawn: haveDrawn, @@ -772,7 +772,7 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Object} tile - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'update-tile', { tile: tile @@ -1294,7 +1294,7 @@ function drawTiles( drawer, lastDrawn ){ * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Object} tile - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'tile-drawn', { tile: tile diff --git a/src/mousetracker.js b/src/mousetracker.js index 95012f85..596ad166 100644 --- a/src/mousetracker.js +++ b/src/mousetracker.js @@ -244,8 +244,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -269,8 +269,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -289,8 +289,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -314,8 +314,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -334,8 +334,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -358,8 +358,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -382,8 +382,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -406,8 +406,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -426,8 +426,8 @@ * True if the original event is a touch event, otherwise false. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -446,8 +446,8 @@ * True if the shift key was pressed during this event. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -462,8 +462,8 @@ * A reference to the tracker instance. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ @@ -478,8 +478,8 @@ * A reference to the tracker instance. * @param {Object} event.originalEvent * The original event object. - * @param {Boolean} [event.preventDefaultAction=false] - * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). + * @param {Boolean} event.preventDefaultAction + * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false. * @param {Object} event.userData * Arbitrary user-defined object. */ diff --git a/src/tilesource.js b/src/tilesource.js index 58d13718..adadf97f 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -305,7 +305,7 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. * @property {String} message * @property {String} source - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } ); return; @@ -320,7 +320,7 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ * @type {object} * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. * @property {Object} tileSource - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'ready', { tileSource: readySource } ); }; @@ -369,7 +369,7 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. * @property {String} message * @property {String} source - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'open-failed', { message: msg, diff --git a/src/viewer.js b/src/viewer.js index 577b112a..d7965559 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -476,7 +476,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {String} message * @property {String} source - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'open-failed', event ); }); @@ -498,7 +498,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {String} message * @property {String} source - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", @@ -556,7 +556,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'close' ); @@ -628,7 +628,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} enabled - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'mouse-enabled', { enabled: enabled } ); return this; @@ -670,7 +670,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} enabled - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'controls-enabled', { enabled: enabled } ); return this; @@ -720,8 +720,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} fullPage - True if entering full-page mode, false if exiting full-page mode. - * @property {Boolean} preventDefaultAction - Set to true to prevent full-page mode change. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-page mode change. Default: false. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'pre-full-page', fullPageEventArgs ); if ( fullPageEventArgs.preventDefaultAction ) { @@ -874,7 +874,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} fullPage - True if changed to full-page mode, false if exited full-page mode. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'full-page', { fullPage: fullPage } ); @@ -910,8 +910,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} fullScreen - True if entering full-screen mode, false if exiting full-screen mode. - * @property {Boolean} preventDefaultAction - Set to true to prevent full-screen mode change. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-screen mode change. Default: false. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'pre-full-screen', fullScreeEventArgs ); if ( fullScreeEventArgs.preventDefaultAction ) { @@ -950,7 +950,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} fullScreen - True if changed to full-screen mode, false if exited full-screen mode. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } ); }; @@ -989,7 +989,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Boolean} visible - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'visible', { visible: visible } ); return this; @@ -1228,7 +1228,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {Object} page - The page changed to (1-based). - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'page', { page: page } ); @@ -1505,7 +1505,7 @@ function openTileSource( viewer, source ) { * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {OpenSeadragon.TileSource} source - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ _this.raiseEvent( 'open', { source: source } ); @@ -1622,7 +1622,7 @@ function onCanvasClick( event ) { * @property {Boolean} quick - True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for differentiating between clicks and drags. * @property {Boolean} shift - True if the shift key was pressed during this event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'canvas-click', { tracker: event.eventSource, @@ -1660,7 +1660,7 @@ function onCanvasDrag( event ) { * @property {OpenSeadragon.Point} delta - The x,y components of the difference between start drag and end drag. * @property {Boolean} shift - True if the shift key was pressed during this event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'canvas-drag', { tracker: event.eventSource, @@ -1685,7 +1685,7 @@ function onCanvasRelease( event ) { * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'canvas-release', { tracker: event.eventSource, @@ -1716,7 +1716,7 @@ function onCanvasScroll( event ) { * @property {Number} scroll - The scroll delta for the event. * @property {Boolean} shift - True if the shift key was pressed during this event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'canvas-scroll', { tracker: event.eventSource, @@ -1746,7 +1746,7 @@ function onContainerExit( event ) { * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'container-exit', { tracker: event.eventSource, @@ -1774,7 +1774,7 @@ function onContainerRelease( event ) { * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'container-release', { tracker: event.eventSource, @@ -1798,7 +1798,7 @@ function onContainerEnter( event ) { * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. * @property {Object} originalEvent - The original DOM event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'container-enter', { tracker: event.eventSource, @@ -1861,7 +1861,7 @@ function updateOnce( viewer ) { * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ viewer.raiseEvent( "animation-start" ); abortControlsAutoHide( viewer ); @@ -1877,7 +1877,7 @@ function updateOnce( viewer ) { * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ viewer.raiseEvent( "animation" ); } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) { @@ -1894,7 +1894,7 @@ function updateOnce( viewer ) { * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ viewer.raiseEvent( "animation-finish" ); diff --git a/src/viewport.js b/src/viewport.js index 788aef13..3c48e1c5 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -128,7 +128,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. * @property {OpenSeadragon.Point} contentSize - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'reset-size', { contentSize: contentSize @@ -182,7 +182,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. * @property {Boolean} immediately - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'home', { immediately: immediately @@ -390,7 +390,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. * @property {Boolean} immediately - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'constrain', { immediately: immediately @@ -550,7 +550,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. * @property {OpenSeadragon.Point} center * @property {Boolean} immediately - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'pan', { center: center, @@ -602,7 +602,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @property {Number} zoom * @property {OpenSeadragon.Point} refPoint * @property {Boolean} immediately - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'zoom', { zoom: zoom, @@ -673,7 +673,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. * @property {OpenSeadragon.Point} newContainerSize * @property {Boolean} maintain - * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'resize', { newContainerSize: newContainerSize, From ccee9f514908886126a10febf458e3818a743a49 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 18 Nov 2013 09:44:54 -0800 Subject: [PATCH 03/18] Updated doclets Updated creation option defaults (issue #93) --- src/openseadragon.js | 79 +++++++++++++++++++++++++++++++++++--------- src/viewer.js | 4 +-- 2 files changed, 64 insertions(+), 19 deletions(-) diff --git a/src/openseadragon.js b/src/openseadragon.js index 661bca23..ec61325d 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -114,11 +114,11 @@ * @param {Object} options All required and optional settings for instantiating * a new instance of an OpenSeadragon image viewer. * - * @param {String} options.xmlPath + * @param {String} [options.xmlPath=null] * DEPRECATED. A relative path to load a DZI file from the server. * Prefer the newer options.tileSources. * - * @param {Array|String|Function|Object[]|Array[]|String[]|Function[]} options.tileSources + * @param {Array|String|Function|Object[]|Array[]|String[]|Function[]} [options.tileSources=null] * As an Array, the tileSource can hold either be all Objects or mixed * types of Arrays of Objects, String, Function. When a value is a String, * the tileSource is used to create a {@link OpenSeadragon.DziTileSource}. @@ -128,15 +128,19 @@ * is an Array of objects, it is used to create a * {@link OpenSeadragon.LegacyTileSource}. * - * @param {Boolean} [options.debugMode=true] - * Currently does nothing. TODO: provide an in-screen panel providing event - * detail feedback. + * @param {Object} [options.tileHost=null] + * TODO: Implement this. Currently not used. * - * @param {Number} [options.animationTime=1.5] + * @param {Boolean} [options.debugMode=false] + * TODO: provide an in-screen panel providing event detail feedback. + * + * @param {String} [options.debugGridColor='#437AB2'] + * + * @param {Number} [options.animationTime=1.2] * Specifies the animation duration per each {@link OpenSeadragon.Spring} * which occur when the image is dragged or zoomed. * - * @param {Number} [options.blendTime=0.5] + * @param {Number} [options.blendTime=0] * Specifies the duration of animation as higher or lower level tiles are * replacing the existing tile. * @@ -155,6 +159,25 @@ * provide the effect of very blurry to sharp. It is recommended to change * setting to true for mobile devices. * + * @param {Number} [options.defaultZoomLevel=0] + * Zoom level to use when image is first opened or the home button is clicked. + * If 0, adjusts to fit viewer. + * + * @param {Number} [options.degrees=0] + * Initial rotation. + * + * @param {Number} [options.minZoomLevel=null] + * + * @param {Number} [options.maxZoomLevel=null] + * + * @param {Boolean} [options.panHorizontal=true] + * Allow horizontal pan. + * + * @param {Boolean} [options.panVertical=true] + * Allow vertical pan. + * + * @param {Boolean} [options.constrainDuringPan=false] + * * @param {Boolean} [options.wrapHorizontal=false] * Set to true to force the image to wrap horizontally within the viewport. * Useful for maps or images representing the surface of a sphere or cylinder. @@ -163,17 +186,20 @@ * Set to true to force the image to wrap vertically within the viewport. * Useful for maps or images representing the surface of a sphere or cylinder. * - * @param {Number} [options.minZoomImageRatio=0.8] + * @param {Number} [options.minZoomImageRatio=0.9] * The minimum percentage ( expressed as a number between 0 and 1 ) of * the viewport height or width at which the zoom out will be constrained. * Setting it to 0, for example will allow you to zoom out infinitly. * - * @param {Number} [options.maxZoomPixelRatio=2] + * @param {Number} [options.maxZoomPixelRatio=1.1] * The maximum ratio to allow a zoom-in to affect the highest level pixel * ratio. This can be set to Infinity to allow 'infinite' zooming into the * image though it is less effective visually if the HTML5 Canvas is not * availble on the viewing device. * + * @param {Number} [options.pixelsPerWheelLine=40] + * For pixel-resolution scrolling devices, the number of pixels equal to one scroll line. + * * @param {Number} [options.visibilityRatio=0.5] * The percentage ( as a number from 0 to 1 ) of the source image which * must be kept within the viewport. If the image is dragged beyond that @@ -181,14 +207,14 @@ * achieved. Setting this to 0 and wrapHorizontal ( or wrapVertical ) to * true will provide the effect of an infinitely scrolling viewport. * - * @param {Number} [options.springStiffness=5.0] + * @param {Number} [options.springStiffness=7.0] * * @param {Number} [options.imageLoaderLimit=0] * The maximum number of image requests to make concurrently. By default * it is set to 0 allowing the browser to make the maximum number of * image requests in parallel as allowed by the browsers policy. * - * @param {Number} [options.clickTimeThreshold=200] + * @param {Number} [options.clickTimeThreshold=300] * If multiple mouse clicks occurs within less than this number of * milliseconds, treat them as a single click. * @@ -202,7 +228,7 @@ * @param {Number} [options.zoomPerScroll=1.2] * The "zoom distance" per mouse scroll or touch pinch. * - * @param {Number} [options.zoomPerSecond=2.0] + * @param {Number} [options.zoomPerSecond=1.0] * The number of seconds to animate a single zoom event over. * * @param {Boolean} [options.showNavigationControl=true] @@ -215,6 +241,18 @@ * Set the ID of a div to hold the navigator minimap. If one is not specified, * one will be generated and placed on top of the main image * + * @param {Number} [options.navigatorHeight=null] + * TODO: Implement this. Currently not used. + * + * @param {Number} [options.navigatorWidth=null] + * TODO: Implement this. Currently not used. + * + * @param {Number} [options.navigatorPosition=null] + * TODO: Implement this. Currently not used. + * + * @param {Number} [options.navigatorSizeRatio=0.2] + * Ratio of navigator size to viewer size. + * * @param {Number} [options.controlsFadeDelay=2000] * The number of milliseconds to wait once the user has stopped interacting * with the interface before begining to fade the controls. Assumes @@ -223,9 +261,11 @@ * @param {Number} [options.controlsFadeLength=1500] * The number of milliseconds to animate the controls fading out. * - * @param {Number} [options.maxImageCacheCount=100] + * @param {Number} [options.maxImageCacheCount=200] * The max number of images we should keep in memory (per drawer). * + * @param {Number} [options.timeout=30000] + * * @param {Boolean} [options.useCanvas=true] * Set to false to not use an HTML canvas element for image rendering even if canvas is supported. * @@ -240,6 +280,13 @@ * interactions include draging the image in a plane, and zooming in toward * and away from the image. * + * @param {Boolean} [options.showSequenceControl=true] + * If the viewer has been configured with a sequence of tile sources, then + * provide buttons for navigating forward and backward through the images. + * + * @param {Number} [options.initialPage=0] + * If the viewer has been configured with a sequence of tile sources, display this page initially. + * * @param {Boolean} [options.preserveViewport=false] * If the viewer has been configured with a sequence of tile sources, then * normally navigating to through each image resets the viewport to 'home' @@ -505,8 +552,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ $.extend( $, /** @lends OpenSeadragon */{ /** * These are the default values for the optional settings documented - * in the {@link OpenSeadragon} constructor detail. - * @name $.DEFAULT_SETTINGS + * in the {@link module:OpenSeadragon} constructor detail. + * @member DEFAULT_SETTINGS + * @memberof OpenSeadragon * @static */ DEFAULT_SETTINGS: { @@ -646,7 +694,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Invokes the the method as if it where a method belonging to the object. - * @name $.delegate * @function * @param {Object} object * @param {Function} method diff --git a/src/viewer.js b/src/viewer.js index d7965559..d58cb671 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -1220,14 +1220,12 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @return {OpenSeadragon.Viewer} Chainable. */ goToPage: function( page ){ - //page is a 1 based index so normalize now - //page = page; /** * @event page * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} page - The page changed to (1-based). + * @property {Object} page - The page index to change to. * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.raiseEvent( 'page', { page: page } ); From b929f2687218f5629db90d7432856d53c6a7230e Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 18 Nov 2013 10:06:38 -0800 Subject: [PATCH 04/18] Updated doclets Creation options now documented in a typedef doclet named OpenSeadragon.Options. --- src/openseadragon.js | 121 ++++++++++++++++++++++--------------------- src/viewer.js | 2 +- 2 files changed, 64 insertions(+), 59 deletions(-) diff --git a/src/openseadragon.js b/src/openseadragon.js index ec61325d..a151c079 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -105,20 +105,16 @@ */ /** - * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all - * combinations of out-of-the-box configurable features. + * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer. * - * @function OpenSeadragon - * @memberof module:OpenSeadragon + * @typedef {Object} Options + * @memberof OpenSeadragon * - * @param {Object} options All required and optional settings for instantiating - * a new instance of an OpenSeadragon image viewer. - * - * @param {String} [options.xmlPath=null] + * @property {String} [xmlPath=null] * DEPRECATED. A relative path to load a DZI file from the server. - * Prefer the newer options.tileSources. + * Prefer the newer Options.tileSources. * - * @param {Array|String|Function|Object[]|Array[]|String[]|Function[]} [options.tileSources=null] + * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null] * As an Array, the tileSource can hold either be all Objects or mixed * types of Arrays of Objects, String, Function. When a value is a String, * the tileSource is used to create a {@link OpenSeadragon.DziTileSource}. @@ -128,177 +124,177 @@ * is an Array of objects, it is used to create a * {@link OpenSeadragon.LegacyTileSource}. * - * @param {Object} [options.tileHost=null] + * @property {Object} [tileHost=null] * TODO: Implement this. Currently not used. * - * @param {Boolean} [options.debugMode=false] + * @property {Boolean} [debugMode=false] * TODO: provide an in-screen panel providing event detail feedback. * - * @param {String} [options.debugGridColor='#437AB2'] + * @property {String} [debugGridColor='#437AB2'] * - * @param {Number} [options.animationTime=1.2] + * @property {Number} [animationTime=1.2] * Specifies the animation duration per each {@link OpenSeadragon.Spring} * which occur when the image is dragged or zoomed. * - * @param {Number} [options.blendTime=0] + * @property {Number} [blendTime=0] * Specifies the duration of animation as higher or lower level tiles are * replacing the existing tile. * - * @param {Boolean} [options.alwaysBlend=false] + * @property {Boolean} [alwaysBlend=false] * Forces the tile to always blend. By default the tiles skip blending * when the blendTime is surpassed and the current animation frame would * not complete the blend. * - * @param {Boolean} [options.autoHideControls=true] + * @property {Boolean} [autoHideControls=true] * If the user stops interacting with the viewport, fade the navigation * controls. Useful for presentation since the controls are by default * floated on top of the image the user is viewing. * - * @param {Boolean} [options.immediateRender=false] + * @property {Boolean} [immediateRender=false] * Render the best closest level first, ignoring the lowering levels which * provide the effect of very blurry to sharp. It is recommended to change * setting to true for mobile devices. * - * @param {Number} [options.defaultZoomLevel=0] + * @property {Number} [defaultZoomLevel=0] * Zoom level to use when image is first opened or the home button is clicked. * If 0, adjusts to fit viewer. * - * @param {Number} [options.degrees=0] + * @property {Number} [degrees=0] * Initial rotation. * - * @param {Number} [options.minZoomLevel=null] + * @property {Number} [minZoomLevel=null] * - * @param {Number} [options.maxZoomLevel=null] + * @property {Number} [maxZoomLevel=null] * - * @param {Boolean} [options.panHorizontal=true] + * @property {Boolean} [panHorizontal=true] * Allow horizontal pan. * - * @param {Boolean} [options.panVertical=true] + * @property {Boolean} [panVertical=true] * Allow vertical pan. * - * @param {Boolean} [options.constrainDuringPan=false] + * @property {Boolean} [constrainDuringPan=false] * - * @param {Boolean} [options.wrapHorizontal=false] + * @property {Boolean} [wrapHorizontal=false] * Set to true to force the image to wrap horizontally within the viewport. * Useful for maps or images representing the surface of a sphere or cylinder. * - * @param {Boolean} [options.wrapVertical=false] + * @property {Boolean} [wrapVertical=false] * Set to true to force the image to wrap vertically within the viewport. * Useful for maps or images representing the surface of a sphere or cylinder. * - * @param {Number} [options.minZoomImageRatio=0.9] + * @property {Number} [minZoomImageRatio=0.9] * The minimum percentage ( expressed as a number between 0 and 1 ) of * the viewport height or width at which the zoom out will be constrained. * Setting it to 0, for example will allow you to zoom out infinitly. * - * @param {Number} [options.maxZoomPixelRatio=1.1] + * @property {Number} [maxZoomPixelRatio=1.1] * The maximum ratio to allow a zoom-in to affect the highest level pixel * ratio. This can be set to Infinity to allow 'infinite' zooming into the * image though it is less effective visually if the HTML5 Canvas is not * availble on the viewing device. * - * @param {Number} [options.pixelsPerWheelLine=40] + * @property {Number} [pixelsPerWheelLine=40] * For pixel-resolution scrolling devices, the number of pixels equal to one scroll line. * - * @param {Number} [options.visibilityRatio=0.5] + * @property {Number} [visibilityRatio=0.5] * The percentage ( as a number from 0 to 1 ) of the source image which * must be kept within the viewport. If the image is dragged beyond that * limit, it will 'bounce' back until the minimum visibility ration is * achieved. Setting this to 0 and wrapHorizontal ( or wrapVertical ) to * true will provide the effect of an infinitely scrolling viewport. * - * @param {Number} [options.springStiffness=7.0] + * @property {Number} [springStiffness=7.0] * - * @param {Number} [options.imageLoaderLimit=0] + * @property {Number} [imageLoaderLimit=0] * The maximum number of image requests to make concurrently. By default * it is set to 0 allowing the browser to make the maximum number of * image requests in parallel as allowed by the browsers policy. * - * @param {Number} [options.clickTimeThreshold=300] + * @property {Number} [clickTimeThreshold=300] * If multiple mouse clicks occurs within less than this number of * milliseconds, treat them as a single click. * - * @param {Number} [options.clickDistThreshold=5] + * @property {Number} [clickDistThreshold=5] * If a mouse or touch drag occurs and the distance to the starting drag * point is less than this many pixels, ignore the drag event. * - * @param {Number} [options.zoomPerClick=2.0] + * @property {Number} [zoomPerClick=2.0] * The "zoom distance" per mouse click or touch tap. * - * @param {Number} [options.zoomPerScroll=1.2] + * @property {Number} [zoomPerScroll=1.2] * The "zoom distance" per mouse scroll or touch pinch. * - * @param {Number} [options.zoomPerSecond=1.0] + * @property {Number} [zoomPerSecond=1.0] * The number of seconds to animate a single zoom event over. * - * @param {Boolean} [options.showNavigationControl=true] + * @property {Boolean} [showNavigationControl=true] * Set to false to prevent the appearance of the default navigation controls. * - * @param {Boolean} [options.showNavigator=false] + * @property {Boolean} [showNavigator=false] * Set to true to make the navigator minimap appear. * - * @param {Boolean} [options.navigatorId=navigator-GENERATED DATE] + * @property {Boolean} [navigatorId=navigator-GENERATED DATE] * Set the ID of a div to hold the navigator minimap. If one is not specified, * one will be generated and placed on top of the main image * - * @param {Number} [options.navigatorHeight=null] + * @property {Number} [navigatorHeight=null] * TODO: Implement this. Currently not used. * - * @param {Number} [options.navigatorWidth=null] + * @property {Number} [navigatorWidth=null] * TODO: Implement this. Currently not used. * - * @param {Number} [options.navigatorPosition=null] + * @property {Number} [navigatorPosition=null] * TODO: Implement this. Currently not used. * - * @param {Number} [options.navigatorSizeRatio=0.2] + * @property {Number} [navigatorSizeRatio=0.2] * Ratio of navigator size to viewer size. * - * @param {Number} [options.controlsFadeDelay=2000] + * @property {Number} [controlsFadeDelay=2000] * The number of milliseconds to wait once the user has stopped interacting * with the interface before begining to fade the controls. Assumes * showNavigationControl and autoHideControls are both true. * - * @param {Number} [options.controlsFadeLength=1500] + * @property {Number} [controlsFadeLength=1500] * The number of milliseconds to animate the controls fading out. * - * @param {Number} [options.maxImageCacheCount=200] + * @property {Number} [maxImageCacheCount=200] * The max number of images we should keep in memory (per drawer). * - * @param {Number} [options.timeout=30000] + * @property {Number} [timeout=30000] * - * @param {Boolean} [options.useCanvas=true] + * @property {Boolean} [useCanvas=true] * Set to false to not use an HTML canvas element for image rendering even if canvas is supported. * - * @param {Number} [options.minPixelRatio=0.5] + * @property {Number} [minPixelRatio=0.5] * The higher the minPixelRatio, the lower the quality of the image that * is considered sufficient to stop rendering a given zoom level. For * example, if you are targeting mobile devices with less bandwith you may * try setting this to 1.5 or higher. * - * @param {Boolean} [options.mouseNavEnabled=true] + * @property {Boolean} [mouseNavEnabled=true] * Is the user able to interact with the image via mouse or touch. Default * interactions include draging the image in a plane, and zooming in toward * and away from the image. * - * @param {Boolean} [options.showSequenceControl=true] + * @property {Boolean} [showSequenceControl=true] * If the viewer has been configured with a sequence of tile sources, then * provide buttons for navigating forward and backward through the images. * - * @param {Number} [options.initialPage=0] + * @property {Number} [initialPage=0] * If the viewer has been configured with a sequence of tile sources, display this page initially. * - * @param {Boolean} [options.preserveViewport=false] + * @property {Boolean} [preserveViewport=false] * If the viewer has been configured with a sequence of tile sources, then * normally navigating to through each image resets the viewport to 'home' * position. If preserveViewport is set to true, then the viewport position * is preserved when navigating between images in the sequence. * - * @param {String} [options.prefixUrl='/images/'] + * @property {String} [prefixUrl='/images/'] * Prepends the prefixUrl to navImages paths, which is very useful * since the default paths are rarely useful for production * environments. * - * @param {Object} [options.navImages=] + * @property {Object} [navImages=] * An object with a property for each button or other built-in navigation * control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'. * Each of those in turn provides an image path for each state of the botton @@ -308,11 +304,20 @@ * these paths, prefer setting the option.prefixUrl rather than overriding * every image path directly through this setting. * - * @param {Boolean} [options.navPrevNextWrap=false] + * @property {Boolean} [navPrevNextWrap=false] * If the 'previous' button will wrap to the last image when viewing the first * image and if the 'next' button will wrap to the first image when viewing * the last image. * + */ + + /** + * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all + * combinations of out-of-the-box configurable features. + * + * @function OpenSeadragon + * @memberof module:OpenSeadragon + * @param {OpenSeadragon.Options} options * @returns {OpenSeadragon.Viewer} */ window.OpenSeadragon = window.OpenSeadragon || function( options ){ diff --git a/src/viewer.js b/src/viewer.js index d58cb671..eecfd1a6 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -54,7 +54,7 @@ var THIS = {}, * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock - * @param {Object} options + * @param {OpenSeadragon.Options} options * @param {String} options.element Id of Element to attach to, * @param {String} options.xmlPath Xpath ( TODO: not sure! ), * @param {String} options.prefixUrl Url used to prepend to paths, eg button From 3e1e5321c18b5415792e822dd0b78d1e0b86648e Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 18 Nov 2013 10:30:48 -0800 Subject: [PATCH 05/18] Updated doclets openseadragon.js doc fixups --- src/openseadragon.js | 45 ++++++++------------------------------------ 1 file changed, 8 insertions(+), 37 deletions(-) diff --git a/src/openseadragon.js b/src/openseadragon.js index a151c079..6796955b 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -557,7 +557,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ $.extend( $, /** @lends OpenSeadragon */{ /** * These are the default values for the optional settings documented - * in the {@link module:OpenSeadragon} constructor detail. + * at {@link OpenSeadragon.Options}. * @member DEFAULT_SETTINGS * @memberof OpenSeadragon * @static @@ -717,7 +717,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * An enumeration of Browser vendors including UNKNOWN, IE, FIREFOX, * SAFARI, CHROME, and OPERA. - * @name $.BROWSERS * @static */ BROWSERS: { @@ -733,7 +732,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Returns a DOM Element for the given id or element. * @function - * @name OpenSeadragon.getElement * @param {String|Element} element Accepts an id or element. * @returns {Element} The element with the given id, null, or the element itself. */ @@ -748,9 +746,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Determines the position of the upper-left corner of the element. * @function - * @name OpenSeadragon.getElementPosition * @param {Element|String} element - the elemenet we want the position for. - * @returns {Point} - the position of the upper left corner of the element. + * @returns {OpenSeadragon.Point} - the position of the upper left corner of the element. */ getElementPosition: function( element ) { var result = new $.Point(), @@ -782,9 +779,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Determines the position of the upper-left corner of the element adjusted for current page and/or element scroll. * @function - * @name OpenSeadragon.getElementOffset * @param {Element|String} element - the element we want the position for. - * @returns {Point} - the position of the upper left corner of the element adjusted for current page and/or element scroll. + * @returns {OpenSeadragon.Point} - the position of the upper left corner of the element adjusted for current page and/or element scroll. */ getElementOffset: function( element ) { element = $.getElement( element ); @@ -820,9 +816,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Determines the height and width of the given element. * @function - * @name OpenSeadragon.getElementSize * @param {Element|String} element - * @returns {Point} + * @returns {OpenSeadragon.Point} */ getElementSize: function( element ) { element = $.getElement( element ); @@ -837,7 +832,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Returns the CSSStyle object for the given element. * @function - * @name OpenSeadragon.getElementStyle * @param {Element|String} element * @returns {CSSStyle} */ @@ -858,7 +852,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * specific to IE behavior. TODO: Deprecate this from the api and * use it internally. * @function - * @name OpenSeadragon.getEvent * @param {Event} [event] * @returns {Event} */ @@ -879,9 +872,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Gets the position of the mouse on the screen for a given event. * @function - * @name OpenSeadragon.getMousePosition * @param {Event} [event] - * @returns {Point} + * @returns {OpenSeadragon.Point} */ getMousePosition: function( event ) { @@ -924,8 +916,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Determines the page's current scroll position. * @function - * @name OpenSeadragon.getPageScroll - * @returns {Point} + * @returns {OpenSeadragon.Point} */ getPageScroll: function() { var docElement = document.documentElement || {}, @@ -963,8 +954,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Set the page scroll position. * @function - * @name OpenSeadragon.getPageScroll - * @returns {Point} + * @returns {OpenSeadragon.Point} */ setPageScroll: function( scroll ) { if ( typeof ( window.scrollTo ) !== "undefined" ) { @@ -1015,8 +1005,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Determines the size of the browsers window. * @function - * @name OpenSeadragon.getWindowSize - * @returns {Point} + * @returns {OpenSeadragon.Point} */ getWindowSize: function() { var docElement = document.documentElement || {}, @@ -1055,7 +1044,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Wraps the given element in a nest of divs so that the element can * be easily centered using CSS tables * @function - * @name OpenSeadragon.makeCenteredNode * @param {Element|String} element * @returns {Element} outermost wrapper element */ @@ -1103,7 +1091,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Creates an easily positionable element of the given type that therefor * serves as an excellent container element. * @function - * @name OpenSeadragon.makeNeutralElement * @param {String} tagName * @returns {Element} */ @@ -1123,7 +1110,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Returns the current milliseconds, using Date.now() if available - * @name $.now * @function */ now: function( ) { @@ -1142,7 +1128,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Generally only IE has issues doing this correctly for formats like * png. * @function - * @name OpenSeadragon.makeTransparentImage * @param {String} src * @returns {Element} */ @@ -1191,7 +1176,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Sets the opacity of the specified element. * @function - * @name OpenSeadragon.setElementOpacity * @param {Element|String} element * @param {Number} opacity * @param {Boolean} [usesAlpha] @@ -1223,7 +1207,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Add the specified CSS class to the element if not present. - * @name $.addClass * @function * @param {Element|String} element * @param {String} className @@ -1242,7 +1225,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Remove the specified CSS class from the element. - * @name $.removeClass * @function * @param {Element|String} element * @param {String} className @@ -1266,7 +1248,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Adds an event listener for the given element, eventName and handler. * @function - * @name OpenSeadragon.addEvent * @param {Element|String} element * @param {String} eventName * @param {Function} handler @@ -1296,7 +1277,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Remove a given event listener for the given element, event type and * handler. * @function - * @name OpenSeadragon.removeEvent * @param {Element|String} element * @param {String} eventName * @param {Function} handler @@ -1326,7 +1306,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Cancels the default browser behavior had the event propagated all * the way up the DOM to the window object. * @function - * @name OpenSeadragon.cancelEvent * @param {Event} [event] */ cancelEvent: function( event ) { @@ -1353,7 +1332,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Stops the propagation of the event up the DOM. * @function - * @name OpenSeadragon.stopEvent * @param {Event} [event] */ stopEvent: function( event ) { @@ -1385,7 +1363,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * invocation, and each invocation can add additional arguments as well. * * @function - * @name OpenSeadragon.createCallback * @param {Object} object * @param {Function} method * @param [args] any additional arguments are passed as arguments to the @@ -1417,7 +1394,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Retreives the value of a url parameter from the window.location string. * @function - * @name OpenSeadragon.getUrlParameter * @param {String} key * @returns {String} The value of the url parameter or null if no param matches. */ @@ -1462,7 +1438,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Makes an AJAX request. * @function - * @name OpenSeadragon.makeAjaxRequest * @param {String} url - the url to request * @param {Function} onSuccess - a function to call on a successful response * @param {Function} onError - a function to call on when an error occurs @@ -1527,7 +1502,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 * @function - * @name OpenSeadragon.jsonp * @param {Object} options * @param {String} options.url * @param {Function} options.callback @@ -1608,7 +1582,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Fully deprecated. Will throw an error. * @function - * @name OpenSeadragon.createFromDZI * @deprecated - use OpenSeadragon.Viewer.prototype.open */ createFromDZI: function() { @@ -1618,7 +1591,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Parses an XML string into a DOM Document. * @function - * @name OpenSeadragon.parseXml * @param {String} string * @returns {Document} */ @@ -1660,7 +1632,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * Reports whether the image format is supported for tiling in this * version. * @function - * @name OpenSeadragon.imageFormatSupported * @param {String} [extension] * @returns {Boolean} */ From 09de239bfa89d39f7975fe12d2315fad34d50357 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Tue, 19 Nov 2013 10:08:04 -0800 Subject: [PATCH 06/18] Updated doclets Remaining creation options - still need descriptions on some. Started event descriptions. Viewer constructor parameters fixed. --- src/button.js | 18 +++++ src/eventsource.js | 2 +- src/openseadragon.js | 166 ++++++++++++++++++++++++++++++------------- src/viewer.js | 35 +++++---- 4 files changed, 158 insertions(+), 63 deletions(-) diff --git a/src/button.js b/src/button.js index 527c4927..71aaff61 100644 --- a/src/button.js +++ b/src/button.js @@ -181,6 +181,8 @@ $.Button = function( options ) { if ( event.insideElementPressed ) { inTo( _this, $.ButtonState.DOWN ); /** + * Raised when the cursor enters the Button element. + * * @event enter * @memberof OpenSeadragon.Button * @type {object} @@ -197,6 +199,8 @@ $.Button = function( options ) { focusHandler: function ( event ) { this.enterHandler( event ); /** + * Raised when the Button element receives focus. + * * @event focus * @memberof OpenSeadragon.Button * @type {object} @@ -211,6 +215,8 @@ $.Button = function( options ) { outTo( _this, $.ButtonState.GROUP ); if ( event.insideElementPressed ) { /** + * Raised when the cursor leaves the Button element. + * * @event exit * @memberof OpenSeadragon.Button * @type {object} @@ -225,6 +231,8 @@ $.Button = function( options ) { blurHandler: function ( event ) { this.exitHandler( event ); /** + * Raised when the Button element loses focus. + * * @event blur * @memberof OpenSeadragon.Button * @type {object} @@ -238,6 +246,8 @@ $.Button = function( options ) { pressHandler: function ( event ) { inTo( _this, $.ButtonState.DOWN ); /** + * Raised when a mouse button is pressed or touch occurs in the Button element. + * * @event press * @memberof OpenSeadragon.Button * @type {object} @@ -252,6 +262,8 @@ $.Button = function( options ) { if ( event.insideElementPressed && event.insideElementReleased ) { outTo( _this, $.ButtonState.HOVER ); /** + * Raised when the mouse button is released or touch ends in the Button element. + * * @event release * @memberof OpenSeadragon.Button * @type {object} @@ -270,6 +282,8 @@ $.Button = function( options ) { clickHandler: function( event ) { if ( event.quick ) { /** + * Raised when a mouse button is pressed and released or touch is initiated end ended in the Button element within the time and distance threshold. + * * @event click * @memberof OpenSeadragon.Button * @type {object} @@ -285,6 +299,8 @@ $.Button = function( options ) { //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode); if( 13 === event.keyCode ){ /*** + * Raised when a mouse button is pressed and released or touch is initiated end ended in the Button element within the time and distance threshold. + * * @event click * @memberof OpenSeadragon.Button * @type {object} @@ -294,6 +310,8 @@ $.Button = function( options ) { */ _this.raiseEvent( "click", { originalEvent: event.originalEvent } ); /*** + * Raised when the mouse button is released or touch ends in the Button element. + * * @event release * @memberof OpenSeadragon.Button * @type {object} diff --git a/src/eventsource.js b/src/eventsource.js index 16abb4b8..0f911af3 100644 --- a/src/eventsource.js +++ b/src/eventsource.js @@ -39,7 +39,7 @@ * * @callback EventHandler * @memberof OpenSeadragon - * @param {Object} event - See individual events for event properties passed. + * @param {Object} event - See individual events for event-specific properties. */ diff --git a/src/openseadragon.js b/src/openseadragon.js index 6796955b..7f763da2 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -82,27 +82,34 @@ */ +/** + * @version <%= pkg.name %> <%= pkg.version %> + * + * @file + * **OpenSeadragon - Javascript Deep Zooming** + * + * OpenSeadragon is provides an html interface for creating + * deep zoom user interfaces. The simplest examples include deep + * zoom for large resolution images, and complex examples include + * zoomable map interfaces driven by SVG files. + * + */ - /** - * @version <%= pkg.name %> <%= pkg.version %> - * - * @fileOverview - *

- * - * OpenSeadragon - Javascript Deep Zooming - * - *

- *

- * OpenSeadragon is provides an html interface for creating - * deep zoom user interfaces. The simplest examples include deep - * zoom for large resolution images, and complex examples include - * zoomable map interfaces driven by SVG files. - *

- */ +/** + * @module OpenSeadragon + * + */ - /** - * @module OpenSeadragon - */ +/** + * The root namespace for OpenSeadragon. All utility methods + * and classes are defined on or below this namespace. + * + * @namespace OpenSeadragon + * + */ + + +// Typedefs /** * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer. @@ -110,10 +117,6 @@ * @typedef {Object} Options * @memberof OpenSeadragon * - * @property {String} [xmlPath=null] - * DEPRECATED. A relative path to load a DZI file from the server. - * Prefer the newer Options.tileSources. - * * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null] * As an Array, the tileSource can hold either be all Objects or mixed * types of Arrays of Objects, String, Function. When a value is a String, @@ -124,6 +127,25 @@ * is an Array of objects, it is used to create a * {@link OpenSeadragon.LegacyTileSource}. * + * @property {String} [xmlPath=null] + * **DEPRECATED**. A relative path to load a DZI file from the server. + * Prefer the newer Options.tileSources. + * + * @property {String} [prefixUrl='/images/'] + * Prepends the prefixUrl to navImages paths, which is very useful + * since the default paths are rarely useful for production + * environments. + * + * @property {OpenSeadragon.NavImages} [navImages] + * An object with a property for each button or other built-in navigation + * control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'. + * Each of those in turn provides an image path for each state of the botton + * or navigation control, eg 'REST', 'GROUP', 'HOVER', 'PRESS'. Finally the + * image paths, by default assume there is a folder on the servers root path + * called '/images', eg '/images/zoomin_rest.png'. If you need to adjust + * these paths, prefer setting the option.prefixUrl rather than overriding + * every image path directly through this setting. + * * @property {Object} [tileHost=null] * TODO: Implement this. Currently not used. * @@ -276,6 +298,11 @@ * interactions include draging the image in a plane, and zooming in toward * and away from the image. * + * @property {Boolean} [navPrevNextWrap=false] + * If the 'previous' button will wrap to the last image when viewing the first + * image and if the 'next' button will wrap to the first image when viewing + * the last image. + * * @property {Boolean} [showSequenceControl=true] * If the viewer has been configured with a sequence of tile sources, then * provide buttons for navigating forward and backward through the images. @@ -289,35 +316,84 @@ * position. If preserveViewport is set to true, then the viewport position * is preserved when navigating between images in the sequence. * - * @property {String} [prefixUrl='/images/'] - * Prepends the prefixUrl to navImages paths, which is very useful - * since the default paths are rarely useful for production - * environments. + * @property {Boolean} [showReferenceStrip=false] + * If the viewer has been configured with a sequence of tile sources, then + * display a scrolling strip of image thumbnails for navigating through the images. * - * @property {Object} [navImages=] - * An object with a property for each button or other built-in navigation - * control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'. - * Each of those in turn provides an image path for each state of the botton - * or navigation control, eg 'REST', 'GROUP', 'HOVER', 'PRESS'. Finally the - * image paths, by default assume there is a folder on the servers root path - * called '/images', eg '/images/zoomin_rest.png'. If you need to adjust - * these paths, prefer setting the option.prefixUrl rather than overriding - * every image path directly through this setting. + * @property {String} [referenceStripScroll='horizontal'] * - * @property {Boolean} [navPrevNextWrap=false] - * If the 'previous' button will wrap to the last image when viewing the first - * image and if the 'next' button will wrap to the first image when viewing - * the last image. + * @property {Element} [referenceStripElement=null] + * + * @property {Number} [referenceStripHeight=null] + * + * @property {Number} [referenceStripWidth=null] + * + * @property {String} [referenceStripPosition='BOTTOM_LEFT'] + * + * @property {Number} [referenceStripSizeRatio=0.2] + * + * @property {Boolean} [collectionMode=false] + * + * @property {Number} [collectionRows=3] + * + * @property {String} [collectionLayout='horizontal'] + * + * @property {Number} [collectionTileSize=800] * */ +/** + * The names for the image resources used for the image navigation buttons. + * + * @typedef {Object} NavImages + * @memberof OpenSeadragon + * + * @property {Object} zoomIn - Images for the zoom-in button. + * @property {String} zoomIn.REST + * @property {String} zoomIn.GROUP + * @property {String} zoomIn.HOVER + * @property {String} zoomIn.DOWN + * + * @property {Object} zoomOut - Images for the zoom-out button. + * @property {String} zoomOut.REST + * @property {String} zoomOut.GROUP + * @property {String} zoomOut.HOVER + * @property {String} zoomOut.DOWN + * + * @property {Object} home - Images for the home button. + * @property {String} home.REST + * @property {String} home.GROUP + * @property {String} home.HOVER + * @property {String} home.DOWN + * + * @property {Object} fullpage - Images for the full-page button. + * @property {String} fullpage.REST + * @property {String} fullpage.GROUP + * @property {String} fullpage.HOVER + * @property {String} fullpage.DOWN + * + * @property {Object} previous - Images for the previous button. + * @property {String} previous.REST + * @property {String} previous.GROUP + * @property {String} previous.HOVER + * @property {String} previous.DOWN + * + * @property {Object} next - Images for the next button. + * @property {String} next.REST + * @property {String} next.GROUP + * @property {String} next.HOVER + * @property {String} next.DOWN + * + */ + + /** * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all * combinations of out-of-the-box configurable features. * * @function OpenSeadragon * @memberof module:OpenSeadragon - * @param {OpenSeadragon.Options} options + * @param {OpenSeadragon.Options} options - Viewer options. * @returns {OpenSeadragon.Viewer} */ window.OpenSeadragon = window.OpenSeadragon || function( options ){ @@ -327,14 +403,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; -/** - * The root namespace for OpenSeadragon. All utility methods - * and classes are defined on or below this namespace. - * - * @namespace OpenSeadragon - */ - - (function( $ ){ diff --git a/src/viewer.js b/src/viewer.js index eecfd1a6..8d4e3fdc 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -54,17 +54,13 @@ var THIS = {}, * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock - * @param {OpenSeadragon.Options} options - * @param {String} options.element Id of Element to attach to, - * @param {String} options.xmlPath Xpath ( TODO: not sure! ), - * @param {String} options.prefixUrl Url used to prepend to paths, eg button - * images, etc. - * @param {OpenSeadragon.Control[]} options.controls Array of OpenSeadragon.Control, - * @param {OpenSeadragon.Overlay[]} options.overlays Array of OpenSeadragon.Overlay, - * @param {OpenSeadragon.Control[]} options.overlayControls An Array of ( TODO: - * not sure! ) - * @property {OpenSeadragon.Viewport} viewport The viewer's viewport, where you - * can access zoom, pan, etc. + * @param {OpenSeadragon.Options} [options] - Viewer options. If an {@link OpenSeadragon.Options} object is passed first, all other parameters are ignored. This is the preferred method of creating a viewer. + * @param {String} element - Id of Element to attach to, + * @param {String} xmlPath - Xpath ( TODO: not sure! ), + * @param {String} prefixUrl - Url used to prepend to paths, eg button images, etc. + * @param {OpenSeadragon.Control[]} controls - Array of OpenSeadragon.Control, + * @param {OpenSeadragon.Overlay[]} overlays - Array of OpenSeadragon.Overlay, + * @param {OpenSeadragon.Control[]} overlayControls - An Array of ( TODO: not sure! ) * **/ $.Viewer = function( options ) { @@ -126,13 +122,26 @@ $.Viewer = function( options ) { //These are originally not part options but declared as members //in initialize. Its still considered idiomatic to put them here source: null, + /** + * @member {OpenSeadragon.Drawer} drawer + * @memberof OpenSeadragon.Viewer# + */ drawer: null, drawers: [], + /** + * The viewer's viewport, where you can access zoom, pan, etc. + * @member {OpenSeadragon.Viewport} viewport + * @memberof OpenSeadragon.Viewer# + */ viewport: null, + /** + * @member {OpenSeadragon.Navigator} navigator + * @memberof OpenSeadragon.Viewer# + */ navigator: null, - //A collection viewport is a seperate viewport used to provide - //simultanious rendering of sets of tiless + //A collection viewport is a separate viewport used to provide + //simultanious rendering of sets of tiles collectionViewport: null, collectionDrawer: null, From f23395b60e4fc508505eba17ba0b7938949171d2 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Tue, 19 Nov 2013 11:20:45 -0800 Subject: [PATCH 07/18] Updated doclets Misc changes. Committing to merge upstream changes. --- src/button.js | 4 ++-- src/openseadragon.js | 8 ++++---- src/viewer.js | 12 +++--------- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/src/button.js b/src/button.js index 71aaff61..b25a7534 100644 --- a/src/button.js +++ b/src/button.js @@ -282,7 +282,7 @@ $.Button = function( options ) { clickHandler: function( event ) { if ( event.quick ) { /** - * Raised when a mouse button is pressed and released or touch is initiated end ended in the Button element within the time and distance threshold. + * Raised when a mouse button is pressed and released or touch is initiated and ended in the Button element within the time and distance threshold. * * @event click * @memberof OpenSeadragon.Button @@ -299,7 +299,7 @@ $.Button = function( options ) { //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode); if( 13 === event.keyCode ){ /*** - * Raised when a mouse button is pressed and released or touch is initiated end ended in the Button element within the time and distance threshold. + * Raised when a mouse button is pressed and released or touch is initiated and ended in the Button element within the time and distance threshold. * * @event click * @memberof OpenSeadragon.Button diff --git a/src/openseadragon.js b/src/openseadragon.js index 7f763da2..9dc40535 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -118,8 +118,8 @@ * @memberof OpenSeadragon * * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null] - * As an Array, the tileSource can hold either be all Objects or mixed - * types of Arrays of Objects, String, Function. When a value is a String, + * As an Array, the tileSource can hold either Objects or mixed + * types of Arrays of Objects, Strings, or Functions. When a value is a String, * the tileSource is used to create a {@link OpenSeadragon.DziTileSource}. * When a value is a Function, the function is used to create a new * {@link OpenSeadragon.TileSource} whose abstract method @@ -241,10 +241,10 @@ * point is less than this many pixels, ignore the drag event. * * @property {Number} [zoomPerClick=2.0] - * The "zoom distance" per mouse click or touch tap. + * The "zoom distance" per mouse click or touch tap. **Note:** Setting this to 1.0 effectively disables the click-to-zoom feature. * * @property {Number} [zoomPerScroll=1.2] - * The "zoom distance" per mouse scroll or touch pinch. + * The "zoom distance" per mouse scroll or touch pinch. **Note:** Setting this to 1.0 effectively disables the mouse-wheel zoom feature. * * @property {Number} [zoomPerSecond=1.0] * The number of seconds to animate a single zoom event over. diff --git a/src/viewer.js b/src/viewer.js index 8d4e3fdc..a7a91b87 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -54,13 +54,7 @@ var THIS = {}, * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock - * @param {OpenSeadragon.Options} [options] - Viewer options. If an {@link OpenSeadragon.Options} object is passed first, all other parameters are ignored. This is the preferred method of creating a viewer. - * @param {String} element - Id of Element to attach to, - * @param {String} xmlPath - Xpath ( TODO: not sure! ), - * @param {String} prefixUrl - Url used to prepend to paths, eg button images, etc. - * @param {OpenSeadragon.Control[]} controls - Array of OpenSeadragon.Control, - * @param {OpenSeadragon.Overlay[]} overlays - Array of OpenSeadragon.Overlay, - * @param {OpenSeadragon.Control[]} overlayControls - An Array of ( TODO: not sure! ) + * @param {OpenSeadragon.Options} options - Viewer options. * **/ $.Viewer = function( options ) { @@ -120,7 +114,7 @@ $.Viewer = function( options ) { customControls: [], //These are originally not part options but declared as members - //in initialize. Its still considered idiomatic to put them here + //in initialize. It's still considered idiomatic to put them here source: null, /** * @member {OpenSeadragon.Drawer} drawer @@ -141,7 +135,7 @@ $.Viewer = function( options ) { navigator: null, //A collection viewport is a separate viewport used to provide - //simultanious rendering of sets of tiles + //simultaneous rendering of sets of tiles collectionViewport: null, collectionDrawer: null, From ece76925a691bfec8702bf9f3542b5ff1ab93d26 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Thu, 21 Nov 2013 12:19:07 -0800 Subject: [PATCH 08/18] Updated Doclets Lots of changes, most notably event documentation (@event and @fires) --- src/button.js | 7 +++++- src/drawer.js | 28 ++++++++++++++++++--- src/fullscreen.js | 18 ++++++++++---- src/openseadragon.js | 28 +++++++++++++-------- src/overlay.js | 14 ++++++++--- src/tilesource.js | 6 +++++ src/viewer.js | 59 +++++++++++++++++++++++++++++++++++++++++--- src/viewport.js | 19 ++++++++++++++ 8 files changed, 153 insertions(+), 26 deletions(-) diff --git a/src/button.js b/src/button.js index b25a7534..306e6f75 100644 --- a/src/button.js +++ b/src/button.js @@ -35,10 +35,15 @@ (function( $ ){ /** - * An enumeration of button states including, REST, GROUP, HOVER, and DOWN + * An enumeration of button states * @member ButtonState * @memberof OpenSeadragon * @static + * @type {Object} + * @property {Number} REST + * @property {Number} GROUP + * @property {Number} HOVER + * @property {Number} DOWN */ $.ButtonState = { REST: 0, diff --git a/src/drawer.js b/src/drawer.js index 5999d18e..cb7d58b1 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -171,6 +171,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @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 */ addOverlay: function( element, location, placement, onDraw ) { var options; @@ -201,11 +202,13 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ this.updateAgain = true; if( this.viewer ){ /** + * Raised when an overlay is added to the viewer (see {@link OpenSeadragon.Drawer#addOverlay}). + * * @event add-overlay * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Element} element + * @property {Element} element - The overlay element. * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location * @property {OpenSeadragon.OverlayPlacement} placement * @property {?Object} userData - Arbitrary subscriber-defined object. @@ -229,6 +232,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * viewport which the location coordinates will be treated as relative * to. * @return {OpenSeadragon.Drawer} Chainable. + * @fires OpenSeadragon.Viewer.event:update-overlay */ updateOverlay: function( element, location, placement ) { var i; @@ -242,6 +246,8 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } if( this.viewer ){ /** + * Raised when an overlay's location or placement changes (see {@link OpenSeadragon.Drawer#updateOverlay}). + * * @event update-overlay * @memberof OpenSeadragon.Viewer * @type {object} @@ -267,6 +273,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * @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 */ removeOverlay: function( element ) { var i; @@ -281,11 +288,13 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } if( this.viewer ){ /** + * Raised when an overlay is removed from the viewer (see {@link OpenSeadragon.Drawer#removeOverlay}). + * * @event remove-overlay * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Element} element + * @property {Element} element - The overlay element. * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent( 'remove-overlay', { @@ -300,6 +309,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ * and update. * @method * @return {OpenSeadragon.Drawer} Chainable. + * @fires OpenSeadragon.Viewer.event:clear-overlay */ clearOverlays: function() { while ( this.overlays.length > 0 ) { @@ -308,6 +318,8 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ } if( this.viewer ){ /** + * Raised when all overlays are removed from the viewer (see {@link OpenSeadragon.Drawer#clearOverlays}). + * * @event clear-overlay * @memberof OpenSeadragon.Viewer * @type {object} @@ -508,6 +520,8 @@ function updateViewport( drawer ) { if( drawer.viewer ){ /** + * - Needs documentation - + * * @event update-viewport * @memberof OpenSeadragon.Viewer * @type {object} @@ -689,6 +703,8 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi if( drawer.viewer ){ /** + * - Needs documentation - + * * @event update-level * @memberof OpenSeadragon.Viewer * @type {object} @@ -767,11 +783,13 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le if( drawer.viewer ){ /** + * - Needs documentation - + * * @event update-tile * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} tile + * @property {OpenSeadragon.Tile} tile * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'update-tile', { @@ -1289,11 +1307,13 @@ function drawTiles( drawer, lastDrawn ){ if( drawer.viewer ){ /** + * - Needs documentation - + * * @event tile-drawn * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. - * @property {Object} tile + * @property {OpenSeadragon.Tile} tile * @property {?Object} userData - Arbitrary subscriber-defined object. */ drawer.viewer.raiseEvent( 'tile-drawn', { diff --git a/src/fullscreen.js b/src/fullscreen.js index 2935923f..dedbd290 100644 --- a/src/fullscreen.js +++ b/src/fullscreen.js @@ -60,12 +60,20 @@ */ -/** - * Determines the appropriate level of native full screen support we can get - * from the browser. - * @name $.supportsFullScreen - */ (function( $ ) { + /** + * Determined native full screen support we can get from the browser. + * @member fullScreenApi + * @memberof OpenSeadragon + * @type {object} + * @property {Boolean} supportsFullScreen + * @property {Function} isFullScreen + * @property {Function} requestFullScreen + * @property {Function} cancelFullScreen + * @property {String} fullScreenEventName + * @property {String} fullScreenErrorEventName + * @property {String} prefix + */ var fullScreenApi = { supportsFullScreen: false, isFullScreen: function() { return false; }, diff --git a/src/openseadragon.js b/src/openseadragon.js index 692417e1..f8da3fc6 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -86,12 +86,13 @@ * @version <%= pkg.name %> <%= pkg.version %> * * @file - * **OpenSeadragon - Javascript Deep Zooming** - * - * OpenSeadragon is provides an html interface for creating + *

OpenSeadragon - Javascript Deep Zooming

+ *

+ * OpenSeadragon provides an html interface for creating * deep zoom user interfaces. The simplest examples include deep * zoom for large resolution images, and complex examples include * zoomable map interfaces driven by SVG files. + *

* */ @@ -128,7 +129,7 @@ * {@link OpenSeadragon.LegacyTileSource}. * * @property {String} [xmlPath=null] - * **DEPRECATED**. A relative path to load a DZI file from the server. + * DEPRECATED. A relative path to load a DZI file from the server. * Prefer the newer Options.tileSources. * * @property {String} [prefixUrl='/images/'] @@ -241,10 +242,10 @@ * point is less than this many pixels, ignore the drag event. * * @property {Number} [zoomPerClick=2.0] - * The "zoom distance" per mouse click or touch tap. **Note:** Setting this to 1.0 effectively disables the click-to-zoom feature. + * The "zoom distance" per mouse click or touch tap. Note: Setting this to 1.0 effectively disables the click-to-zoom feature. * * @property {Number} [zoomPerScroll=1.2] - * The "zoom distance" per mouse scroll or touch pinch. **Note:** Setting this to 1.0 effectively disables the mouse-wheel zoom feature. + * The "zoom distance" per mouse scroll or touch pinch. Note: Setting this to 1.0 effectively disables the mouse-wheel zoom feature. * * @property {Number} [zoomPerSecond=1.0] * The number of seconds to animate a single zoom event over. @@ -763,7 +764,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * Invokes the the method as if it where a method belonging to the object. + * Invokes the method as if it where a method belonging to the object. * @function * @param {Object} object * @param {Function} method @@ -780,9 +781,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * An enumeration of Browser vendors including UNKNOWN, IE, FIREFOX, - * SAFARI, CHROME, and OPERA. + * An enumeration of Browser vendors. * @static + * @type {Object} + * @property {Number} UNKNOWN + * @property {Number} IE + * @property {Number} FIREFOX + * @property {Number} SAFARI + * @property {Number} CHROME + * @property {Number} OPERA */ BROWSERS: { UNKNOWN: 0, @@ -919,6 +926,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * @function * @param {Event} [event] * @returns {Event} + * @deprecated For internal use only */ getEvent: function( event ) { if( event ){ @@ -1647,7 +1655,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Fully deprecated. Will throw an error. * @function - * @deprecated - use OpenSeadragon.Viewer.prototype.open + * @deprecated use {@link OpenSeadragon.Viewer#open} */ createFromDZI: function() { throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open."; diff --git a/src/overlay.js b/src/overlay.js index 109f34c5..1cc615f5 100644 --- a/src/overlay.js +++ b/src/overlay.js @@ -35,12 +35,20 @@ (function( $ ){ /** - * An enumeration of positions that an overlay may be assigned relative - * to the viewport including CENTER, TOP_LEFT (default), TOP, TOP_RIGHT, - * RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT. + * An enumeration of positions that an overlay may be assigned relative to the viewport. * @member OverlayPlacement * @memberof OpenSeadragon * @static + * @type {Object} + * @property {Number} CENTER + * @property {Number} TOP_LEFT + * @property {Number} TOP + * @property {Number} TOP_RIGHT + * @property {Number} RIGHT + * @property {Number} BOTTOM_RIGHT + * @property {Number} BOTTOM + * @property {Number} BOTTOM_LEFT + * @property {Number} LEFT */ $.OverlayPlacement = { CENTER: 0, diff --git a/src/tilesource.js b/src/tilesource.js index adadf97f..63da063d 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -299,6 +299,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ var $TileSource = $.TileSource.determineType( _this, data, url ); if ( !$TileSource ) { /** + * Raised when an error occurs loading a TileSource. + * * @event open-failed * @memberof OpenSeadragon.TileSource * @type {object} @@ -315,6 +317,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ readySource = new $TileSource( options ); _this.ready = true; /** + * Raised when a TileSource is opened and initialized. + * * @event ready * @memberof OpenSeadragon.TileSource * @type {object} @@ -363,6 +367,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ } /*** + * Raised when an error occurs loading a TileSource. + * * @event open-failed * @memberof OpenSeadragon.TileSource * @type {object} diff --git a/src/viewer.js b/src/viewer.js index 6384f5a3..1d45135d 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -406,7 +406,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @param {String} dzi xml string or the url to a DZI xml document. * @return {OpenSeadragon.Viewer} Chainable. * - * @deprecated - use 'open' instead. + * @deprecated - use {@link OpenSeadragon.Viewer#open} instead. */ openDzi: function ( dzi ) { return this.open( dzi ); @@ -420,7 +420,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @param {String|Object|Function} See OpenSeadragon.Viewer.prototype.open * @return {OpenSeadragon.Viewer} Chainable. * - * @deprecated - use 'open' instead. + * @deprecated - use {@link OpenSeadragon.Viewer#open} instead. */ openTileSource: function ( tileSource ) { return this.open( tileSource ); @@ -445,6 +445,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @name OpenSeadragon.Viewer.prototype.open * @param {String|Object|Function} * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:open + * @fires OpenSeadragon.Viewer.event:open-failed */ open: function ( tileSource ) { var _this = this, @@ -473,6 +475,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, }); tileSource.addHandler( 'open-failed', function ( event ) { /** + * Raised when an error occurs loading a TileSource. + * * @event open-failed * @memberof OpenSeadragon.Viewer * @type {object} @@ -495,6 +499,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, $TileSource = $.TileSource.determineType( _this, tileSource ); if ( !$TileSource ) { /*** + * Raised when an error occurs loading a TileSource. + * * @event open-failed * @memberof OpenSeadragon.Viewer * @type {object} @@ -527,6 +533,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @function * @name OpenSeadragon.Viewer.prototype.close * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:close */ close: function ( ) { if ( this._updateRequestId !== null ) { @@ -555,6 +562,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, delete VIEWERS[ this.hash ]; /** + * Raised when the viewer is closed (see {@link OpenSeadragon.Viewer#close}). + * * @event close * @memberof OpenSeadragon.Viewer * @type {object} @@ -622,10 +631,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled * @param {Boolean} enabled - true to enable, false to disable * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:mouse-enabled */ setMouseNavEnabled: function( enabled ){ this.innerTracker.setTracking( enabled ); /** + * Raised when mouse/touch navigation is enabled or disabled (see {@link OpenSeadragon.Viewer#setMouseNavEnabled}). + * * @event mouse-enabled * @memberof OpenSeadragon.Viewer * @type {object} @@ -660,6 +672,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @name OpenSeadragon.Viewer.prototype.setControlsEnabled * @param {Boolean} true to show, false to hide. * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:controls-enabled */ setControlsEnabled: function( enabled ) { if( enabled ){ @@ -668,6 +681,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, beginControlsAutoHide( this ); } /** + * Raised when the navigation controls are shown or hidden (see {@link OpenSeadragon.Viewer#setControlsEnabled}). + * * @event controls-enabled * @memberof OpenSeadragon.Viewer * @type {object} @@ -697,6 +712,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @param {Boolean} fullPage * If true, enter full page mode. If false, exit full page mode. * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:pre-full-page + * @fires OpenSeadragon.Viewer.event:full-page */ setFullPage: function( fullPage ) { @@ -718,6 +735,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, preventDefaultAction: false }; /** + * Raised when the viewer is about to change to/from full-page mode (see {@link OpenSeadragon.Viewer#setFullPage}). + * * @event pre-full-page * @memberof OpenSeadragon.Viewer * @type {object} @@ -872,6 +891,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } /** + * Raised when the viewer has changed to/from full-page mode (see {@link OpenSeadragon.Viewer#setFullPage}). + * * @event full-page * @memberof OpenSeadragon.Viewer * @type {object} @@ -891,6 +912,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @param {Boolean} fullScreen * If true, enter full screen mode. If false, exit full screen mode. * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:pre-full-screen + * @fires OpenSeadragon.Viewer.event:full-screen */ setFullScreen: function( fullScreen ) { var _this = this; @@ -908,6 +931,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, preventDefaultAction: false }; /** + * Raised when the viewer is about to change to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}). + * * @event pre-full-screen * @memberof OpenSeadragon.Viewer * @type {object} @@ -948,6 +973,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } } /** + * Raised when the viewer has changed to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}). + * * @event full-screen * @memberof OpenSeadragon.Viewer * @type {object} @@ -983,10 +1010,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @name OpenSeadragon.Viewer.prototype.setVisible * @param {Boolean} visible * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:visible */ setVisible: function( visible ){ this.container.style.visibility = visible ? "" : "hidden"; /** + * Raised when the viewer is shown or hidden (see {@link OpenSeadragon.Viewer#setVisible}). + * * @event visible * @memberof OpenSeadragon.Viewer * @type {object} @@ -1221,11 +1251,12 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @function * @name OpenSeadragon.Viewer.prototype.goToPage * @return {OpenSeadragon.Viewer} Chainable. + * @fires OpenSeadragon.Viewer.event:page */ goToPage: function( page ){ if( page >= 0 && page < this.tileSources.length ){ /** - * Raised when the page is changed on a viewer configured with multiple image sources. + * Raised when the page is changed on a viewer configured with multiple image sources (see {@link OpenSeadragon.Viewer#goToPage}). * * @event page * @memberof OpenSeadragon.Viewer @@ -1497,6 +1528,8 @@ function openTileSource( viewer, source ) { VIEWERS[ _this.hash ] = _this; /** + * Raised when the viewer has opened and loaded one or more TileSources. + * * @event open * @memberof OpenSeadragon.Viewer * @type {object} @@ -1610,6 +1643,8 @@ function onCanvasClick( event ) { this.viewport.applyConstraints(); } /** + * Raised when a mouse press/release or touch/remove occurs on the viewer. + * * @event canvas-click * @memberof OpenSeadragon.Viewer * @type {object} @@ -1648,6 +1683,8 @@ function onCanvasDrag( event ) { } } /** + * Raised when a mouse or touch drag operation occurs in the viewer. + * * @event canvas-drag * @memberof OpenSeadragon.Viewer * @type {object} @@ -1673,6 +1710,8 @@ function onCanvasRelease( event ) { this.viewport.applyConstraints(); } /** + * Raised when the mouse button is released or touch ends in the viewer. + * * @event canvas-release * @memberof OpenSeadragon.Viewer * @type {object} @@ -1704,6 +1743,8 @@ function onCanvasScroll( event ) { this.viewport.applyConstraints(); } /** + * Raised when a scroll event occurs in the viewer (mouse wheel, touch pinch, etc.). + * * @event canvas-scroll * @memberof OpenSeadragon.Viewer * @type {object} @@ -1734,6 +1775,8 @@ function onContainerExit( event ) { } } /** + * Raised when the cursor leaves the viewer element. + * * @event container-exit * @memberof OpenSeadragon.Viewer * @type {object} @@ -1762,6 +1805,8 @@ function onContainerRelease( event ) { } } /** + * Raised when the mouse button is released or touch ends in the viewer. + * * @event container-release * @memberof OpenSeadragon.Viewer * @type {object} @@ -1786,6 +1831,8 @@ function onContainerEnter( event ) { THIS[ this.hash ].mouseInside = true; abortControlsAutoHide( this ); /** + * Raised when the cursor enters the viewer element. + * * @event container-enter * @memberof OpenSeadragon.Viewer * @type {object} @@ -1854,6 +1901,8 @@ function updateOnce( viewer ) { if ( !THIS[ viewer.hash ].animating && animated ) { /** + * Raised when any spring animation starts (zoom, pan, etc.). + * * @event animation-start * @memberof OpenSeadragon.Viewer * @type {object} @@ -1870,6 +1919,8 @@ function updateOnce( viewer ) { viewer.navigator.update( viewer.viewport ); } /** + * Raised when any spring animation update occurs (zoom, pan, etc.). + * * @event animation * @memberof OpenSeadragon.Viewer * @type {object} @@ -1887,6 +1938,8 @@ function updateOnce( viewer ) { if ( THIS[ viewer.hash ].animating && !animated ) { /** + * Raised when any spring animation ends (zoom, pan, etc.). + * * @event animation-finish * @memberof OpenSeadragon.Viewer * @type {object} diff --git a/src/viewport.js b/src/viewport.js index 3c48e1c5..013ee02c 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -111,6 +111,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:reset-size */ resetContentSize: function( contentSize ){ this.contentSize = contentSize; @@ -123,6 +124,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** + * Raised when the viewer's content size is reset (see {@link OpenSeadragon.Viewport#resetContentSize}). + * * @event reset-size * @memberof OpenSeadragon.Viewer * @type {object} @@ -173,10 +176,13 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @param {Boolean} immediately + * @fires OpenSeadragon.Viewer.event:home */ goHome: function( immediately ) { if( this.viewer ){ /** + * Raised when the "home" operation occurs (see {@link OpenSeadragon.Viewport#goHome}). + * * @event home * @memberof OpenSeadragon.Viewer * @type {object} @@ -314,6 +320,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:constrain */ applyConstraints: function( immediately ) { var actualZoom = this.getZoom(), @@ -385,6 +392,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** + * Raised when the viewport constraints are applied (see {@link OpenSeadragon.Viewport#applyConstraints}). + * * @event constrain * @memberof OpenSeadragon.Viewer * @type {object} @@ -532,6 +541,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @param {OpenSeadragon.Point} center * @param {Boolean} immediately * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:pan */ panTo: function( center, immediately ) { if ( immediately ) { @@ -544,6 +554,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** + * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panTo}). + * * @event pan * @memberof OpenSeadragon.Viewer * @type {object} @@ -564,6 +576,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:zoom */ zoomBy: function( factor, refPoint, immediately ) { if( refPoint instanceof $.Point && !isNaN( refPoint.x ) && !isNaN( refPoint.y ) ) { @@ -578,6 +591,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:zoom */ zoomTo: function( zoom, refPoint, immediately ) { @@ -595,6 +609,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** + * Raised when the viewport zoom level changes (see {@link OpenSeadragon.Viewport#zoomBy} and {@link OpenSeadragon.Viewport#zoomTo}). + * * @event zoom * @memberof OpenSeadragon.Viewer * @type {object} @@ -649,6 +665,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:resize */ resize: function( newContainerSize, maintain ) { var oldBounds = this.getBounds(), @@ -667,6 +684,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** + * Raised when the viewer is resized (see {@link OpenSeadragon.Viewport#resize}). + * * @event resize * @memberof OpenSeadragon.Viewer * @type {object} From 7f60184b9a8e8cd536a9c97a4fe47ed185c6eb3a Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Thu, 21 Nov 2013 19:43:45 -0800 Subject: [PATCH 09/18] Updated Doclets Found another @fires --- src/viewport.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/viewport.js b/src/viewport.js index 013ee02c..b6744f21 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -526,6 +526,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ * @param {OpenSeadragon.Point} delta * @param {Boolean} immediately * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:pan */ panBy: function( delta, immediately ) { var center = new $.Point( @@ -554,7 +555,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ if( this.viewer ){ /** - * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panTo}). + * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panBy} and {@link OpenSeadragon.Viewport#panTo}). * * @event pan * @memberof OpenSeadragon.Viewer From cb765afea2521f7820b0e2ca912b03becafc70cd Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Sat, 23 Nov 2013 10:39:37 -0800 Subject: [PATCH 10/18] Added an OpenSeadragon.version property --- changelog.txt | 1 + package.json | 2 +- src/openseadragon.js | 24 ++++++++++++++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/changelog.txt b/changelog.txt index 01a3900f..c72b2cea 100644 --- a/changelog.txt +++ b/changelog.txt @@ -56,6 +56,7 @@ OPENSEADRAGON CHANGELOG * Viewer.innerTracker.scrollHandler: preventDefaultAction == true prevents viewer zooming on mousewheel/pinch * Fixed: IE8 error with custom buttons - "Object doesn't support this action" (#279) * Support IIIF servers that don't report tile dimensions (#286) +* Added a static 'version' property to OpenSeadragon. Useful for plugins that require specific OpenSeadragon versions. 0.9.131: diff --git a/package.json b/package.json index 63c432b9..9c53ceb0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "OpenSeadragon", - "version": "0.9.131", + "version": "1.0.0", "description": "Provides a smooth, zoomable user interface for HTML/Javascript.", "devDependencies": { "grunt": "~0.4.1", diff --git a/src/openseadragon.js b/src/openseadragon.js index 4a1fb29d..efae6051 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -277,6 +277,30 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ (function( $ ){ + /** + * The OpenSeadragon version. + * + * @member {Object} version + * @memberof OpenSeadragon + * @property {String} versionStr - The version number as a string ('major.minor.revision'). + * @property {Number} major - The major version number. + * @property {Number} minor - The minor version number. + * @property {Number} revision - The revision number. + */ + $.version = (function () { + // The version string ('x.x.x') is filled in by the grunt concat build task + // from the 'version' value in package.json + var versionStr = '<%= pkg.version %>', + versionComponents = versionStr.split( '.' ); + return { + versionStr: versionStr, + major: parseInt( versionComponents[ 0 ] ), + minor: parseInt( versionComponents[ 1 ] ), + revision: parseInt( versionComponents[ 2 ] ) + }; + }()); + + /** * Taken from jquery 1.6.1 * [[Class]] -> type pairs From 930e8c4dfd5213b1e981a12ad1ab8c10b71fa537 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 08:48:44 -0800 Subject: [PATCH 11/18] Updated Doclets --- src/button.js | 74 ++++++++++++++--------- src/buttongroup.js | 43 ++++++++------ src/control.js | 53 ++++++++++++----- src/controldock.js | 2 + src/displayrectangle.js | 17 ++++-- src/drawer.js | 74 +++++++++++++---------- src/eventsource.js | 7 ++- src/iiif1_1tilesource.js | 4 +- src/iiiftilesource.js | 4 +- src/legacytilesource.js | 5 +- src/mousetracker.js | 62 +++++++++++--------- src/navigator.js | 6 +- src/openseadragon.js | 29 +++++---- src/osmtilesource.js | 6 +- src/overlay.js | 18 +++++- src/point.js | 17 ++++-- src/profiler.js | 5 +- src/rectangle.js | 28 +++++++-- src/referencestrip.js | 12 +++- src/spring.js | 37 +++++++++--- src/strings.js | 4 +- src/tile.js | 123 +++++++++++++++++++++++++++++++-------- src/tilesource.js | 53 ++++++++++++----- src/tmstilesource.js | 4 +- src/viewer.js | 65 ++++++++++++--------- src/viewport.js | 3 + 26 files changed, 513 insertions(+), 242 deletions(-) diff --git a/src/button.js b/src/button.js index 306e6f75..5a1e0a30 100644 --- a/src/button.js +++ b/src/button.js @@ -53,39 +53,30 @@ $.ButtonState = { }; /** - * Manages events, hover states for individual buttons, tool-tips, as well + * @class Button + * @classdesc Manages events, hover states for individual buttons, tool-tips, as well * as fading the bottons out when the user has not interacted with them * for a specified period. - * @class Button + * * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Object} options - * @param {String} options.tooltip Provides context help for the button we the + * @param {Element} [options.element=null] Element to use as the button. If not specified, an HTML <button> element is created. + * @param {String} [options.tooltip=null] Provides context help for the button when the * user hovers over it. - * @param {String} options.srcRest URL of image to use in 'rest' state - * @param {String} options.srcGroup URL of image to use in 'up' state - * @param {String} options.srcHover URL of image to use in 'hover' state - * @param {String} options.srcDown URL of image to use in 'down' state - * @param {Element} [options.element] Element to use as a container for the - * button. - * @property {String} tooltip Provides context help for the button we the - * user hovers over it. - * @property {String} srcRest URL of image to use in 'rest' state - * @property {String} srcGroup URL of image to use in 'up' state - * @property {String} srcHover URL of image to use in 'hover' state - * @property {String} srcDown URL of image to use in 'down' state - * @property {Object} config Configurable settings for this button. DEPRECATED. - * @property {Element} [element] Element to use as a container for the - * button. - * @property {Number} fadeDelay How long to wait before fading - * @property {Number} fadeLength How long should it take to fade the button. - * @property {Number} fadeBeginTime When the button last began to fade. - * @property {Boolean} shouldFade Whether this button should fade after user - * stops interacting with the viewport. - this.fadeDelay = 0; // begin fading immediately - this.fadeLength = 2000; // fade over a period of 2 seconds - this.fadeBeginTime = null; - this.shouldFade = false; + * @param {String} [options.srcRest=null] URL of image to use in 'rest' state. + * @param {String} [options.srcGroup=null] URL of image to use in 'up' state. + * @param {String} [options.srcHover=null] URL of image to use in 'hover' state. + * @param {String} [options.srcDown=null] URL of image to use in 'down' state. + * @param {Number} [options.fadeDelay=0] How long to wait before fading. + * @param {Number} [options.fadeLength=2000] How long should it take to fade the button. + * @param {OpenSeadragon.EventHandler} [options.onPress=null] Event handler callback for {@link OpenSeadragon.Button.event:press}. + * @param {OpenSeadragon.EventHandler} [options.onRelease=null] Event handler callback for {@link OpenSeadragon.Button.event:release}. + * @param {OpenSeadragon.EventHandler} [options.onClick=null] Event handler callback for {@link OpenSeadragon.Button.event:click}. + * @param {OpenSeadragon.EventHandler} [options.onEnter=null] Event handler callback for {@link OpenSeadragon.Button.event:enter}. + * @param {OpenSeadragon.EventHandler} [options.onExit=null] Event handler callback for {@link OpenSeadragon.Button.event:exit}. + * @param {OpenSeadragon.EventHandler} [options.onFocus=null] Event handler callback for {@link OpenSeadragon.Button.event:focus}. + * @param {OpenSeadragon.EventHandler} [options.onBlur=null] Event handler callback for {@link OpenSeadragon.Button.event:blur}. */ $.Button = function( options ) { @@ -102,9 +93,17 @@ $.Button = function( options ) { srcDown: null, clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold, clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold, - // begin fading immediately + /** + * How long to wait before fading. + * @member {Number} fadeDelay + * @memberof OpenSeadragon.Button# + */ fadeDelay: 0, - // fade over a period of 2 seconds + /** + * How long should it take to fade the button. + * @member {Number} fadeLength + * @memberof OpenSeadragon.Button# + */ fadeLength: 2000, onPress: null, onRelease: null, @@ -116,6 +115,11 @@ $.Button = function( options ) { }, options ); + /** + * The button element. + * @member {Element} element + * @memberof OpenSeadragon.Button# + */ this.element = options.element || $.makeNeutralElement( "button" ); //if the user has specified the element to bind the control to explicitly @@ -167,15 +171,27 @@ $.Button = function( options ) { this.addHandler( "focus", this.onFocus ); this.addHandler( "blur", this.onBlur ); + /** + * The button's current state. + * @member {OpenSeadragon.ButtonState} currentState + * @memberof OpenSeadragon.Button# + */ this.currentState = $.ButtonState.GROUP; + // When the button last began to fade. this.fadeBeginTime = null; + // Whether this button should fade after user stops interacting with the viewport. this.shouldFade = false; this.element.style.display = "inline-block"; this.element.style.position = "relative"; this.element.title = this.tooltip; + /** + * Tracks mouse/touch/key events on the button. + * @member {OpenSeadragon.MouseTracker} tracker + * @memberof OpenSeadragon.Button# + */ this.tracker = new $.MouseTracker({ element: this.element, diff --git a/src/buttongroup.js b/src/buttongroup.js index 9f1ea2b5..22535571 100644 --- a/src/buttongroup.js +++ b/src/buttongroup.js @@ -34,43 +34,41 @@ (function( $ ){ /** - * Manages events on groups of buttons. * @class ButtonGroup + * @classdesc Manages events on groups of buttons. + * * @memberof OpenSeadragon - * @param {Object} options - a dictionary of settings applied against the entire - * group of buttons - * @param {Array} options.buttons Array of buttons - * @param {Element} [options.group] Element to use as the container, - * @param {Object} options.config Object with Viewer settings ( TODO: is - * this actually used anywhere? ) - * @param {Function} [options.enter] Function callback for when the mouse - * enters group - * @param {Function} [options.exit] Function callback for when mouse leaves - * the group - * @param {Function} [options.release] Function callback for when mouse is - * released - * @property {Array} buttons - An array containing the buttons themselves. - * @property {Element} element - The shared container for the buttons. - * @property {Object} config - Configurable settings for the group of buttons. - * @property {OpenSeadragon.MouseTracker} tracker - Tracks mouse events accross - * the group of buttons. + * @param {Object} options - A dictionary of settings applied against the entire group of buttons. + * @param {Array} options.buttons Array of buttons + * @param {Element} [options.element] Element to use as the container **/ $.ButtonGroup = function( options ) { $.extend( true, this, { + /** + * An array containing the buttons themselves. + * @member {Array} buttons + * @memberof OpenSeadragon.ButtonGroup# + */ buttons: [], clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold, clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold, labelText: "" }, options ); - // copy the botton elements + // copy the button elements TODO: Why? var buttons = this.buttons.concat([]), _this = this, i; + /** + * The shared container for the buttons. + * @member {Element} element + * @memberof OpenSeadragon.ButtonGroup# + */ this.element = options.element || $.makeNeutralElement( "fieldgroup" ); + // TODO What if there IS an options.group specified? if( !options.group ){ this.label = $.makeNeutralElement( "label" ); //TODO: support labels for ButtonGroups @@ -82,6 +80,11 @@ $.ButtonGroup = function( options ) { } } + /** + * Tracks mouse/touch/key events accross the group of buttons. + * @member {OpenSeadragon.MouseTracker} tracker + * @memberof OpenSeadragon.ButtonGroup# + */ this.tracker = new $.MouseTracker({ element: this.element, clickTimeThreshold: this.clickTimeThreshold, @@ -117,6 +120,7 @@ $.ButtonGroup.prototype = /** @lends OpenSeadragon.ButtonGroup.prototype */{ * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function + * @private */ emulateEnter: function() { this.tracker.enterHandler( { eventSource: this.tracker } ); @@ -126,6 +130,7 @@ $.ButtonGroup.prototype = /** @lends OpenSeadragon.ButtonGroup.prototype */{ * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function + * @private */ emulateExit: function() { this.tracker.exitHandler( { eventSource: this.tracker } ); diff --git a/src/control.js b/src/control.js index 3f0565a7..d35776b9 100644 --- a/src/control.js +++ b/src/control.js @@ -35,10 +35,17 @@ (function( $ ){ /** - * An enumeration of supported locations where controls can be anchored, - * including NONE, TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, and BOTTOM_LEFT. - * The anchoring is always relative to the container + * An enumeration of supported locations where controls can be anchored. + * The anchoring is always relative to the container. + * @member ControlAnchor + * @memberof OpenSeadragon * @static + * @type {Object} + * @property {Number} NONE + * @property {Number} TOP_LEFT + * @property {Number} TOP_RIGHT + * @property {Number} BOTTOM_LEFT + * @property {Number} BOTTOM_RIGHT */ $.ControlAnchor = { NONE: 0, @@ -49,10 +56,11 @@ $.ControlAnchor = { }; /** - * A Control represents any interface element which is meant to allow the user + * @class Control + * @classdesc A Control represents any interface element which is meant to allow the user * to interact with the zoomable interface. Any control can be anchored to any * element. - * @class Control + * * @memberof OpenSeadragon * @param {Element} element - the control element to be anchored in the container. * @param {Object } options - All required and optional settings for configuring a control element. @@ -62,16 +70,6 @@ $.ControlAnchor = { * directly to the container * @param {Boolean} [options.autoFade=true] - Whether the control should have the autofade behavior * @param {Element} container - the element to control will be anchored too. - * - * @property {Element} element - the element providing the user interface with - * some type of control. Eg a zoom-in button - * @property {OpenSeadragon.ControlAnchor} anchor - the position of the control - * relative to the container. - * @property {Boolean} autoFade - Whether the control should have the autofade behavior - * @property {Element} container - the element within with the control is - * positioned. - * @property {Element} wrapper - a neutral element surrounding the control - * element. */ $.Control = function ( element, options, container ) { var parent = element.parentNode; @@ -83,10 +81,35 @@ $.Control = function ( element, options, container ) { options = {anchor: options}; } options.attachToViewer = (typeof options.attachToViewer === 'undefined') ? true : options.attachToViewer; + /** + * True if the control should have autofade behavior. + * @member {Boolean} autoFade + * @memberof OpenSeadragon.Control# + */ this.autoFade = (typeof options.autoFade === 'undefined') ? true : options.autoFade; + /** + * The element providing the user interface with some type of control (e.g. a zoom-in button). + * @member {Element} element + * @memberof OpenSeadragon.Control# + */ this.element = element; + /** + * The position of the Control relative to its container. + * @member {OpenSeadragon.ControlAnchor} anchor + * @memberof OpenSeadragon.Control# + */ this.anchor = options.anchor; + /** + * The Control's containing element. + * @member {Element} container + * @memberof OpenSeadragon.Control# + */ this.container = container; + /** + * A neutral element surrounding the control element. + * @member {Element} wrapper + * @memberof OpenSeadragon.Control# + */ this.wrapper = $.makeNeutralElement( "span" ); this.wrapper.style.display = "inline-block"; this.wrapper.appendChild( this.element ); diff --git a/src/controldock.js b/src/controldock.js index ed6e60a0..685418d4 100644 --- a/src/controldock.js +++ b/src/controldock.js @@ -35,6 +35,8 @@ (function( $ ){ /** * @class ControlDock + * @classdesc Provides a container element (a <form> element) with support for the layout of control elements. + * * @memberof OpenSeadragon */ $.ControlDock = function( options ){ diff --git a/src/displayrectangle.js b/src/displayrectangle.js index 0b20b3d6..0f401457 100644 --- a/src/displayrectangle.js +++ b/src/displayrectangle.js @@ -35,10 +35,11 @@ (function( $ ){ /** - * A display rectanlge is very similar to the OpenSeadragon.Rect but adds two + * @class DisplayRect + * @classdesc A display rectangle is very similar to {@link OpenSeadragon.Rect} but adds two * fields, 'minLevel' and 'maxLevel' which denote the supported zoom levels * for this rectangle. - * @class DisplayRect + * * @memberof OpenSeadragon * @extends OpenSeadragon.Rect * @param {Number} x The vector component 'x'. @@ -47,13 +48,21 @@ * @param {Number} height The vector component 'width'. * @param {Number} minLevel The lowest zoom level supported. * @param {Number} maxLevel The highest zoom level supported. - * @property {Number} minLevel The lowest zoom level supported. - * @property {Number} maxLevel The highest zoom level supported. */ $.DisplayRect = function( x, y, width, height, minLevel, maxLevel ) { $.Rect.apply( this, [ x, y, width, height ] ); + /** + * The lowest zoom level supported. + * @member {Number} minLevel + * @memberof OpenSeadragon.DisplayRect# + */ this.minLevel = minLevel; + /** + * The highest zoom level supported. + * @member {Number} maxLevel + * @memberof OpenSeadragon.DisplayRect# + */ this.maxLevel = maxLevel; }; diff --git a/src/drawer.js b/src/drawer.js index cb7d58b1..a25e0aee 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -49,27 +49,13 @@ var DEVICE_SCREEN = $.getWindowSize(), /** * @class Drawer + * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}. + * A new instance is created for each TileSource opened (see {@link OpenSeadragon.Viewer#drawer}). + * * @memberof OpenSeadragon * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source. * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. - * @param {Element} element - Reference to Viewer 'canvas'. - * @property {OpenSeadragon.TileSource} source - Reference to Viewer tile source. - * @property {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. - * @property {Element} container - Reference to Viewer 'canvas'. - * @property {Element|Canvas} canvas - TODO - * @property {CanvasContext} context - TODO - * @property {Object} config - Reference to Viewer config. - * @property {Number} downloading - How many images are currently being loaded in parallel. - * @property {Number} normHeight - Ratio of zoomable image height to width. - * @property {Object} tilesMatrix - A '3d' dictionary [level][x][y] --> Tile. - * @property {Array} tilesLoaded - An unordered list of Tiles with loaded images. - * @property {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean. - * @property {Array} overlays - An unordered list of Overlays added. - * @property {Array} lastDrawn - An unordered list of Tiles drawn last frame. - * @property {Number} lastResetTime - Last time for which the drawer was reset. - * @property {Boolean} midUpdate - Is the drawer currently updating the viewport? - * @property {Boolean} updateAgain - Does the drawer need to update the viewort again? - * @property {Element} element - DEPRECATED Alias for container. + * @param {Element} element - Parent element. */ $.Drawer = function( options ) { @@ -80,9 +66,9 @@ $.Drawer = function( options ) { if( !$.isPlainObject( options ) ){ options = { - source: args[ 0 ], - viewport: args[ 1 ], - element: args[ 2 ] + source: args[ 0 ], // Reference to Viewer tile source. + viewport: args[ 1 ], // Reference to Viewer viewport. + element: args[ 2 ] // Parent element. }; } @@ -90,18 +76,18 @@ $.Drawer = function( options ) { //internal state properties viewer: null, - downloading: 0, - tilesMatrix: {}, - tilesLoaded: [], - coverage: {}, - lastDrawn: [], - lastResetTime: 0, - midUpdate: false, - updateAgain: true, + downloading: 0, // How many images are currently being loaded in parallel. + tilesMatrix: {}, // A '3d' dictionary [level][x][y] --> Tile. + tilesLoaded: [], // An unordered list of Tiles with loaded images. + coverage: {}, // A '3d' dictionary [level][x][y] --> Boolean. + lastDrawn: [], // An unordered list of Tiles drawn last frame. + lastResetTime: 0, // Last time for which the drawer was reset. + midUpdate: false, // Is the drawer currently updating the viewport? + updateAgain: true, // Does the drawer need to update the viewort again? //internal state / configurable settings - overlays: [], + overlays: [], // An unordered list of Overlays added. collectionOverlays: {}, //configurable settings @@ -120,10 +106,33 @@ $.Drawer = function( options ) { }, options ); this.useCanvas = $.supportsCanvas && ( this.viewer ? this.viewer.useCanvas : true ); + /** + * The parent element of this Drawer instance, passed in when the Drawer was created. + * The parent of {@link OpenSeadragon.Drawer#canvas}. + * @member {Element} container + * @memberof OpenSeadragon.Drawer# + */ this.container = $.getElement( this.element ); + /** + * A <canvas> element if the browser supports them, otherwise a <div> element. + * Child element of {@link OpenSeadragon.Drawer#container}. + * @member {Element} canvas + * @memberof OpenSeadragon.Drawer# + */ this.canvas = $.makeNeutralElement( this.useCanvas ? "canvas" : "div" ); + /** + * 2d drawing context for {@link OpenSeadragon.Drawer#canvas} if it's a <canvas> element, otherwise null. + * @member {Object} context + * @memberof OpenSeadragon.Drawer# + */ this.context = this.useCanvas ? this.canvas.getContext( "2d" ) : null; + // Ratio of zoomable image height to width. this.normHeight = this.source.dimensions.y / this.source.dimensions.x; + /** + * @member {Element} element + * @memberof OpenSeadragon.Drawer# + * @deprecated Alias for {@link OpenSeadragon.Drawer#container}. + */ this.element = this.container; // We force our container to ltr because our drawing math doesn't work in rtl. @@ -447,6 +456,11 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ return loading; }, + /** + * Returns whether rotation is supported or not. + * @method + * @return {Boolean} True if rotation is supported. + */ canRotate: function() { return this.useCanvas; } diff --git a/src/eventsource.js b/src/eventsource.js index 0f911af3..a9578ef0 100644 --- a/src/eventsource.js +++ b/src/eventsource.js @@ -44,10 +44,9 @@ /** - * For use by classes which want to support custom, non-browser events. - * TODO: Add a method 'one' which automatically unbinds a listener after - * the first triggered event that matches. * @class EventSource + * @classdesc For use by classes which want to support custom, non-browser events. + * * @memberof OpenSeadragon */ $.EventSource = function() { @@ -56,6 +55,8 @@ $.EventSource = function() { $.EventSource.prototype = /** @lends OpenSeadragon.EventSource.prototype */{ + // TODO: Add a method 'one' which automatically unbinds a listener after the first triggered event that matches. + /** * Add an event handler for a given event. * @function diff --git a/src/iiif1_1tilesource.js b/src/iiif1_1tilesource.js index 319aa0b1..cfddcb8c 100644 --- a/src/iiif1_1tilesource.js +++ b/src/iiif1_1tilesource.js @@ -35,10 +35,10 @@ (function( $ ){ /** - * A client implementation of the International Image Interoperability + * @class IIIF1_1TileSource + * @classdesc A client implementation of the International Image Interoperability * Format: Image API 1.1 * - * @class IIIF1_1TileSource * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ diff --git a/src/iiiftilesource.js b/src/iiiftilesource.js index 3050d9e2..a9b79cd1 100644 --- a/src/iiiftilesource.js +++ b/src/iiiftilesource.js @@ -42,10 +42,10 @@ (function( $ ){ /** - * A client implementation of the International Image Interoperability + * @class IIIFTileSource + * @classdesc A client implementation of the International Image Interoperability * Format: Image API Draft 0.2 * - * @class IIIFTileSource * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ diff --git a/src/legacytilesource.js b/src/legacytilesource.js index a1cb47f5..80891b43 100644 --- a/src/legacytilesource.js +++ b/src/legacytilesource.js @@ -35,13 +35,14 @@ (function( $ ){ /** - * The LegacyTileSource allows simple, traditional image pyramids to be loaded + * @class LegacyTileSource + * @classdesc The LegacyTileSource allows simple, traditional image pyramids to be loaded * into an OpenSeadragon Viewer. Basically, this translates to the historically * common practice of starting with a 'master' image, maybe a tiff for example, * and generating a set of 'service' images like one or more thumbnails, a medium * resolution image and a high resolution image in standard web formats like * png or jpg. - * @class LegacyTileSource + * * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Array} levels An array of file descriptions, each is an object with diff --git a/src/mousetracker.js b/src/mousetracker.js index 596ad166..86238d8c 100644 --- a/src/mousetracker.js +++ b/src/mousetracker.js @@ -46,18 +46,19 @@ THIS = {}; /** - * The MouseTracker allows other classes to set handlers for common mouse - * events on a specific element like, 'enter', 'exit', 'press', 'release', - * 'scroll', 'click', and 'drag'. * @class MouseTracker + * @classdesc Provides simplified handling of common mouse, touch, and keyboard + * events on a specific element, like 'enter', 'exit', 'press', 'release', + * 'scroll', 'click', and 'drag'. + * * @memberof OpenSeadragon * @param {Object} options * Allows configurable properties to be entirely specified by passing * an options object to the constructor. The constructor also supports - * the original positional arguments 'elements', 'clickTimeThreshold', + * the original positional arguments 'element', 'clickTimeThreshold', * and 'clickDistThreshold' in that order. * @param {Element|String} options.element - * A reference to an element or an element id for which the mouse + * A reference to an element or an element id for which the mouse/touch/key * events will be monitored. * @param {Number} options.clickTimeThreshold * The number of milliseconds within which multiple mouse clicks @@ -65,43 +66,33 @@ * @param {Number} options.clickDistThreshold * The distance between mouse click within multiple mouse clicks * will be treated as a single event. - * @param {Number} options.stopDelay + * @param {Number} [options.stopDelay=50] * The number of milliseconds without mouse move before the mouse stop * event is fired. - * @param {OpenSeadragon.EventHandler} options.enterHandler + * @param {OpenSeadragon.EventHandler} [options.enterHandler=null] * An optional handler for mouse enter. - * @param {OpenSeadragon.EventHandler} options.exitHandler + * @param {OpenSeadragon.EventHandler} [options.exitHandler=null] * An optional handler for mouse exit. - * @param {OpenSeadragon.EventHandler} options.pressHandler + * @param {OpenSeadragon.EventHandler} [options.pressHandler=null] * An optional handler for mouse press. - * @param {OpenSeadragon.EventHandler} options.releaseHandler + * @param {OpenSeadragon.EventHandler} [options.releaseHandler=null] * An optional handler for mouse release. - * @param {OpenSeadragon.EventHandler} options.moveHandler + * @param {OpenSeadragon.EventHandler} [options.moveHandler=null] * An optional handler for mouse move. - * @param {OpenSeadragon.EventHandler} options.scrollHandler + * @param {OpenSeadragon.EventHandler} [options.scrollHandler=null] * An optional handler for mouse scroll. - * @param {OpenSeadragon.EventHandler} options.clickHandler + * @param {OpenSeadragon.EventHandler} [options.clickHandler=null] * An optional handler for mouse click. - * @param {OpenSeadragon.EventHandler} options.dragHandler + * @param {OpenSeadragon.EventHandler} [options.dragHandler=null] * An optional handler for mouse drag. - * @param {OpenSeadragon.EventHandler} options.keyHandler + * @param {OpenSeadragon.EventHandler} [options.keyHandler=null] * An optional handler for keypress. - * @param {OpenSeadragon.EventHandler} options.focusHandler + * @param {OpenSeadragon.EventHandler} [options.focusHandler=null] * An optional handler for focus. - * @param {OpenSeadragon.EventHandler} options.blurHandler + * @param {OpenSeadragon.EventHandler} [options.blurHandler=null] * An optional handler for blur. * @param {Object} [options.userData=null] * Arbitrary object to be passed unchanged to any attached handler methods. - * @property {Number} hash - * An unique hash for this tracker. - * @property {Element} element - * The element for which mouse event are being monitored. - * @property {Number} clickTimeThreshold - * The number of milliseconds within which mutliple mouse clicks - * will be treated as a single event. - * @property {Number} clickDistThreshold - * The distance between mouse click within multiple mouse clicks - * will be treated as a single event. */ $.MouseTracker = function ( options ) { @@ -115,9 +106,24 @@ }; } - this.hash = Math.random(); + this.hash = Math.random(); // An unique hash for this tracker. + /** + * The element for which mouse/touch/key events are being monitored. + * @member {Element} element + * @memberof OpenSeadragon.MouseTracker# + */ this.element = $.getElement( options.element ); + /** + * The number of milliseconds within which mutliple mouse clicks will be treated as a single event. + * @member {Number} clickTimeThreshold + * @memberof OpenSeadragon.MouseTracker# + */ this.clickTimeThreshold = options.clickTimeThreshold; + /** + * The distance between mouse click within multiple mouse clicks will be treated as a single event. + * @member {Number} clickDistThreshold + * @memberof OpenSeadragon.MouseTracker# + */ this.clickDistThreshold = options.clickDistThreshold; this.userData = options.userData || null; this.stopDelay = options.stopDelay || 50; diff --git a/src/navigator.js b/src/navigator.js index c90aafb0..f06944f9 100644 --- a/src/navigator.js +++ b/src/navigator.js @@ -35,17 +35,17 @@ (function( $ ){ /** - * The Navigator provides a small view of the current image as fixed + * @class Navigator + * @classdesc The Navigator provides a small view of the current image as fixed * while representing the viewport as a moving box serving as a frame * of reference in the larger viewport as to which portion of the image * is currently being examined. The navigator's viewport can be interacted * with using the keyboard or the mouse. - * @class Navigator + * * @memberof OpenSeadragon * @extends OpenSeadragon.Viewer * @extends OpenSeadragon.EventSource * @param {Object} options - * @param {String} options.viewerId */ $.Navigator = function( options ){ diff --git a/src/openseadragon.js b/src/openseadragon.js index f8da3fc6..9dcd745c 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -118,6 +118,14 @@ * @typedef {Object} Options * @memberof OpenSeadragon * + * @property {String} id + * Id of the element to append the viewer's container element to. If not provided, the 'element' property must be provided. + * If both the element and id properties are specified, the viewer is appended to the element provided in the element property. + * + * @property {Element} element + * The element to append the viewer's container element to. If not provided, the 'id' property must be provided. + * If both the element and id properties are specified, the viewer is appended to the element provided in the element property. + * * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null] * As an Array, the tileSource can hold either Objects or mixed * types of Arrays of Objects, Strings, or Functions. When a value is a String, @@ -625,11 +633,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ $.extend( $, /** @lends OpenSeadragon */{ /** - * These are the default values for the optional settings documented - * at {@link OpenSeadragon.Options}. - * @member DEFAULT_SETTINGS - * @memberof OpenSeadragon + * The default values for the optional settings documented at {@link OpenSeadragon.Options}. * @static + * @type {Object} */ DEFAULT_SETTINGS: { //DATA SOURCE DETAILS @@ -764,10 +770,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * Invokes the method as if it where a method belonging to the object. + * Returns a function which invokes the method as if it were a method belonging to the object. * @function * @param {Object} object * @param {Function} method + * @returns {Function} */ delegate: function( object, method ) { return function(){ @@ -921,12 +928,12 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Gets the latest event, really only useful internally since its - * specific to IE behavior. TODO: Deprecate this from the api and - * use it internally. + * specific to IE behavior. * @function * @param {Event} [event] * @returns {Event} * @deprecated For internal use only + * @private */ getEvent: function( event ) { if( event ){ @@ -1717,12 +1724,14 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * The current browser vendor, version, and related information regarding - * detected features. Features include *'alpha'* - Does the browser support image alpha - * transparency.
+ * The current browser vendor, version, and related information regarding detected features. * @member {Object} Browser * @memberof OpenSeadragon * @static + * @type {Object} + * @property {OpenSeadragon.BROWSERS} vendor - One of the {@link OpenSeadragon.BROWSERS} enumeration values. + * @property {Number} version + * @property {Boolean} alpha - Does the browser support image alpha transparency. */ $.Browser = { vendor: $.BROWSERS.UNKNOWN, diff --git a/src/osmtilesource.js b/src/osmtilesource.js index 11cbc2d6..cc3286bc 100644 --- a/src/osmtilesource.js +++ b/src/osmtilesource.js @@ -43,12 +43,13 @@ (function( $ ){ /** - * A tilesource implementation for OpenStreetMap. + * @class OsmTileSource + * @classdesc A tilesource implementation for OpenStreetMap.

* * Note 1. Zoomlevels. Deep Zoom and OSM define zoom levels differently. In Deep * Zoom, level 0 equals an image of 1x1 pixels. In OSM, level 0 equals an image of * 256x256 levels (see http://gasi.ch/blog/inside-deep-zoom-2). I.e. there is a - * difference of log2(256)=8 levels. + * difference of log2(256)=8 levels.

* * Note 2. Image dimension. According to the OSM Wiki * (http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Zoom_levels) @@ -56,7 +57,6 @@ * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864 * pixels. * - * @class OsmTileSource * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic diff --git a/src/overlay.js b/src/overlay.js index 1cc615f5..29445389 100644 --- a/src/overlay.js +++ b/src/overlay.js @@ -63,12 +63,28 @@ }; /** - * An Overlay provides a * @class Overlay + * @classdesc Provides a way to float an HTML element on top of the viewer element. + * * @memberof OpenSeadragon + * @param {Object} options + * @param {Element} options.element + * @param {OpenSeadragon.Point|OpenSeadragon.Rect} options.location + * @param {OpenSeadragon.OverlayPlacement} options.placement - Only used if location is an {@link OpenSeadragon.Point}. + * @param {OpenSeadragon.Overlay.OnDrawCallback} options.onDraw */ $.Overlay = function( element, location, placement ) { + /** + * onDraw callback signature used by {@link OpenSeadragon.Overlay}. + * + * @callback OnDrawCallback + * @memberof OpenSeadragon.Overlay + * @param {OpenSeadragon.Point} position + * @param {OpenSeadragon.Point} size + * @param {Element} element + */ + var options; if( $.isPlainObject( element ) ){ options = element; diff --git a/src/point.js b/src/point.js index 285071e4..b3cd928a 100644 --- a/src/point.js +++ b/src/point.js @@ -35,18 +35,27 @@ (function( $ ){ /** - * A Point is really used as a 2-dimensional vector, equally useful for + * @class Point + * @classdesc A Point is really used as a 2-dimensional vector, equally useful for * representing a point on a plane, or the height and width of a plane * not requiring any other frame of reference. - * @class Point + * * @memberof OpenSeadragon * @param {Number} [x] The vector component 'x'. Defaults to the origin at 0. * @param {Number} [y] The vector component 'y'. Defaults to the origin at 0. - * @property {Number} [x] The vector component 'x'. - * @property {Number} [y] The vector component 'y'. */ $.Point = function( x, y ) { + /** + * The vector component 'x'. + * @member {Number} x + * @memberof OpenSeadragon.Point# + */ this.x = typeof ( x ) == "number" ? x : 0; + /** + * The vector component 'y'. + * @member {Number} y + * @memberof OpenSeadragon.Point# + */ this.y = typeof ( y ) == "number" ? y : 0; }; diff --git a/src/profiler.js b/src/profiler.js index 1e229b2e..5e6cfb7c 100644 --- a/src/profiler.js +++ b/src/profiler.js @@ -35,9 +35,10 @@ (function( $ ){ /** - * A utility class useful for developers to establish baseline performance - * metrics of rendering routines. * @class Profiler + * @classdesc A utility class useful for developers to establish baseline performance + * metrics of rendering routines. + * * @memberof OpenSeadragon * @property {Boolean} midUpdate * @property {Number} numUpdates diff --git a/src/rectangle.js b/src/rectangle.js index 819fa7a9..99172e7d 100644 --- a/src/rectangle.js +++ b/src/rectangle.js @@ -35,26 +35,42 @@ (function( $ ){ /** - * A Rectangle really represents a 2x2 matrix where each row represents a + * @class Rect + * @classdesc A Rectangle really represents a 2x2 matrix where each row represents a * 2 dimensional vector component, the first is (x,y) and the second is * (width, height). The latter component implies the equation of a simple * plane. * - * @class Rect * @memberof OpenSeadragon * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. * @param {Number} width The vector component 'height'. * @param {Number} height The vector component 'width'. - * @property {Number} x The vector component 'x'. - * @property {Number} y The vector component 'y'. - * @property {Number} width The vector component 'width'. - * @property {Number} height The vector component 'height'. */ $.Rect = function( x, y, width, height ) { + /** + * The vector component 'x'. + * @member {Number} x + * @memberof OpenSeadragon.Rect# + */ this.x = typeof ( x ) == "number" ? x : 0; + /** + * The vector component 'y'. + * @member {Number} y + * @memberof OpenSeadragon.Rect# + */ this.y = typeof ( y ) == "number" ? y : 0; + /** + * The vector component 'width'. + * @member {Number} width + * @memberof OpenSeadragon.Rect# + */ this.width = typeof ( width ) == "number" ? width : 0; + /** + * The vector component 'height'. + * @member {Number} height + * @memberof OpenSeadragon.Rect# + */ this.height = typeof ( height ) == "number" ? height : 0; }; diff --git a/src/referencestrip.js b/src/referencestrip.js index 9afcd356..fc9bcc73 100644 --- a/src/referencestrip.js +++ b/src/referencestrip.js @@ -56,6 +56,11 @@ var THIS = {}; * require better abstraction at those points in order to effeciently * reuse those paradigms. */ +/** + * @class ReferenceStrip + * @memberof OpenSeadragon + * @param {Object} options + */ $.ReferenceStrip = function ( options ) { var _this = this, @@ -220,8 +225,11 @@ $.ReferenceStrip = function ( options ) { }; -$.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototype, { +$.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototype, /** @lends OpenSeadragon.ReferenceStrip.prototype */{ + /** + * @function + */ setFocus: function ( page ) { var element = $.getElement( this.element.id + '-' + page ), viewerSize = $.getElementSize( this.viewer.canvas ), @@ -268,9 +276,9 @@ $.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototyp onStripEnter.call( this, { eventSource: this.innerTracker } ); } }, + /** * @function - * @name OpenSeadragon.ReferenceStrip.prototype.update */ update: function () { if ( THIS[this.id].animating ) { diff --git a/src/spring.js b/src/spring.js index 353c5289..4f92dfcb 100644 --- a/src/spring.js +++ b/src/spring.js @@ -42,14 +42,6 @@ * spring is not in motion initally by default. * @param {Number} options.springStiffness - Spring stiffness. * @param {Number} options.animationTime - Animation duration per spring. - * - * @property {Number} initial - Initial value of spring, default to 0 so - * spring is not in motion initally by default. - * @property {Number} springStiffness - Spring stiffness. - * @property {Number} animationTime - Animation duration per spring. - * @property {Object} current - * @property {Number} start - * @property {Number} target */ $.Spring = function( options ) { var args = arguments; @@ -61,9 +53,19 @@ $.Spring = function( options ) { initial: args.length && typeof ( args[ 0 ] ) == "number" ? args[ 0 ] : 0, + /** + * Spring stiffness. + * @member {Number} springStiffness + * @memberof OpenSeadragon.Spring# + */ springStiffness: args.length > 1 ? args[ 1 ].springStiffness : 5.0, + /** + * Animation duration per spring. + * @member {Number} animationTime + * @memberof OpenSeadragon.Spring# + */ animationTime: args.length > 1 ? args[ 1 ].animationTime : 1.5 @@ -72,7 +74,12 @@ $.Spring = function( options ) { $.extend( true, this, options); - + /** + * @member {Object} current + * @memberof OpenSeadragon.Spring# + * @property {Number} value + * @property {Number} time + */ this.current = { value: typeof ( this.initial ) == "number" ? this.initial : @@ -80,11 +87,23 @@ $.Spring = function( options ) { time: $.now() // always work in milliseconds }; + /** + * @member {Object} start + * @memberof OpenSeadragon.Spring# + * @property {Number} value + * @property {Number} time + */ this.start = { value: this.current.value, time: this.current.time }; + /** + * @member {Object} target + * @memberof OpenSeadragon.Spring# + * @property {Number} value + * @property {Number} time + */ this.target = { value: this.current.value, time: this.current.time diff --git a/src/strings.js b/src/strings.js index 8e473dc5..e6cf8352 100644 --- a/src/strings.js +++ b/src/strings.js @@ -59,11 +59,10 @@ var I18N = { } }; -$.extend( $, { +$.extend( $, /** @lends OpenSeadragon */{ /** * @function - * @name OpenSeadragon.getString * @param {String} property */ getString: function( prop ) { @@ -95,7 +94,6 @@ $.extend( $, { /** * @function - * @name OpenSeadragon.setString * @param {String} property * @param {*} value */ diff --git a/src/tile.js b/src/tile.js index 21eea985..820f856b 100644 --- a/src/tile.js +++ b/src/tile.js @@ -45,53 +45,130 @@ * @param {Boolean} exists Is this tile a part of a sparse image? ( Also has * this tile failed to load? ) * @param {String} url The URL of this tile's image. - * - * @property {Number} level The zoom level this tile belongs to. - * @property {Number} x The vector component 'x'. - * @property {Number} y The vector component 'y'. - * @property {OpenSeadragon.Point} bounds Where this tile fits, in normalized - * coordinates - * @property {Boolean} exists Is this tile a part of a sparse image? ( Also has - * this tile failed to load? - * @property {String} url The URL of this tile's image. - * @property {Boolean} loaded Is this tile loaded? - * @property {Boolean} loading Is this tile loading? - * @property {Element} element The HTML div element for this tile - * @property {Element} imgElement The HTML img element for this tile - * @property {Image} image The Image object for this tile - * @property {String} style The alias of this.element.style. - * @property {String} position This tile's position on screen, in pixels. - * @property {String} size This tile's size on screen, in pixels - * @property {String} blendStart The start time of this tile's blending - * @property {String} opacity The current opacity this tile should be. - * @property {String} distance The distance of this tile to the viewport center - * @property {String} visibility The visibility score of this tile. - * @property {Boolean} beingDrawn Whether this tile is currently being drawn - * @property {Number} lastTouchTime Timestamp the tile was last touched. */ $.Tile = function(level, x, y, bounds, exists, url) { + /** + * The zoom level this tile belongs to. + * @member {Number} level + * @memberof OpenSeadragon.Tile# + */ this.level = level; + /** + * The vector component 'x'. + * @member {Number} x + * @memberof OpenSeadragon.Tile# + */ this.x = x; + /** + * The vector component 'y'. + * @member {Number} y + * @memberof OpenSeadragon.Tile# + */ this.y = y; + /** + * Where this tile fits, in normalized coordinates + * @member {OpenSeadragon.Point} bounds + * @memberof OpenSeadragon.Tile# + */ this.bounds = bounds; + /** + * Is this tile a part of a sparse image? Also has this tile failed to load? + * @member {Boolean} exists + * @memberof OpenSeadragon.Tile# + */ this.exists = exists; + /** + * The URL of this tile's image. + * @member {String} url + * @memberof OpenSeadragon.Tile# + */ this.url = url; + /** + * Is this tile loaded? + * @member {Boolean} loaded + * @memberof OpenSeadragon.Tile# + */ this.loaded = false; + /** + * Is this tile loading? + * @member {Boolean} loading + * @memberof OpenSeadragon.Tile# + */ this.loading = false; + /** + * The HTML div element for this tile + * @member {Element} element + * @memberof OpenSeadragon.Tile# + */ this.element = null; + /** + * The HTML img element for this tile. + * @member {Element} imgElement + * @memberof OpenSeadragon.Tile# + */ this.imgElement = null; + /** + * The Image object for this tile. + * @member {Object} image + * @memberof OpenSeadragon.Tile# + */ this.image = null; + /** + * The alias of this.element.style. + * @member {String} style + * @memberof OpenSeadragon.Tile# + */ this.style = null; + /** + * This tile's position on screen, in pixels. + * @member {OpenSeadragon.Point} position + * @memberof OpenSeadragon.Tile# + */ this.position = null; + /** + * This tile's size on screen, in pixels. + * @member {OpenSeadragon.Point} size + * @memberof OpenSeadragon.Tile# + */ this.size = null; + /** + * The start time of this tile's blending. + * @member {Number} blendStart + * @memberof OpenSeadragon.Tile# + */ this.blendStart = null; + /** + * The current opacity this tile should be. + * @member {Number} opacity + * @memberof OpenSeadragon.Tile# + */ this.opacity = null; + /** + * The distance of this tile to the viewport center. + * @member {Number} distance + * @memberof OpenSeadragon.Tile# + */ this.distance = null; + /** + * The visibility score of this tile. + * @member {Number} visibility + * @memberof OpenSeadragon.Tile# + */ this.visibility = null; + /** + * Whether this tile is currently being drawn. + * @member {Boolean} beingDrawn + * @memberof OpenSeadragon.Tile# + */ this.beingDrawn = false; + /** + * Timestamp the tile was last touched. + * @member {Number} lastTouchTime + * @memberof OpenSeadragon.Tile# + */ this.lastTouchTime = 0; }; diff --git a/src/tilesource.js b/src/tilesource.js index 63da063d..e6dff844 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -36,7 +36,8 @@ /** - * The TileSource contains the most basic implementation required to create a + * @class TileSource + * @classdesc The TileSource contains the most basic implementation required to create a * smooth transition between layer in an image pyramid. It has only a single key * interface that must be implemented to complete it key functionality: * 'getTileUrl'. It also has several optional interfaces that can be @@ -48,7 +49,7 @@ * By default the image pyramid is split into N layers where the images longest * side in M (in pixels), where N is the smallest integer which satisfies * 2^(N+1) >= M. - * @class TileSource + * * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Number|Object|Array|String} width @@ -71,18 +72,6 @@ * The minimum level to attempt to load. * @param {Number} maxLevel * The maximum level to attempt to load. - * @property {Number} aspectRatio - * Ratio of width to height - * @property {OpenSeadragon.Point} dimensions - * Vector storing x and y dimensions ( width and height respectively ). - * @property {Number} tileSize - * The size of the image tiles used to compose the image. - * @property {Number} tileOverlap - * The overlap in pixels each tile shares with it's adjacent neighbors. - * @property {Number} minLevel - * The minimum pyramid level this tile source supports or should attempt to load. - * @property {Number} maxLevel - * The maximum pyramid level this tile source supports or should attempt to load. */ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLevel ) { var callback = null, @@ -126,6 +115,42 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve } } + /** + * Ratio of width to height + * @member {Number} aspectRatio + * @memberof OpenSeadragon.TileSource# + */ + /** + * Vector storing x and y dimensions ( width and height respectively ). + * @member {OpenSeadragon.Point} dimensions + * @memberof OpenSeadragon.TileSource# + */ + /** + * The size of the image tiles used to compose the image. + * @member {Number} tileSize + * @memberof OpenSeadragon.TileSource# + */ + /** + * The overlap in pixels each tile shares with it's adjacent neighbors. + * @member {Number} tileOverlap + * @memberof OpenSeadragon.TileSource# + */ + /** + * The minimum pyramid level this tile source supports or should attempt to load. + * @member {Number} minLevel + * @memberof OpenSeadragon.TileSource# + */ + /** + * The maximum pyramid level this tile source supports or should attempt to load. + * @member {Number} maxLevel + * @memberof OpenSeadragon.TileSource# + */ + /** + * + * @member {Boolean} ready + * @memberof OpenSeadragon.TileSource# + */ + if( 'string' == $.type( arguments[ 0 ] ) ){ //in case the getImageInfo method is overriden and/or implies an //async mechanism set some safe defaults first diff --git a/src/tmstilesource.js b/src/tmstilesource.js index 42857d3e..4c3d0ab0 100644 --- a/src/tmstilesource.js +++ b/src/tmstilesource.js @@ -43,11 +43,11 @@ (function( $ ){ /** - * A tilesource implementation for Tiled Map Services (TMS). + * @class TmsTileSource + * @classdesc A tilesource implementation for Tiled Map Services (TMS). * TMS tile scheme ( [ as supported by OpenLayers ] is described here * ( http://openlayers.org/dev/examples/tms.html ). * - * @class TmsTileSource * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic diff --git a/src/viewer.js b/src/viewer.js index 1d45135d..72ebc1bb 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -51,6 +51,8 @@ var THIS = {}, * as arguments and we translate a positional call into an idiomatic call. * * @class Viewer + * @classdesc The main OpenSeadragon viewer class. + * * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock @@ -94,9 +96,36 @@ $.Viewer = function( options ) { hash: options.hash || options.id, //dom nodes + /** + * The parent element of this Viewer instance, passed in when the Viewer was created. + * @member {Element} element + * @memberof OpenSeadragon.Viewer# + */ element: null, - canvas: null, + /** + * A <form> element (provided by {@link OpenSeadragon.ControlDock}), the base element of this Viewer instance.

+ * Child element of {@link OpenSeadragon.Viewer#element}. + * @member {Element} container + * @memberof OpenSeadragon.Viewer# + */ container: null, + /** + * A <textarea> element, the element where keyboard events are handled.

+ * Child element of {@link OpenSeadragon.Viewer#container}, + * positioned below {@link OpenSeadragon.Viewer#canvas}. + * @member {Element} keyboardCommandArea + * @memberof OpenSeadragon.Viewer# + */ + keyboardCommandArea: null, + /** + * A <div> element, the element where user-input events are handled for panning and zooming.

+ * Child element of {@link OpenSeadragon.Viewer#container}, + * positioned on top of {@link OpenSeadragon.Viewer#keyboardCommandArea}.

+ * The parent of {@link OpenSeadragon.Drawer#canvas} instances. + * @member {Element} canvas + * @memberof OpenSeadragon.Viewer# + */ + canvas: null, //TODO: not sure how to best describe these overlays: [], @@ -117,13 +146,14 @@ $.Viewer = function( options ) { //in initialize. It's still considered idiomatic to put them here source: null, /** + * Handles rendering of tiles in the viewer. Created for each TileSource opened. * @member {OpenSeadragon.Drawer} drawer * @memberof OpenSeadragon.Viewer# */ drawer: null, drawers: [], /** - * The viewer's viewport, where you can access zoom, pan, etc. + * Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened. * @member {OpenSeadragon.Viewport} viewport * @memberof OpenSeadragon.Viewer# */ @@ -416,7 +446,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * A deprecated function, renamed to 'open' to match event name and * match current 'close' method. * @function - * @name OpenSeadragon.Viewer.prototype.openTileSource * @param {String|Object|Function} See OpenSeadragon.Viewer.prototype.open * @return {OpenSeadragon.Viewer} Chainable. * @@ -442,7 +471,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * implementation. If the object has a property which is a function * named 'getTileUrl', it is treated as a custom TileSource. * @function - * @name OpenSeadragon.Viewer.prototype.open * @param {String|Object|Function} * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:open @@ -531,7 +559,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.close * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:close */ @@ -580,7 +607,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * Function to destroy the viewer and clean up everything created by * OpenSeadragon. * @function - * @name OpenSeadragon.Viewer.prototype.destroy */ destroy: function( ) { this.close(); @@ -619,7 +645,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isMouseNavEnabled * @return {Boolean} */ isMouseNavEnabled: function () { @@ -628,7 +653,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled * @param {Boolean} enabled - true to enable, false to disable * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:mouse-enabled @@ -652,7 +676,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.areControlsEnabled * @return {Boolean} */ areControlsEnabled: function () { @@ -669,7 +692,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * Shows or hides the controls (e.g. the default navigation buttons). * * @function - * @name OpenSeadragon.Viewer.prototype.setControlsEnabled * @param {Boolean} true to show, false to hide. * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:controls-enabled @@ -697,7 +719,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isFullPage * @return {Boolean} */ isFullPage: function () { @@ -708,7 +729,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Toggle full page mode. * @function - * @name OpenSeadragon.Viewer.prototype.setFullPage * @param {Boolean} fullPage * If true, enter full page mode. If false, exit full page mode. * @return {OpenSeadragon.Viewer} Chainable. @@ -908,7 +928,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Toggle full screen mode if supported. Toggle full page mode otherwise. * @function - * @name OpenSeadragon.Viewer.prototype.setFullScreen * @param {Boolean} fullScreen * If true, enter full screen mode. If false, exit full screen mode. * @return {OpenSeadragon.Viewer} Chainable. @@ -997,7 +1016,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isVisible * @return {Boolean} */ isVisible: function () { @@ -1007,7 +1025,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.setVisible * @param {Boolean} visible * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:visible @@ -1031,7 +1048,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.bindSequenceControls * @return {OpenSeadragon.Viewer} Chainable. */ bindSequenceControls: function(){ @@ -1117,7 +1133,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.bindStandardControls * @return {OpenSeadragon.Viewer} Chainable. */ bindStandardControls: function(){ @@ -1240,7 +1255,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Gets the active page of a sequence * @function - * @name OpenSeadragon.Viewer.prototype.currentPage * @return {Number} */ currentPage: function () { @@ -1249,7 +1263,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.goToPage * @return {OpenSeadragon.Viewer} Chainable. * @fires OpenSeadragon.Viewer.event:page */ @@ -1643,7 +1656,7 @@ function onCanvasClick( event ) { this.viewport.applyConstraints(); } /** - * Raised when a mouse press/release or touch/remove occurs on the viewer. + * Raised when a mouse press/release or touch/remove occurs on the {@link OpenSeadragon.Viewer#canvas} element. * * @event canvas-click * @memberof OpenSeadragon.Viewer @@ -1683,7 +1696,7 @@ function onCanvasDrag( event ) { } } /** - * Raised when a mouse or touch drag operation occurs in the viewer. + * Raised when a mouse or touch drag operation occurs on the {@link OpenSeadragon.Viewer#canvas} element. * * @event canvas-drag * @memberof OpenSeadragon.Viewer @@ -1710,7 +1723,7 @@ function onCanvasRelease( event ) { this.viewport.applyConstraints(); } /** - * Raised when the mouse button is released or touch ends in the viewer. + * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#canvas} element. * * @event canvas-release * @memberof OpenSeadragon.Viewer @@ -1743,7 +1756,7 @@ function onCanvasScroll( event ) { this.viewport.applyConstraints(); } /** - * Raised when a scroll event occurs in the viewer (mouse wheel, touch pinch, etc.). + * Raised when a scroll event occurs on the {@link OpenSeadragon.Viewer#canvas} element (mouse wheel, touch pinch, etc.). * * @event canvas-scroll * @memberof OpenSeadragon.Viewer @@ -1775,7 +1788,7 @@ function onContainerExit( event ) { } } /** - * Raised when the cursor leaves the viewer element. + * Raised when the cursor leaves the {@link OpenSeadragon.Viewer#container} element. * * @event container-exit * @memberof OpenSeadragon.Viewer @@ -1805,7 +1818,7 @@ function onContainerRelease( event ) { } } /** - * Raised when the mouse button is released or touch ends in the viewer. + * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#container} element. * * @event container-release * @memberof OpenSeadragon.Viewer @@ -1831,7 +1844,7 @@ function onContainerEnter( event ) { THIS[ this.hash ].mouseInside = true; abortControlsAutoHide( this ); /** - * Raised when the cursor enters the viewer element. + * Raised when the cursor enters the {@link OpenSeadragon.Viewer#container} element. * * @event container-enter * @memberof OpenSeadragon.Viewer diff --git a/src/viewport.js b/src/viewport.js index b6744f21..7acfe5b2 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -37,6 +37,9 @@ /** * @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 */ $.Viewport = function( options ) { From 2a1b797767aa549710804e28fba3c6a6cded1b34 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 09:19:50 -0800 Subject: [PATCH 12/18] Modified OpenSeadragon.version property Let grunt do more of the work! --- Gruntfile.js | 6 ++++++ src/openseadragon.js | 42 ++++++++++++++++++------------------------ 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 419752e4..80d133e1 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -55,6 +55,12 @@ module.exports = function(grunt) { // Project configuration. grunt.initConfig({ pkg: packageJson, + version: { + versionStr: packageJson.version, + major: parseInt(packageJson.version.split('.')[0]), + minor: parseInt(packageJson.version.split('.')[1]), + revision: parseInt(packageJson.version.split('.')[2]) + }, clean: { build: ["build"], package: [packageDir], diff --git a/src/openseadragon.js b/src/openseadragon.js index efae6051..f1e6ba8c 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -287,18 +287,12 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * @property {Number} minor - The minor version number. * @property {Number} revision - The revision number. */ - $.version = (function () { - // The version string ('x.x.x') is filled in by the grunt concat build task - // from the 'version' value in package.json - var versionStr = '<%= pkg.version %>', - versionComponents = versionStr.split( '.' ); - return { - versionStr: versionStr, - major: parseInt( versionComponents[ 0 ] ), - minor: parseInt( versionComponents[ 1 ] ), - revision: parseInt( versionComponents[ 2 ] ) - }; - }()); + $.version = { + versionStr: '<%= version.versionStr %>', + major: parseInt('<%= version.major %>'), + minor: parseInt('<%= version.minor %>'), + revision: parseInt('<%= version.revision %>') + }; /** @@ -307,18 +301,18 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * @private */ var class2type = { - '[object Boolean]': 'boolean', - '[object Number]': 'number', - '[object String]': 'string', - '[object Function]': 'function', - '[object Array]': 'array', - '[object Date]': 'date', - '[object RegExp]': 'regexp', - '[object Object]': 'object' - }, - // Save a reference to some core methods - toString = Object.prototype.toString, - hasOwn = Object.prototype.hasOwnProperty; + '[object Boolean]': 'boolean', + '[object Number]': 'number', + '[object String]': 'string', + '[object Function]': 'function', + '[object Array]': 'array', + '[object Date]': 'date', + '[object RegExp]': 'regexp', + '[object Object]': 'object' + }, + // Save a reference to some core methods + toString = Object.prototype.toString, + hasOwn = Object.prototype.hasOwnProperty; /** * Taken from jQuery 1.6.1 From f0d6a5872fb09bd23a78d871de7288e751955477 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 09:30:49 -0800 Subject: [PATCH 13/18] OpenSeadragon.version property change grunt property name changed to be more OpenSeadragon-specific --- Gruntfile.js | 2 +- src/openseadragon.js | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 80d133e1..5243921a 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -55,7 +55,7 @@ module.exports = function(grunt) { // Project configuration. grunt.initConfig({ pkg: packageJson, - version: { + osdVersion: { versionStr: packageJson.version, major: parseInt(packageJson.version.split('.')[0]), minor: parseInt(packageJson.version.split('.')[1]), diff --git a/src/openseadragon.js b/src/openseadragon.js index f1e6ba8c..368646ee 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -280,18 +280,17 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * The OpenSeadragon version. * - * @member {Object} version - * @memberof OpenSeadragon + * @member {Object} OpenSeadragon.version * @property {String} versionStr - The version number as a string ('major.minor.revision'). * @property {Number} major - The major version number. * @property {Number} minor - The minor version number. * @property {Number} revision - The revision number. */ $.version = { - versionStr: '<%= version.versionStr %>', - major: parseInt('<%= version.major %>'), - minor: parseInt('<%= version.minor %>'), - revision: parseInt('<%= version.revision %>') + versionStr: '<%= osdVersion.versionStr %>', + major: parseInt('<%= osdVersion.major %>'), + minor: parseInt('<%= osdVersion.minor %>'), + revision: parseInt('<%= osdVersion.revision %>') }; From 7cb2f7cfd50aacf6e6dcf44ae3fbff53d6b8727a Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 10:38:50 -0800 Subject: [PATCH 14/18] Updated Doclets Botton fixes :) --- src/button.js | 2 +- src/openseadragon.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/button.js b/src/button.js index 5a1e0a30..abadaff4 100644 --- a/src/button.js +++ b/src/button.js @@ -55,7 +55,7 @@ $.ButtonState = { /** * @class Button * @classdesc Manages events, hover states for individual buttons, tool-tips, as well - * as fading the bottons out when the user has not interacted with them + * as fading the buttons out when the user has not interacted with them * for a specified period. * * @memberof OpenSeadragon diff --git a/src/openseadragon.js b/src/openseadragon.js index 9dcd745c..33d0be8e 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -148,7 +148,7 @@ * @property {OpenSeadragon.NavImages} [navImages] * An object with a property for each button or other built-in navigation * control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'. - * Each of those in turn provides an image path for each state of the botton + * Each of those in turn provides an image path for each state of the button * or navigation control, eg 'REST', 'GROUP', 'HOVER', 'PRESS'. Finally the * image paths, by default assume there is a folder on the servers root path * called '/images', eg '/images/zoomin_rest.png'. If you need to adjust From 2684f0ab3a0c0ecedeab92e6addd8195a2ab0926 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 10:44:34 -0800 Subject: [PATCH 15/18] Added radix to parseInt()s --- Gruntfile.js | 6 +++--- src/openseadragon.js | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 5243921a..b077b431 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -57,9 +57,9 @@ module.exports = function(grunt) { pkg: packageJson, osdVersion: { versionStr: packageJson.version, - major: parseInt(packageJson.version.split('.')[0]), - minor: parseInt(packageJson.version.split('.')[1]), - revision: parseInt(packageJson.version.split('.')[2]) + major: parseInt(packageJson.version.split('.')[0], 10), + minor: parseInt(packageJson.version.split('.')[1], 10), + revision: parseInt(packageJson.version.split('.')[2], 10) }, clean: { build: ["build"], diff --git a/src/openseadragon.js b/src/openseadragon.js index 368646ee..1eadf026 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -288,9 +288,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ */ $.version = { versionStr: '<%= osdVersion.versionStr %>', - major: parseInt('<%= osdVersion.major %>'), - minor: parseInt('<%= osdVersion.minor %>'), - revision: parseInt('<%= osdVersion.revision %>') + major: parseInt( '<%= osdVersion.major %>', 10 ), + minor: parseInt( '<%= osdVersion.minor %>', 10 ), + revision: parseInt( '<%= osdVersion.revision %>', 10 ) }; From f34fe1b6e50d9472ca1e39815c98af86e06c9029 Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 11:51:36 -0800 Subject: [PATCH 16/18] Added @since doclet tag to OpenSeadragon.version --- src/openseadragon.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/openseadragon.js b/src/openseadragon.js index 1eadf026..0dfd989c 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -285,6 +285,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * @property {Number} major - The major version number. * @property {Number} minor - The minor version number. * @property {Number} revision - The revision number. + * @since 1.0.0 */ $.version = { versionStr: '<%= osdVersion.versionStr %>', From 12596b2ee5a6c41b63133a03113614be89fe8b9d Mon Sep 17 00:00:00 2001 From: Mark Salsbery Date: Mon, 25 Nov 2013 12:02:43 -0800 Subject: [PATCH 17/18] Add jshint ignore directives to version --- src/openseadragon.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/openseadragon.js b/src/openseadragon.js index 0dfd989c..6b584e2f 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -287,12 +287,14 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ * @property {Number} revision - The revision number. * @since 1.0.0 */ + /* jshint ignore:start */ $.version = { versionStr: '<%= osdVersion.versionStr %>', - major: parseInt( '<%= osdVersion.major %>', 10 ), - minor: parseInt( '<%= osdVersion.minor %>', 10 ), - revision: parseInt( '<%= osdVersion.revision %>', 10 ) + major: <%= osdVersion.major %>, + minor: <%= osdVersion.minor %>, + revision: <%= osdVersion.revision %> }; + /* jshint ignore:end */ /** From 6b310934ff4ae426abbbba08027eeee7a6fedf67 Mon Sep 17 00:00:00 2001 From: Ian Gilman Date: Tue, 26 Nov 2013 09:53:15 -0800 Subject: [PATCH 18/18] Changelog for #281 --- changelog.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.txt b/changelog.txt index c72b2cea..c0c8a3eb 100644 --- a/changelog.txt +++ b/changelog.txt @@ -29,6 +29,7 @@ OPENSEADRAGON CHANGELOG * There is now a 'full-screen' event with a `fullScreen` property (true if it has gone to full screen). * There are now 'pre-full-page' and 'pre-full-screen' events that include a `preventDefaultAction` property you can set in your handler to cancel. They also have `fullPage` and `fullScreen` properties respectively, to indicate if they are going into or out of the mode. * BREAKING CHANGE: Removed the 'onPageChange' callback from the viewer options. Viewer.goToPage() now raises the 'page' event only (#285) +* Major documentation improvements (#281) * MouseTracker now passes the original event objects to its handler methods (#23) * MouseTracker now supports an optional 'moveHandler' method for tracking mousemove events (#215) * Added stopHandler to MouseTracker. (#262)