diff --git a/Gruntfile.js b/Gruntfile.js index 419752e4..b077b431 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -55,6 +55,12 @@ module.exports = function(grunt) { // Project configuration. grunt.initConfig({ pkg: packageJson, + osdVersion: { + versionStr: packageJson.version, + major: parseInt(packageJson.version.split('.')[0], 10), + minor: parseInt(packageJson.version.split('.')[1], 10), + revision: parseInt(packageJson.version.split('.')[2], 10) + }, clean: { build: ["build"], package: [packageDir], diff --git a/changelog.txt b/changelog.txt index e2685843..73dc4c76 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) @@ -56,7 +57,8 @@ 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 an autoResize option. Default is true. When set to false, the viewer takes no action when its container element is resized. +* Added an autoResize option. Default is true. When set to false, the viewer takes no action when its container element is resized. (#291) +* Added a static 'version' property to OpenSeadragon. Useful for plugins that require specific OpenSeadragon versions. (#292) 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/button.js b/src/button.js index ef0e460e..abadaff4 100644 --- a/src/button.js +++ b/src/button.js @@ -35,8 +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, @@ -46,38 +53,30 @@ $.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 + * @class Button + * @classdesc Manages events, hover states for individual buttons, tool-tips, as well + * as fading the buttons out when the user has not interacted with them * for a specified period. - * @class + * + * @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 ) { @@ -94,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, @@ -108,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 @@ -159,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, @@ -177,6 +201,16 @@ $.Button = function( options ) { enterHandler: function( event ) { if ( event.insideElementPressed ) { inTo( _this, $.ButtonState.DOWN ); + /** + * Raised when the cursor enters the Button element. + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "enter", { originalEvent: event.originalEvent } ); } else if ( !event.buttonDownAny ) { inTo( _this, $.ButtonState.HOVER ); @@ -185,29 +219,79 @@ $.Button = function( options ) { focusHandler: function ( event ) { this.enterHandler( event ); + /** + * Raised when the Button element receives focus. + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "focus", { originalEvent: event.originalEvent } ); }, exitHandler: function( event ) { outTo( _this, $.ButtonState.GROUP ); if ( event.insideElementPressed ) { + /** + * Raised when the cursor leaves the Button element. + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "exit", { originalEvent: event.originalEvent } ); } }, blurHandler: function ( event ) { this.exitHandler( event ); + /** + * Raised when the Button element loses focus. + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "blur", { originalEvent: event.originalEvent } ); }, 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} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "press", { originalEvent: event.originalEvent } ); }, releaseHandler: function( event ) { 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} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); } else if ( event.insideElementPressed ) { outTo( _this, $.ButtonState.GROUP ); @@ -218,6 +302,16 @@ $.Button = function( options ) { clickHandler: function( event ) { if ( event.quick ) { + /** + * 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 + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent("click", { originalEvent: event.originalEvent }); } }, @@ -225,7 +319,27 @@ $.Button = function( options ) { keyHandler: function( event ){ //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 and ended in the Button element within the time and distance threshold. + * + * @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 - Arbitrary subscriber-defined object. + */ _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} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); return false; } @@ -237,13 +351,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 ); @@ -253,18 +366,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..22535571 100644 --- a/src/buttongroup.js +++ b/src/buttongroup.js @@ -34,42 +34,41 @@ (function( $ ){ /** - * Manages events on groups of buttons. - * @class - * @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. + * @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.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 @@ -81,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, @@ -110,13 +114,13 @@ $.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 + * @private */ emulateEnter: function() { this.tracker.enterHandler( { eventSource: this.tracker } ); @@ -126,7 +130,7 @@ $.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 + * @private */ emulateExit: function() { this.tracker.exitHandler( { eventSource: this.tracker } ); diff --git a/src/control.js b/src/control.js index ed682f85..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,12 @@ $.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 + * + * @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 @@ -61,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; @@ -82,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 ); @@ -110,7 +134,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..685418d4 100644 --- a/src/controldock.js +++ b/src/controldock.js @@ -34,7 +34,10 @@ (function( $ ){ /** - * @class + * @class ControlDock + * @classdesc Provides a container element (a <form> element) with support for the layout of control elements. + * + * @memberof OpenSeadragon */ $.ControlDock = function( options ){ var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'], @@ -85,7 +88,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..0f401457 100644 --- a/src/displayrectangle.js +++ b/src/displayrectangle.js @@ -35,10 +35,12 @@ (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 + * + * @memberof OpenSeadragon * @extends OpenSeadragon.Rect * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. @@ -46,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 5a049469..a25e0aee 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -48,27 +48,14 @@ var DEVICE_SCREEN = $.getWindowSize(), /** - * @class + * @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 ) { @@ -79,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. }; } @@ -89,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 @@ -119,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. @@ -153,7 +163,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 @@ -170,6 +180,7 @@ $.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; @@ -199,6 +210,18 @@ $.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 - The overlay element. + * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location + * @property {OpenSeadragon.OverlayPlacement} placement + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'add-overlay', { element: element, location: options.location, @@ -218,6 +241,7 @@ $.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; @@ -230,6 +254,18 @@ $.Drawer.prototype = { this.updateAgain = true; } 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} + * @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 - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'update-overlay', { element: element, location: location, @@ -246,6 +282,7 @@ $.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; @@ -259,6 +296,16 @@ $.Drawer.prototype = { this.updateAgain = true; } 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 - The overlay element. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'remove-overlay', { element: element }); @@ -271,6 +318,7 @@ $.Drawer.prototype = { * and update. * @method * @return {OpenSeadragon.Drawer} Chainable. + * @fires OpenSeadragon.Viewer.event:clear-overlay */ clearOverlays: function() { while ( this.overlays.length > 0 ) { @@ -278,6 +326,15 @@ $.Drawer.prototype = { this.updateAgain = true; } 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'clear-overlay', {} ); } return this; @@ -399,6 +456,11 @@ $.Drawer.prototype = { return loading; }, + /** + * Returns whether rotation is supported or not. + * @method + * @return {Boolean} True if rotation is supported. + */ canRotate: function() { return this.useCanvas; } @@ -471,6 +533,15 @@ function updateViewport( drawer ) { drawer.updateAgain = false; if( drawer.viewer ){ + /** + * - Needs documentation - + * + * @event update-viewport + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-viewport', {} ); } @@ -645,6 +716,23 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi if( drawer.viewer ){ + /** + * - Needs documentation - + * + * @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 - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-level', { havedrawn: haveDrawn, level: level, @@ -708,6 +796,16 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le drawTile = drawLevel; 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 {OpenSeadragon.Tile} tile + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-tile', { tile: tile }); @@ -1222,6 +1320,16 @@ 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 {OpenSeadragon.Tile} tile + * @property {?Object} userData - 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..a9578ef0 100644 --- a/src/eventsource.js +++ b/src/eventsource.js @@ -35,22 +35,33 @@ (function($){ /** - * 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 + * Event handler method signature used by all OpenSeadragon events. + * + * @callback EventHandler + * @memberof OpenSeadragon + * @param {Object} event - See individual events for event-specific properties. + */ + + +/** + * @class EventSource + * @classdesc For use by classes which want to support custom, non-browser events. + * + * @memberof OpenSeadragon */ $.EventSource = function() { this.events = {}; }; -$.EventSource.prototype = { +$.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 * @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 +78,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 +115,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 +144,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/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/iiif1_1tilesource.js b/src/iiif1_1tilesource.js index 966f8c17..cfddcb8c 100644 --- a/src/iiif1_1tilesource.js +++ b/src/iiif1_1tilesource.js @@ -35,11 +35,11 @@ (function( $ ){ /** - * A client implementation of the International Image Interoperability - * Format: Image API 1.1 - Please read more about the specification - * at + * @class IIIF1_1TileSource + * @classdesc A client implementation of the International Image Interoperability + * Format: Image API 1.1 * - * @class + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ */ @@ -74,12 +74,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 */ @@ -95,7 +94,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): @@ -118,7 +116,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..a9b79cd1 100644 --- a/src/iiiftilesource.js +++ b/src/iiiftilesource.js @@ -42,11 +42,11 @@ (function( $ ){ /** - * A client implementation of the International Image Interoperability - * Format: Image API Draft 0.2 - Please read more about the specification - * at + * @class IIIFTileSource + * @classdesc A client implementation of the International Image Interoperability + * Format: Image API Draft 0.2 * - * @class + * @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..80891b43 100644 --- a/src/legacytilesource.js +++ b/src/legacytilesource.js @@ -35,13 +35,15 @@ (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 + * + * @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 +98,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 +120,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 +144,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getLevelScale * @param {Number} level */ getLevelScale: function ( level ) { @@ -159,7 +158,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getNumTiles * @param {Number} level */ getNumTiles: function( level ) { @@ -173,7 +171,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getTileAtPoint * @param {Number} level * @param {OpenSeadragon.Point} point */ @@ -188,7 +185,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..86238d8c 100644 --- a/src/mousetracker.js +++ b/src/mousetracker.js @@ -46,17 +46,19 @@ THIS = {}; /** - * The MouseTracker allows other classes to set handlers for common mouse - * events on a specific element like, 'enter', 'exit', 'press', 'release', + * @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'. - * @class + * + * @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 @@ -64,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 {Function} options.enterHandler + * @param {OpenSeadragon.EventHandler} [options.enterHandler=null] * An optional handler for mouse enter. - * @param {Function} options.exitHandler + * @param {OpenSeadragon.EventHandler} [options.exitHandler=null] * An optional handler for mouse exit. - * @param {Function} options.pressHandler + * @param {OpenSeadragon.EventHandler} [options.pressHandler=null] * An optional handler for mouse press. - * @param {Function} options.releaseHandler + * @param {OpenSeadragon.EventHandler} [options.releaseHandler=null] * An optional handler for mouse release. - * @param {Function} options.moveHandler + * @param {OpenSeadragon.EventHandler} [options.moveHandler=null] * An optional handler for mouse move. - * @param {Function} options.scrollHandler + * @param {OpenSeadragon.EventHandler} [options.scrollHandler=null] * An optional handler for mouse scroll. - * @param {Function} options.clickHandler + * @param {OpenSeadragon.EventHandler} [options.clickHandler=null] * An optional handler for mouse click. - * @param {Function} options.dragHandler + * @param {OpenSeadragon.EventHandler} [options.dragHandler=null] * An optional handler for mouse drag. - * @param {Function} options.keyHandler + * @param {OpenSeadragon.EventHandler} [options.keyHandler=null] * An optional handler for keypress. - * @param {Function} options.focusHandler + * @param {OpenSeadragon.EventHandler} [options.focusHandler=null] * An optional handler for focus. - * @param {Function} 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 ) { @@ -114,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; @@ -188,7 +195,7 @@ }; - $.MouseTracker.prototype = { + $.MouseTracker.prototype = /** @lends OpenSeadragon.MouseTracker.prototype */{ /** * Clean up any events or objects created by the mouse tracker. @@ -243,8 +250,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. */ @@ -268,8 +275,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. */ @@ -288,8 +295,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. */ @@ -313,8 +320,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. */ @@ -333,8 +340,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. */ @@ -357,8 +364,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. */ @@ -374,15 +381,15 @@ * @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 * 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. */ @@ -405,8 +412,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. */ @@ -425,8 +432,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. */ @@ -445,8 +452,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. */ @@ -461,8 +468,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. */ @@ -477,8 +484,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/navigator.js b/src/navigator.js index 8c8d344c..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 - * @name OpenSeadragon.Navigator + * + * @memberof OpenSeadragon * @extends OpenSeadragon.Viewer * @extends OpenSeadragon.EventSource * @param {Object} options - * @param {String} options.viewerId */ $.Navigator = function( 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 c011c2d3..e9c0f388 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -82,45 +82,53 @@ */ +/** + * @version <%= pkg.name %> <%= pkg.version %> + * + * @file + *

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. + *

+ * + */ + +/** + * @module OpenSeadragon + * + */ + +/** + * The root namespace for OpenSeadragon. All utility methods + * and classes are defined on or below this namespace. + * + * @namespace OpenSeadragon + * + */ + + +// Typedefs /** - * @version <%= pkg.name %> <%= pkg.version %> + * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer. * - * @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. - *

- */ - - /** - * 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. + * @typedef {Object} Options + * @memberof OpenSeadragon * - * @namespace - * @function - * @name OpenSeadragon - * @exports $ as 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. * - * @param {Object} options All required and optional settings for instantiating - * a new instance of an OpenSeadragon image viewer. + * @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. * - * @param {String} options.xmlPath - * 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 - * 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, + * @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, * 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 @@ -128,147 +136,276 @@ * 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. + * @property {String} [xmlPath=null] + * DEPRECATED. A relative path to load a DZI file from the server. + * Prefer the newer Options.tileSources. * - * @param {Number} [options.animationTime=1.5] - * Specifies the animation duration per each {@link OpenSeadragon.Spring} - * which occur when the image is dragged or zoomed. - * - * @param {Number} [options.blendTime=0.5] - * Specifies the duration of animation as higher or lower level tiles are - * replacing the existing tile. - * - * @param {Boolean} [options.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] - * 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] - * 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 {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. - * - * @param {Boolean} [options.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.8] - * 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] - * 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 {Boolean} [options.autoResize=true] - * Set to false to prevent polling for viewer size changes. Useful for providing custom resize behavior. - * - * @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 - * 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=5.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] - * If multiple mouse clicks occurs within less than this number of - * milliseconds, treat them as a single click. - * - * @param {Number} [options.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] - * The "zoom distance" per mouse click or touch tap. - * - * @param {Number} [options.zoomPerScroll=1.2] - * The "zoom distance" per mouse scroll or touch pinch. - * - * @param {Number} [options.zoomPerSecond=2.0] - * The number of seconds to animate a single zoom event over. - * - * @param {Boolean} [options.showNavigationControl=true] - * Set to false to prevent the appearance of the default navigation controls. - * - * @param {Boolean} [options.showNavigator=false] - * Set to true to make the navigator minimap appear. - * - * @param {Boolean} [options.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.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] - * The number of milliseconds to animate the controls fading out. - * - * @param {Number} [options.maxImageCacheCount=100] - * The max number of images we should keep in memory (per drawer). - * - * @param {Boolean} [options.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] - * 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] - * 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.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 {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 * these paths, prefer setting the option.prefixUrl rather than overriding * every image path directly through this setting. * - * @param {Boolean} [options.navPrevNextWrap=false] + * @property {Object} [tileHost=null] + * TODO: Implement this. Currently not used. + * + * @property {Boolean} [debugMode=false] + * TODO: provide an in-screen panel providing event detail feedback. + * + * @property {String} [debugGridColor='#437AB2'] + * + * @property {Number} [animationTime=1.2] + * Specifies the animation duration per each {@link OpenSeadragon.Spring} + * which occur when the image is dragged or zoomed. + * + * @property {Number} [blendTime=0] + * Specifies the duration of animation as higher or lower level tiles are + * replacing the existing tile. + * + * @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. + * + * @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. + * + * @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. + * + * @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. + * + * @property {Number} [degrees=0] + * Initial rotation. + * + * @property {Number} [minZoomLevel=null] + * + * @property {Number} [maxZoomLevel=null] + * + * @property {Boolean} [panHorizontal=true] + * Allow horizontal pan. + * + * @property {Boolean} [panVertical=true] + * Allow vertical pan. + * + * @property {Boolean} [constrainDuringPan=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. + * + * @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. + * + * @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. + * + * @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. + * + * @property {Boolean} [autoResize=true] + * Set to false to prevent polling for viewer size changes. Useful for providing custom resize behavior. + * + * @property {Number} [pixelsPerWheelLine=40] + * For pixel-resolution scrolling devices, the number of pixels equal to one scroll line. + * + * @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. + * + * @property {Number} [springStiffness=7.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. + * + * @property {Number} [clickTimeThreshold=300] + * If multiple mouse clicks occurs within less than this number of + * milliseconds, treat them as a single click. + * + * @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. + * + * @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. + * + * @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. + * + * @property {Number} [zoomPerSecond=1.0] + * The number of seconds to animate a single zoom event over. + * + * @property {Boolean} [showNavigationControl=true] + * Set to false to prevent the appearance of the default navigation controls. + * + * @property {Boolean} [showNavigator=false] + * Set to true to make the navigator minimap appear. + * + * @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 + * + * @property {Number} [navigatorHeight=null] + * TODO: Implement this. Currently not used. + * + * @property {Number} [navigatorWidth=null] + * TODO: Implement this. Currently not used. + * + * @property {Number} [navigatorPosition=null] + * TODO: Implement this. Currently not used. + * + * @property {Number} [navigatorSizeRatio=0.2] + * Ratio of navigator size to viewer size. + * + * @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. + * + * @property {Number} [controlsFadeLength=1500] + * The number of milliseconds to animate the controls fading out. + * + * @property {Number} [maxImageCacheCount=200] + * The max number of images we should keep in memory (per drawer). + * + * @property {Number} [timeout=30000] + * + * @property {Boolean} [useCanvas=true] + * Set to false to not use an HTML canvas element for image rendering even if canvas is supported. + * + * @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. + * + * @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. + * + * @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. + * + * @property {Number} [initialPage=0] + * If the viewer has been configured with a sequence of tile sources, display this page initially. + * + * @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. + * + * @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 {String} [referenceStripScroll='horizontal'] + * + * @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 - Viewer options. * @returns {OpenSeadragon.Viewer} */ window.OpenSeadragon = window.OpenSeadragon || function( options ){ @@ -277,33 +414,54 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; + (function( $ ){ + /** + * The OpenSeadragon version. + * + * @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. + * @since 1.0.0 + */ + /* jshint ignore:start */ + $.version = { + versionStr: '<%= osdVersion.versionStr %>', + major: <%= osdVersion.major %>, + minor: <%= osdVersion.minor %>, + revision: <%= osdVersion.revision %> + }; + /* jshint ignore:end */ + + /** * Taken from jquery 1.6.1 * [[Class]] -> type pairs * @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 - * @name $.isFunction - * @function - * @see jQuery + * @function isFunction + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isFunction = function( obj ) { return $.type(obj) === "function"; @@ -312,9 +470,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"; @@ -324,9 +482,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; @@ -335,9 +493,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 ) ? @@ -348,9 +506,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. @@ -379,9 +537,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 ) { @@ -393,8 +551,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' ); @@ -421,7 +579,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, @@ -494,12 +654,11 @@ 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. - * @name $.DEFAULT_SETTINGS + * The default values for the optional settings documented at {@link OpenSeadragon.Options}. * @static + * @type {Object} */ DEFAULT_SETTINGS: { //DATA SOURCE DETAILS @@ -635,11 +794,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * Invokes the the method as if it where a method belonging to the object. - * @name $.delegate + * 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(){ @@ -653,10 +812,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** - * An enumeration of Browser vendors including UNKNOWN, IE, FIREFOX, - * SAFARI, CHROME, and OPERA. - * @name $.BROWSERS + * 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, @@ -671,7 +835,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. */ @@ -686,9 +849,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(), @@ -720,9 +882,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 ); @@ -758,9 +919,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 ); @@ -775,7 +935,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} */ @@ -793,12 +952,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 - * @name OpenSeadragon.getEvent * @param {Event} [event] * @returns {Event} + * @deprecated For internal use only + * @private */ getEvent: function( event ) { if( event ){ @@ -817,9 +976,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 ) { @@ -862,8 +1020,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 || {}, @@ -901,8 +1058,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" ) { @@ -953,8 +1109,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 || {}, @@ -993,7 +1148,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 */ @@ -1041,7 +1195,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} */ @@ -1061,7 +1214,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Returns the current milliseconds, using Date.now() if available - * @name $.now * @function */ now: function( ) { @@ -1080,7 +1232,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} */ @@ -1129,7 +1280,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] @@ -1161,7 +1311,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 @@ -1180,7 +1329,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 @@ -1204,7 +1352,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 @@ -1234,7 +1381,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 @@ -1264,7 +1410,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 ) { @@ -1291,7 +1436,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 ) { @@ -1323,7 +1467,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 @@ -1355,7 +1498,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. */ @@ -1400,7 +1542,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 @@ -1465,7 +1606,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 @@ -1546,8 +1686,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Fully deprecated. Will throw an error. * @function - * @name OpenSeadragon.createFromDZI - * @deprecated - use OpenSeadragon.Viewer.prototype.open + * @deprecated use {@link OpenSeadragon.Viewer#open} */ createFromDZI: function() { throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open."; @@ -1556,7 +1695,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Parses an XML string into a DOM Document. * @function - * @name OpenSeadragon.parseXml * @param {String} string * @returns {Document} */ @@ -1598,7 +1736,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} */ @@ -1611,12 +1748,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.
- * @name $.Browser + * 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 23c8d635..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,7 @@ * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864 * pixels. * - * @class + * @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..29445389 100644 --- a/src/overlay.js +++ b/src/overlay.js @@ -35,10 +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, @@ -53,11 +63,28 @@ }; /** - * An Overlay provides a - * @class + * @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; @@ -93,7 +120,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..b3cd928a 100644 --- a/src/point.js +++ b/src/point.js @@ -35,21 +35,31 @@ (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 + * + * @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; }; -$.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..5e6cfb7c 100644 --- a/src/profiler.js +++ b/src/profiler.js @@ -35,9 +35,11 @@ (function( $ ){ /** - * A utility class useful for developers to establish baseline performance + * @class Profiler + * @classdesc A utility class useful for developers to establish baseline performance * metrics of rendering routines. - * @class + * + * @memberof OpenSeadragon * @property {Boolean} midUpdate * @property {Number} numUpdates * @property {Number} lastBeginTime @@ -66,7 +68,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..99172e7d 100644 --- a/src/rectangle.js +++ b/src/rectangle.js @@ -35,29 +35,46 @@ (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 + * @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; }; -$.Rect.prototype = { +$.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{ /** * The aspect ratio is simply the ratio of width to height. 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 2ef2d220..4f92dfcb 100644 --- a/src/spring.js +++ b/src/spring.js @@ -35,20 +35,13 @@ (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. * @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; @@ -60,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 @@ -71,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 : @@ -79,18 +87,30 @@ $.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 }; }; -$.Spring.prototype = { +$.Spring.prototype = /** @lends OpenSeadragon.Spring.prototype */{ /** * @function 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 fc985d1e..820f856b 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'. @@ -44,57 +45,134 @@ * @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; }; -$.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..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,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 + * + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Number|Object|Array|String} width * If more than a single argument is supplied, the traditional use of @@ -70,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, @@ -125,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 @@ -166,7 +192,7 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve }; -$.TileSource.prototype = { +$.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ /** * @function @@ -297,6 +323,17 @@ $.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} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {String} message + * @property {String} source + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } ); return; } @@ -304,6 +341,16 @@ $.TileSource.prototype = { options = $TileSource.prototype.configure.apply( _this, [ data, url ]); readySource = new $TileSource( options ); _this.ready = true; + /** + * Raised when a TileSource is opened and initialized. + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'ready', { tileSource: readySource } ); }; @@ -344,6 +391,17 @@ $.TileSource.prototype = { msg = formattedExc + " attempting to load TileSource"; } + /*** + * Raised when an error occurs loading a 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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: msg, source: url @@ -431,7 +489,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 +531,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..4c3d0ab0 100644 --- a/src/tmstilesource.js +++ b/src/tmstilesource.js @@ -43,11 +43,12 @@ (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 + * @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 ab2dc8f4..7d9e755b 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -50,20 +50,13 @@ 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 + * @classdesc The main OpenSeadragon viewer class. + * + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock - * @param {Object} 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. * **/ $.Viewer = function( options ) { @@ -103,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: [], @@ -123,15 +143,29 @@ $.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, + /** + * Handles rendering of tiles in the viewer. Created for each TileSource opened. + * @member {OpenSeadragon.Drawer} drawer + * @memberof OpenSeadragon.Viewer# + */ drawer: null, drawers: [], + /** + * Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened. + * @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 + //simultaneous rendering of sets of tiles collectionViewport: null, collectionDrawer: null, @@ -384,12 +418,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,11 +433,10 @@ $.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. * - * @deprecated - use 'open' instead. + * @deprecated - use {@link OpenSeadragon.Viewer#open} instead. */ openDzi: function ( dzi ) { return this.open( dzi ); @@ -414,11 +446,10 @@ $.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. * - * @deprecated - use 'open' instead. + * @deprecated - use {@link OpenSeadragon.Viewer#open} instead. */ openTileSource: function ( tileSource ) { return this.open( tileSource ); @@ -440,9 +471,10 @@ $.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 + * @fires OpenSeadragon.Viewer.event:open-failed */ open: function ( tileSource ) { var _this = this, @@ -470,6 +502,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, openTileSource( _this, event.tileSource ); }); tileSource.addHandler( 'open-failed', function ( event ) { + /** + * Raised when an error occurs loading a 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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', event ); }); @@ -483,6 +526,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, //inline configuration $TileSource = $.TileSource.determineType( _this, tileSource ); if ( !$TileSource ) { + /*** + * Raised when an error occurs loading a 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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: tileSource @@ -505,8 +559,8 @@ $.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 ) { @@ -534,6 +588,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, VIEWERS[ this.hash ] = null; delete VIEWERS[ this.hash ]; + /** + * Raised when the viewer is closed (see {@link OpenSeadragon.Viewer#close}). + * + * @event close + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'close' ); return this; @@ -544,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(); @@ -583,7 +645,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isMouseNavEnabled * @return {Boolean} */ isMouseNavEnabled: function () { @@ -592,11 +653,22 @@ $.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 */ 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} enabled + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'mouse-enabled', { enabled: enabled } ); return this; }, @@ -604,7 +676,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.areControlsEnabled * @return {Boolean} */ areControlsEnabled: function () { @@ -621,9 +692,9 @@ $.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 */ setControlsEnabled: function( enabled ) { if( enabled ){ @@ -631,6 +702,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } else { beginControlsAutoHide( this ); } + /** + * Raised when the navigation controls are shown or hidden (see {@link OpenSeadragon.Viewer#setControlsEnabled}). + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'controls-enabled', { enabled: enabled } ); return this; }, @@ -638,7 +719,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isFullPage * @return {Boolean} */ isFullPage: function () { @@ -649,10 +729,11 @@ $.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. + * @fires OpenSeadragon.Viewer.event:pre-full-page + * @fires OpenSeadragon.Viewer.event:full-page */ setFullPage: function( fullPage ) { @@ -673,6 +754,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullPage: fullPage, 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} + * @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. Default: false. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-page', fullPageEventArgs ); if ( fullPageEventArgs.preventDefaultAction ) { return this; @@ -818,6 +910,16 @@ $.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} + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'full-page', { fullPage: fullPage } ); return this; @@ -826,10 +928,11 @@ $.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. + * @fires OpenSeadragon.Viewer.event:pre-full-screen + * @fires OpenSeadragon.Viewer.event:full-screen */ setFullScreen: function( fullScreen ) { var _this = this; @@ -846,6 +949,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullScreen: fullScreen, 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} + * @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. Default: false. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-screen', fullScreeEventArgs ); if ( fullScreeEventArgs.preventDefaultAction ) { return this; @@ -877,6 +991,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, _this.element.style.height = _this.fullPageStyleHeight; } } + /** + * Raised when the viewer has changed to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}). + * + * @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 - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } ); }; $.addEvent( document, $.fullScreenEventName, onFullScreenChange ); @@ -892,7 +1016,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.isVisible * @return {Boolean} */ isVisible: function () { @@ -902,11 +1025,22 @@ $.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 */ 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} visible + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'visible', { visible: visible } ); return this; }, @@ -914,7 +1048,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.bindSequenceControls * @return {OpenSeadragon.Viewer} Chainable. */ bindSequenceControls: function(){ @@ -1000,7 +1133,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function - * @name OpenSeadragon.Viewer.prototype.bindStandardControls * @return {OpenSeadragon.Viewer} Chainable. */ bindStandardControls: function(){ @@ -1123,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 () { @@ -1132,13 +1263,13 @@ $.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 @@ -1165,7 +1296,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Updates the sequence buttons. - * @function + * @function OpenSeadragon.Viewer.prototype._updateSequenceButtons * @private * @param {Number} Sequence Value */ @@ -1195,7 +1326,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 */ @@ -1214,7 +1345,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Hide any currently displayed viewport message - * @function + * @function OpenSeadragon.Viewer.prototype._hideMessage * @private */ _hideMessage: function () { @@ -1409,6 +1540,16 @@ 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {OpenSeadragon.TileSource} source + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open', { source: source } ); return _this; @@ -1514,6 +1655,20 @@ function onCanvasClick( event ) { ); this.viewport.applyConstraints(); } + /** + * Raised when a mouse press/release or touch/remove occurs on the {@link OpenSeadragon.Viewer#canvas} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-click', { tracker: event.eventSource, position: event.position, @@ -1540,6 +1695,20 @@ function onCanvasDrag( event ) { this.viewport.applyConstraints(); } } + /** + * Raised when a mouse or touch drag operation occurs on the {@link OpenSeadragon.Viewer#canvas} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-drag', { tracker: event.eventSource, position: event.position, @@ -1553,6 +1722,20 @@ function onCanvasRelease( event ) { if ( event.insideElementPressed && this.viewport ) { this.viewport.applyConstraints(); } + /** + * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#canvas} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-release', { tracker: event.eventSource, position: event.position, @@ -1572,6 +1755,20 @@ function onCanvasScroll( event ) { ); this.viewport.applyConstraints(); } + /** + * Raised when a scroll event occurs on the {@link OpenSeadragon.Viewer#canvas} element (mouse wheel, touch pinch, etc.). + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-scroll', { tracker: event.eventSource, position: event.position, @@ -1590,6 +1787,20 @@ function onContainerExit( event ) { beginControlsAutoHide( this ); } } + /** + * Raised when the cursor leaves the {@link OpenSeadragon.Viewer#container} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-exit', { tracker: event.eventSource, position: event.position, @@ -1606,6 +1817,20 @@ function onContainerRelease( event ) { beginControlsAutoHide( this ); } } + /** + * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#container} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-release', { tracker: event.eventSource, position: event.position, @@ -1618,6 +1843,20 @@ function onContainerRelease( event ) { function onContainerEnter( event ) { THIS[ this.hash ].mouseInside = true; abortControlsAutoHide( this ); + /** + * Raised when the cursor enters the {@link OpenSeadragon.Viewer#container} element. + * + * @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 - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-enter', { tracker: event.eventSource, position: event.position, @@ -1676,6 +1915,15 @@ 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-start" ); abortControlsAutoHide( viewer ); } @@ -1685,6 +1933,15 @@ function updateOnce( viewer ) { if( viewer.navigator ){ viewer.navigator.update( viewer.viewport ); } + /** + * Raised when any spring animation update occurs (zoom, pan, etc.). + * + * @event animation + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation" ); } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) { viewer.drawer.update(); @@ -1695,6 +1952,15 @@ 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-finish" ); if ( !THIS[ viewer.hash ].mouseInside ) { diff --git a/src/viewport.js b/src/viewport.js index c4cea72f..65230f4a 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -36,7 +36,11 @@ /** - * @class + * @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 ) { @@ -105,11 +109,12 @@ $.Viewport = function( options ) { this.update(); }; -$.Viewport.prototype = { +$.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:reset-size */ resetContentSize: function( contentSize ){ this.contentSize = contentSize; @@ -121,6 +126,16 @@ $.Viewport.prototype = { this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY ); 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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} contentSize + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'reset-size', { contentSize: contentSize }); @@ -164,9 +179,20 @@ $.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} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Boolean} immediately + * @property {?Object} userData - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'home', { immediately: immediately }); @@ -297,6 +323,7 @@ $.Viewport.prototype = { /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:constrain */ applyConstraints: function( immediately ) { var actualZoom = this.getZoom(), @@ -367,6 +394,16 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * Raised when the viewport constraints are applied (see {@link OpenSeadragon.Viewport#applyConstraints}). + * + * @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 - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'constrain', { immediately: immediately }); @@ -492,6 +529,7 @@ $.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( @@ -507,6 +545,7 @@ $.Viewport.prototype = { * @param {OpenSeadragon.Point} center * @param {Boolean} immediately * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:pan */ panTo: function( center, immediately ) { if ( immediately ) { @@ -518,6 +557,17 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panBy} and {@link OpenSeadragon.Viewport#panTo}). + * + * @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 - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'pan', { center: center, immediately: immediately @@ -530,6 +580,7 @@ $.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 ) ) { @@ -544,6 +595,7 @@ $.Viewport.prototype = { /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:zoom */ zoomTo: function( zoom, refPoint, immediately ) { @@ -560,6 +612,18 @@ $.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} + * @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 - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'zoom', { zoom: zoom, refPoint: refPoint, @@ -576,7 +640,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 +660,6 @@ $.Viewport.prototype = { /** * Gets the current rotation in degrees. * @function - * @name OpenSeadragon.Viewport.prototype.getRotation * @return {Number} The current rotation in degrees. */ getRotation: function() { @@ -607,6 +669,7 @@ $.Viewport.prototype = { /** * @function * @return {OpenSeadragon.Viewport} Chainable. + * @fires OpenSeadragon.Viewer.event:resize */ resize: function( newContainerSize, maintain ) { var oldBounds = this.getBounds(), @@ -625,6 +688,17 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * Raised when the viewer is resized (see {@link OpenSeadragon.Viewport#resize}). + * + * @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 - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'resize', { newContainerSize: newContainerSize, maintain: maintain