mirror/openseadragon
1
0
Fork 0
mirror of https://github.com/openseadragon/openseadragon.git synced 2024-11-25 06:36:11 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #281 from msalsbery/jsdoc3-documentation

Browse Source 
Updated doclets for jsdoc3
This commit is contained in:
iangilman 2013-11-26 09:42:34 -08:00
commit 5a5447dfd3
29 changed files with 1574 additions and 624 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
src/button.js
View File

@ -35,8 +35,15 @@
(function( $ ){ (function( $ ){
/** /**
* An enumeration of button states including, REST, GROUP, HOVER, and DOWN * An enumeration of button states
* @member ButtonState
* @memberof OpenSeadragon
* @static * @static
* @type {Object}
* @property {Number} REST
* @property {Number} GROUP
* @property {Number} HOVER
* @property {Number} DOWN
*/ */
$.ButtonState = { $.ButtonState = {
REST: 0, REST: 0,
@ -46,38 +53,30 @@ $.ButtonState = {
}; };
/** /**
* Manages events, hover states for individual buttons, tool-tips, as well * @class Button
* as fading the bottons out when the user has not interacted with them * @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. * for a specified period.
* @class *
* @memberof OpenSeadragon
* @extends OpenSeadragon.EventSource * @extends OpenSeadragon.EventSource
* @param {Object} options * @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. * user hovers over it.
* @param {String} options.srcRest URL of image to use in 'rest' state * @param {String} [options.srcRest=null] URL of image to use in 'rest' state.
* @param {String} options.srcGroup URL of image to use in 'up' state * @param {String} [options.srcGroup=null] URL of image to use in 'up' state.
* @param {String} options.srcHover URL of image to use in 'hover' state * @param {String} [options.srcHover=null] URL of image to use in 'hover' state.
* @param {String} options.srcDown URL of image to use in 'down' state * @param {String} [options.srcDown=null] URL of image to use in 'down' state.
* @param {Element} [options.element] Element to use as a container for the * @param {Number} [options.fadeDelay=0] How long to wait before fading.
* button. * @param {Number} [options.fadeLength=2000] How long should it take to fade the button.
* @property {String} tooltip Provides context help for the button we the * @param {OpenSeadragon.EventHandler} [options.onPress=null] Event handler callback for {@link OpenSeadragon.Button.event:press}.
* user hovers over it. * @param {OpenSeadragon.EventHandler} [options.onRelease=null] Event handler callback for {@link OpenSeadragon.Button.event:release}.
* @property {String} srcRest URL of image to use in 'rest' state * @param {OpenSeadragon.EventHandler} [options.onClick=null] Event handler callback for {@link OpenSeadragon.Button.event:click}.
* @property {String} srcGroup URL of image to use in 'up' state * @param {OpenSeadragon.EventHandler} [options.onEnter=null] Event handler callback for {@link OpenSeadragon.Button.event:enter}.
* @property {String} srcHover URL of image to use in 'hover' state * @param {OpenSeadragon.EventHandler} [options.onExit=null] Event handler callback for {@link OpenSeadragon.Button.event:exit}.
* @property {String} srcDown URL of image to use in 'down' state * @param {OpenSeadragon.EventHandler} [options.onFocus=null] Event handler callback for {@link OpenSeadragon.Button.event:focus}.
* @property {Object} config Configurable settings for this button. DEPRECATED. * @param {OpenSeadragon.EventHandler} [options.onBlur=null] Event handler callback for {@link OpenSeadragon.Button.event:blur}.
* @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;
*/ */
$.Button = function( options ) { $.Button = function( options ) {
@ -94,9 +93,17 @@ $.Button = function( options ) {
srcDown: null, srcDown: null,
clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold, clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold,
clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold, clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold,
// begin fading immediately /**
* How long to wait before fading.
* @member {Number} fadeDelay
* @memberof OpenSeadragon.Button#
*/
fadeDelay: 0, 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, fadeLength: 2000,
onPress: null, onPress: null,
onRelease: null, onRelease: null,
@ -108,6 +115,11 @@ $.Button = function( options ) {
}, options ); }, options );
/**
* The button element.
* @member {Element} element
* @memberof OpenSeadragon.Button#
*/
this.element = options.element || $.makeNeutralElement( "button" ); this.element = options.element || $.makeNeutralElement( "button" );
//if the user has specified the element to bind the control to explicitly //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( "focus", this.onFocus );
this.addHandler( "blur", this.onBlur ); this.addHandler( "blur", this.onBlur );
/**
* The button's current state.
* @member {OpenSeadragon.ButtonState} currentState
* @memberof OpenSeadragon.Button#
*/
this.currentState = $.ButtonState.GROUP; this.currentState = $.ButtonState.GROUP;
// When the button last began to fade.
this.fadeBeginTime = null; this.fadeBeginTime = null;
// Whether this button should fade after user stops interacting with the viewport.
this.shouldFade = false; this.shouldFade = false;
this.element.style.display = "inline-block"; this.element.style.display = "inline-block";
this.element.style.position = "relative"; this.element.style.position = "relative";
this.element.title = this.tooltip; this.element.title = this.tooltip;
/**
* Tracks mouse/touch/key events on the button.
* @member {OpenSeadragon.MouseTracker} tracker
* @memberof OpenSeadragon.Button#
*/
this.tracker = new $.MouseTracker({ this.tracker = new $.MouseTracker({
element: this.element, element: this.element,
@ -177,6 +201,16 @@ $.Button = function( options ) {
enterHandler: function( event ) { enterHandler: function( event ) {
if ( event.insideElementPressed ) { if ( event.insideElementPressed ) {
inTo( _this, $.ButtonState.DOWN ); 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 } ); _this.raiseEvent( "enter", { originalEvent: event.originalEvent } );
} else if ( !event.buttonDownAny ) { } else if ( !event.buttonDownAny ) {
inTo( _this, $.ButtonState.HOVER ); inTo( _this, $.ButtonState.HOVER );
@ -185,29 +219,79 @@ $.Button = function( options ) {
focusHandler: function ( event ) { focusHandler: function ( event ) {
this.enterHandler( 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 } ); _this.raiseEvent( "focus", { originalEvent: event.originalEvent } );
}, },
exitHandler: function( event ) { exitHandler: function( event ) {
outTo( _this, $.ButtonState.GROUP ); outTo( _this, $.ButtonState.GROUP );
if ( event.insideElementPressed ) { 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 } ); _this.raiseEvent( "exit", { originalEvent: event.originalEvent } );
} }
}, },
blurHandler: function ( event ) { blurHandler: function ( event ) {
this.exitHandler( 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 } ); _this.raiseEvent( "blur", { originalEvent: event.originalEvent } );
}, },
pressHandler: function ( event ) { pressHandler: function ( event ) {
inTo( _this, $.ButtonState.DOWN ); 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 } ); _this.raiseEvent( "press", { originalEvent: event.originalEvent } );
}, },
releaseHandler: function( event ) { releaseHandler: function( event ) {
if ( event.insideElementPressed && event.insideElementReleased ) { if ( event.insideElementPressed && event.insideElementReleased ) {
outTo( _this, $.ButtonState.HOVER ); 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 } ); _this.raiseEvent( "release", { originalEvent: event.originalEvent } );
} else if ( event.insideElementPressed ) { } else if ( event.insideElementPressed ) {
outTo( _this, $.ButtonState.GROUP ); outTo( _this, $.ButtonState.GROUP );
@ -218,6 +302,16 @@ $.Button = function( options ) {
clickHandler: function( event ) { clickHandler: function( event ) {
if ( event.quick ) { 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 }); _this.raiseEvent("click", { originalEvent: event.originalEvent });
} }
}, },
@ -225,7 +319,27 @@ $.Button = function( options ) {
keyHandler: function( event ){ keyHandler: function( event ){
//console.log( "%s : handling key %s!", _this.tooltip, event.keyCode); //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode);
if( 13 === 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 } ); _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 } ); _this.raiseEvent( "release", { originalEvent: event.originalEvent } );
return false; return false;
} }
@ -237,13 +351,12 @@ $.Button = function( options ) {
outTo( this, $.ButtonState.REST ); 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 * TODO: Determine what this function is intended to do and if it's actually
* useful as an API point. * useful as an API point.
* @function * @function
* @name OpenSeadragon.Button.prototype.notifyGroupEnter
*/ */
notifyGroupEnter: function() { notifyGroupEnter: function() {
inTo( this, $.ButtonState.GROUP ); 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 * TODO: Determine what this function is intended to do and if it's actually
* useful as an API point. * useful as an API point.
* @function * @function
* @name OpenSeadragon.Button.prototype.notifyGroupExit
*/ */
notifyGroupExit: function() { notifyGroupExit: function() {
outTo( this, $.ButtonState.REST ); outTo( this, $.ButtonState.REST );
}, },
/**
* @function
*/
disable: function(){ disable: function(){
this.notifyGroupExit(); this.notifyGroupExit();
this.element.disabled = true; this.element.disabled = true;
$.setElementOpacity( this.element, 0.2, true ); $.setElementOpacity( this.element, 0.2, true );
}, },
/**
* @function
*/
enable: function(){ enable: function(){
this.element.disabled = false; this.element.disabled = false;
$.setElementOpacity( this.element, 1.0, true ); $.setElementOpacity( this.element, 1.0, true );

50
src/buttongroup.js
View File

@ -34,42 +34,41 @@
(function( $ ){ (function( $ ){
/** /**
* Manages events on groups of buttons. * @class ButtonGroup
* @class * @classdesc Manages events on groups of buttons.
* @param {Object} options - a dictionary of settings applied against the entire *
* group of buttons * @memberof OpenSeadragon
* @param {Array} options.buttons Array of buttons * @param {Object} options - A dictionary of settings applied against the entire group of buttons.
* @param {Element} [options.group] Element to use as the container, * @param {Array} options.buttons Array of buttons
* @param {Object} options.config Object with Viewer settings ( TODO: is * @param {Element} [options.element] Element to use as the container
* 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.
**/ **/
$.ButtonGroup = function( options ) { $.ButtonGroup = function( options ) {
$.extend( true, this, { $.extend( true, this, {
/**
* An array containing the buttons themselves.
* @member {Array} buttons
* @memberof OpenSeadragon.ButtonGroup#
*/
buttons: [], buttons: [],
clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold, clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold,
clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold, clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold,
labelText: "" labelText: ""
}, options ); }, options );
// copy the botton elements // copy the button elements TODO: Why?
var buttons = this.buttons.concat([]), var buttons = this.buttons.concat([]),
_this = this, _this = this,
i; i;
/**
* The shared container for the buttons.
* @member {Element} element
* @memberof OpenSeadragon.ButtonGroup#
*/
this.element = options.element || $.makeNeutralElement( "fieldgroup" ); this.element = options.element || $.makeNeutralElement( "fieldgroup" );
// TODO What if there IS an options.group specified?
if( !options.group ){ if( !options.group ){
this.label = $.makeNeutralElement( "label" ); this.label = $.makeNeutralElement( "label" );
//TODO: support labels for ButtonGroups //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({ this.tracker = new $.MouseTracker({
element: this.element, element: this.element,
clickTimeThreshold: this.clickTimeThreshold, clickTimeThreshold: this.clickTimeThreshold,
@ -110,13 +114,13 @@ $.ButtonGroup = function( options ) {
}).setTracking( true ); }).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 * TODO: Figure out why this is used on the public API and if a more useful
* api can be created. * api can be created.
* @function * @function
* @name OpenSeadragon.ButtonGroup.prototype.emulateEnter * @private
*/ */
emulateEnter: function() { emulateEnter: function() {
this.tracker.enterHandler( { eventSource: this.tracker } ); 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 * TODO: Figure out why this is used on the public API and if a more useful
* api can be created. * api can be created.
* @function * @function
* @name OpenSeadragon.ButtonGroup.prototype.emulateExit * @private
*/ */
emulateExit: function() { emulateExit: function() {
this.tracker.exitHandler( { eventSource: this.tracker } ); this.tracker.exitHandler( { eventSource: this.tracker } );

56
src/control.js
View File

@ -35,10 +35,17 @@
(function( $ ){ (function( $ ){
/** /**
* An enumeration of supported locations where controls can be anchored, * 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.
* The anchoring is always relative to the container * @member ControlAnchor
* @memberof OpenSeadragon
* @static * @static
* @type {Object}
* @property {Number} NONE
* @property {Number} TOP_LEFT
* @property {Number} TOP_RIGHT
* @property {Number} BOTTOM_LEFT
* @property {Number} BOTTOM_RIGHT
*/ */
$.ControlAnchor = { $.ControlAnchor = {
NONE: 0, 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 * to interact with the zoomable interface. Any control can be anchored to any
* element. * element.
* @class *
* @memberof OpenSeadragon
* @param {Element} element - the control element to be anchored in the container. * @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 {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 * @param {OpenSeadragon.ControlAnchor} [options.anchor=OpenSeadragon.ControlAnchor.NONE] - the position of the control
@ -61,16 +70,6 @@ $.ControlAnchor = {
* directly to the container * directly to the container
* @param {Boolean} [options.autoFade=true] - Whether the control should have the autofade behavior * @param {Boolean} [options.autoFade=true] - Whether the control should have the autofade behavior
* @param {Element} container - the element to control will be anchored too. * @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 ) { $.Control = function ( element, options, container ) {
var parent = element.parentNode; var parent = element.parentNode;
@ -82,10 +81,35 @@ $.Control = function ( element, options, container ) {
options = {anchor: options}; options = {anchor: options};
} }
options.attachToViewer = (typeof options.attachToViewer === 'undefined') ? true : options.attachToViewer; 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; 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; this.element = element;
/**
* The position of the Control relative to its container.
* @member {OpenSeadragon.ControlAnchor} anchor
* @memberof OpenSeadragon.Control#
*/
this.anchor = options.anchor; this.anchor = options.anchor;
/**
* The Control's containing element.
* @member {Element} container
* @memberof OpenSeadragon.Control#
*/
this.container = container; this.container = container;
/**
* A neutral element surrounding the control element.
* @member {Element} wrapper
* @memberof OpenSeadragon.Control#
*/
this.wrapper = $.makeNeutralElement( "span" ); this.wrapper = $.makeNeutralElement( "span" );
this.wrapper.style.display = "inline-block"; this.wrapper.style.display = "inline-block";
this.wrapper.appendChild( this.element ); 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. * Removes the control from the container.

7
src/controldock.js
View File

@ -34,7 +34,10 @@
(function( $ ){ (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 ){ $.ControlDock = function( options ){
var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'], var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'],
@ -85,7 +88,7 @@
this.container.appendChild( this.controls.bottomleft ); this.container.appendChild( this.controls.bottomleft );
}; };
$.ControlDock.prototype = { $.ControlDock.prototype = /** @lends OpenSeadragon.ControlDock.prototype */{
/** /**
* @function * @function

18
src/displayrectangle.js
View File

@ -35,10 +35,12 @@
(function( $ ){ (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 * fields, 'minLevel' and 'maxLevel' which denote the supported zoom levels
* for this rectangle. * for this rectangle.
* @class *
* @memberof OpenSeadragon
* @extends OpenSeadragon.Rect * @extends OpenSeadragon.Rect
* @param {Number} x The vector component 'x'. * @param {Number} x The vector component 'x'.
* @param {Number} y The vector component 'y'. * @param {Number} y The vector component 'y'.
@ -46,13 +48,21 @@
* @param {Number} height The vector component 'width'. * @param {Number} height The vector component 'width'.
* @param {Number} minLevel The lowest zoom level supported. * @param {Number} minLevel The lowest zoom level supported.
* @param {Number} maxLevel The highest 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 ) { $.DisplayRect = function( x, y, width, height, minLevel, maxLevel ) {
$.Rect.apply( this, [ x, y, width, height ] ); $.Rect.apply( this, [ x, y, width, height ] );
/**
* The lowest zoom level supported.
* @member {Number} minLevel
* @memberof OpenSeadragon.DisplayRect#
*/
this.minLevel = minLevel; this.minLevel = minLevel;
/**
* The highest zoom level supported.
* @member {Number} maxLevel
* @memberof OpenSeadragon.DisplayRect#
*/
this.maxLevel = maxLevel; this.maxLevel = maxLevel;
}; };

172
src/drawer.js
View File

@ -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.TileSource} source - Reference to Viewer tile source.
* @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport.
* @param {Element} element - Reference to Viewer 'canvas'. * @param {Element} element - Parent element.
* @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.
*/ */
$.Drawer = function( options ) { $.Drawer = function( options ) {
@ -79,9 +66,9 @@ $.Drawer = function( options ) {
if( !$.isPlainObject( options ) ){ if( !$.isPlainObject( options ) ){
options = { options = {
source: args[ 0 ], source: args[ 0 ], // Reference to Viewer tile source.
viewport: args[ 1 ], viewport: args[ 1 ], // Reference to Viewer viewport.
element: args[ 2 ] element: args[ 2 ] // Parent element.
}; };
} }
@ -89,18 +76,18 @@ $.Drawer = function( options ) {
//internal state properties //internal state properties
viewer: null, viewer: null,
downloading: 0, downloading: 0, // How many images are currently being loaded in parallel.
tilesMatrix: {}, tilesMatrix: {}, // A '3d' dictionary [level][x][y] --> Tile.
tilesLoaded: [], tilesLoaded: [], // An unordered list of Tiles with loaded images.
coverage: {}, coverage: {}, // A '3d' dictionary [level][x][y] --> Boolean.
lastDrawn: [], lastDrawn: [], // An unordered list of Tiles drawn last frame.
lastResetTime: 0, lastResetTime: 0, // Last time for which the drawer was reset.
midUpdate: false, midUpdate: false, // Is the drawer currently updating the viewport?
updateAgain: true, updateAgain: true, // Does the drawer need to update the viewort again?
//internal state / configurable settings //internal state / configurable settings
overlays: [], overlays: [], // An unordered list of Overlays added.
collectionOverlays: {}, collectionOverlays: {},
//configurable settings //configurable settings
@ -119,10 +106,33 @@ $.Drawer = function( options ) {
}, options ); }, options );
this.useCanvas = $.supportsCanvas && ( this.viewer ? this.viewer.useCanvas : true ); 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 ); 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" ); 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; 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; 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; this.element = this.container;
// We force our container to ltr because our drawing math doesn't work in rtl. // 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(); //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 * 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 * @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. * needs to be drawn. It it the responsibility of the callback to do any drawing/positioning.
* It is passed position, size and element. * It is passed position, size and element.
* @fires OpenSeadragon.Viewer.event:add-overlay
*/ */
addOverlay: function( element, location, placement, onDraw ) { addOverlay: function( element, location, placement, onDraw ) {
var options; var options;
@ -199,6 +210,18 @@ $.Drawer.prototype = {
}) ); }) );
this.updateAgain = true; this.updateAgain = true;
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'add-overlay', {
element: element, element: element,
location: options.location, location: options.location,
@ -218,6 +241,7 @@ $.Drawer.prototype = {
* viewport which the location coordinates will be treated as relative * viewport which the location coordinates will be treated as relative
* to. * to.
* @return {OpenSeadragon.Drawer} Chainable. * @return {OpenSeadragon.Drawer} Chainable.
* @fires OpenSeadragon.Viewer.event:update-overlay
*/ */
updateOverlay: function( element, location, placement ) { updateOverlay: function( element, location, placement ) {
var i; var i;
@ -230,6 +254,18 @@ $.Drawer.prototype = {
this.updateAgain = true; this.updateAgain = true;
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'update-overlay', {
element: element, element: element,
location: location, location: location,
@ -246,6 +282,7 @@ $.Drawer.prototype = {
* @param {Element|String} element - A reference to the element or an * @param {Element|String} element - A reference to the element or an
* element id which represent the ovelay content to be removed. * element id which represent the ovelay content to be removed.
* @return {OpenSeadragon.Drawer} Chainable. * @return {OpenSeadragon.Drawer} Chainable.
* @fires OpenSeadragon.Viewer.event:remove-overlay
*/ */
removeOverlay: function( element ) { removeOverlay: function( element ) {
var i; var i;
@ -259,6 +296,16 @@ $.Drawer.prototype = {
this.updateAgain = true; this.updateAgain = true;
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'remove-overlay', {
element: element element: element
}); });
@ -271,6 +318,7 @@ $.Drawer.prototype = {
* and update. * and update.
* @method * @method
* @return {OpenSeadragon.Drawer} Chainable. * @return {OpenSeadragon.Drawer} Chainable.
* @fires OpenSeadragon.Viewer.event:clear-overlay
*/ */
clearOverlays: function() { clearOverlays: function() {
while ( this.overlays.length > 0 ) { while ( this.overlays.length > 0 ) {
@ -278,6 +326,15 @@ $.Drawer.prototype = {
this.updateAgain = true; this.updateAgain = true;
} }
if( this.viewer ){ 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', {} ); this.viewer.raiseEvent( 'clear-overlay', {} );
} }
return this; return this;
@ -399,6 +456,11 @@ $.Drawer.prototype = {
return loading; return loading;
}, },
/**
* Returns whether rotation is supported or not.
* @method
* @return {Boolean} True if rotation is supported.
*/
canRotate: function() { canRotate: function() {
return this.useCanvas; return this.useCanvas;
} }
@ -471,6 +533,15 @@ function updateViewport( drawer ) {
drawer.updateAgain = false; drawer.updateAgain = false;
if( drawer.viewer ){ if( drawer.viewer ){
/**
* <em>- Needs documentation -</em>
*
* @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', {} ); drawer.viewer.raiseEvent( 'update-viewport', {} );
} }
@ -645,6 +716,23 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi
if( drawer.viewer ){ if( drawer.viewer ){
/**
* <em>- Needs documentation -</em>
*
* @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', { drawer.viewer.raiseEvent( 'update-level', {
havedrawn: haveDrawn, havedrawn: haveDrawn,
level: level, level: level,
@ -708,6 +796,16 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le
drawTile = drawLevel; drawTile = drawLevel;
if( drawer.viewer ){ if( drawer.viewer ){
/**
* <em>- Needs documentation -</em>
*
* @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', { drawer.viewer.raiseEvent( 'update-tile', {
tile: tile tile: tile
}); });
@ -1222,6 +1320,16 @@ function drawTiles( drawer, lastDrawn ){
} }
if( drawer.viewer ){ if( drawer.viewer ){
/**
* <em>- Needs documentation -</em>
*
* @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', { drawer.viewer.raiseEvent( 'tile-drawn', {
tile: tile tile: tile
}); });

9
src/dzitilesource.js
View File

@ -35,7 +35,8 @@
(function( $ ){ (function( $ ){
/** /**
* @class * @class DziTileSource
* @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @param {Number|Object} width - the pixel width of the image or the idiomatic * @param {Number|Object} width - the pixel width of the image or the idiomatic
* options object which is used instead of positional arguments. * 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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @function
* @name OpenSeadragon.DziTileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -118,7 +118,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.DziTileSource.prototype.configure
* @param {Object|XMLDocument} data - the raw configuration * @param {Object|XMLDocument} data - the raw configuration
* @param {String} url - the url the data was retreived from if any. * @param {String} url - the url the data was retreived from if any.
* @return {Object} options - A dictionary of keyword arguments sufficient * @return {Object} options - A dictionary of keyword arguments sufficient
@ -147,7 +146,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.DziTileSource.prototype.getTileUrl
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y
@ -159,7 +157,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.DziTileSource.prototype.tileExists
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

29
src/eventsource.js
View File

@ -35,22 +35,33 @@
(function($){ (function($){
/** /**
* For use by classes which want to support custom, non-browser events. * Event handler method signature used by all OpenSeadragon events.
* TODO: Add a method 'one' which automatically unbinds a listener after *
* the first triggered event that matches. * @callback EventHandler
* @class * @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() { $.EventSource = function() {
this.events = {}; 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. * Add an event handler for a given event.
* @function * @function
* @param {String} eventName - Name of event to register. * @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. * @param {Object} [userData=null] - Arbitrary object to be passed unchanged to the handler.
*/ */
addHandler: function ( eventName, handler, userData ) { addHandler: function ( eventName, handler, userData ) {
@ -67,7 +78,7 @@ $.EventSource.prototype = {
* Remove a specific event handler for a given event. * Remove a specific event handler for a given event.
* @function * @function
* @param {String} eventName - Name of event for which the handler is to be removed. * @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 ) { removeHandler: function ( eventName, handler ) {
var events = this.events[ eventName ], 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 * @function
* @param {String} eventName - Name of event to get handlers for. * @param {String} eventName - Name of event to get handlers for.
*/ */
@ -133,7 +144,7 @@ $.EventSource.prototype = {
* Trigger an event, optionally passing additional information. * Trigger an event, optionally passing additional information.
* @function * @function
* @param {String} eventName - Name of event to register. * @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 ) { raiseEvent: function( eventName, eventArgs ) {
//uncomment if you want to get a log of all events //uncomment if you want to get a log of all events

18
src/fullscreen.js
View File

@ -60,12 +60,20 @@
*/ */
/**
* Determines the appropriate level of native full screen support we can get
* from the browser.
* @name $.supportsFullScreen
*/
(function( $ ) { (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 = { var fullScreenApi = {
supportsFullScreen: false, supportsFullScreen: false,
isFullScreen: function() { return false; }, isFullScreen: function() { return false; },

13
src/iiif1_1tilesource.js
View File

@ -35,11 +35,11 @@
(function( $ ){ (function( $ ){
/** /**
* A client implementation of the International Image Interoperability * @class IIIF1_1TileSource
* Format: Image API 1.1 - Please read more about the specification * @classdesc A client implementation of the International Image Interoperability
* at * Format: Image API 1.1
* *
* @class * @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @see http://library.stanford.edu/iiif/image-api/ * @see http://library.stanford.edu/iiif/image-api/
*/ */
@ -74,12 +74,11 @@ $.IIIF1_1TileSource = function( options ){
$.TileSource.apply( this, [ 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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @function
* @name OpenSeadragon.IIIF1_1TileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -95,7 +94,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.IIIF1_1TileSource.prototype.configure
* @param {Object} data - the raw configuration * @param {Object} data - the raw configuration
*/ */
// IIIF 1.1 Info Looks like this (XML syntax is no more): // 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 * Responsible for retreiving the url which will return an image for the
* region specified by the given x, y, and level components. * region specified by the given x, y, and level components.
* @function * @function
* @name OpenSeadragon.IIIF1_1TileSource.prototype.getTileUrl
* @param {Number} level - z index * @param {Number} level - z index
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

89
src/iiiftilesource.js
View File

@ -42,11 +42,11 @@
(function( $ ){ (function( $ ){
/** /**
* A client implementation of the International Image Interoperability * @class IIIFTileSource
* Format: Image API Draft 0.2 - Please read more about the specification * @classdesc A client implementation of the International Image Interoperability
* at * Format: Image API Draft 0.2
* *
* @class * @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @see http://library.stanford.edu/iiif/image-api/ * @see http://library.stanford.edu/iiif/image-api/
*/ */
@ -81,12 +81,11 @@ $.IIIFTileSource = function( options ){
$.TileSource.apply( this, [ 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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @method
* @name OpenSeadragon.IIIFTileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -109,10 +108,9 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
); );
}, },
/** /**
* *
* @function * @method
* @name OpenSeadragon.IIIFTileSource.prototype.configure
* @param {Object|XMLDocument} data - the raw configuration * @param {Object|XMLDocument} data - the raw configuration
* @param {String} url - the url the data was retreived from if any. * @param {String} url - the url the data was retreived from if any.
* @return {Object} options - A dictionary of keyword arguments sufficient * @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 * Responsible for retreiving the url which will return an image for the
* region speified by the given x, y, and level components. * region speified by the given x, y, and level components.
* @function * @method
* @name OpenSeadragon.IIIFTileSource.prototype.getTileUrl
* @param {Number} level - z index * @param {Number} level - z index
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y
@ -215,28 +212,28 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
* @private * @private
* @inner * @inner
* @function * @function
* * @example
<?xml version="1.0" encoding="UTF-8"?> * <?xml version="1.0" encoding="UTF-8"?>
<info xmlns="http://library.stanford.edu/iiif/image-api/ns/"> * <info xmlns="http://library.stanford.edu/iiif/image-api/ns/">
<identifier>1E34750D-38DB-4825-A38A-B60A345E591C</identifier> * <identifier>1E34750D-38DB-4825-A38A-B60A345E591C</identifier>
<width>6000</width> * <width>6000</width>
<height>4000</height> * <height>4000</height>
<scale_factors> * <scale_factors>
<scale_factor>1</scale_factor> * <scale_factor>1</scale_factor>
<scale_factor>2</scale_factor> * <scale_factor>2</scale_factor>
<scale_factor>4</scale_factor> * <scale_factor>4</scale_factor>
</scale_factors> * </scale_factors>
<tile_width>1024</tile_width> * <tile_width>1024</tile_width>
<tile_height>1024</tile_height> * <tile_height>1024</tile_height>
<formats> * <formats>
<format>jpg</format> * <format>jpg</format>
<format>png</format> * <format>png</format>
</formats> * </formats>
<qualities> * <qualities>
<quality>native</quality> * <quality>native</quality>
<quality>grey</quality> * <quality>grey</quality>
</qualities> * </qualities>
</info> * </info>
*/ */
function configureFromXml( tileSource, xmlDoc ){ function configureFromXml( tileSource, xmlDoc ){
@ -306,18 +303,18 @@ function parseXML( node, configuration, property ){
* @private * @private
* @inner * @inner
* @function * @function
* * @example
{ * {
"profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1", * "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1",
"identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C", * "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C",
"width" : 6000, * "width" : 6000,
"height" : 4000, * "height" : 4000,
"scale_factors" : [ 1, 2, 4 ], * "scale_factors" : [ 1, 2, 4 ],
"tile_width" : 1024, * "tile_width" : 1024,
"tile_height" : 1024, * "tile_height" : 1024,
"formats" : [ "jpg", "png" ], * "formats" : [ "jpg", "png" ],
"quality" : [ "native", "grey" ] * "quality" : [ "native", "grey" ]
} * }
*/ */
function configureFromObject( tileSource, configuration ){ function configureFromObject( tileSource, configuration ){
//the image_host property is not part of the iiif standard but is included here to //the image_host property is not part of the iiif standard but is included here to

14
src/legacytilesource.js
View File

@ -35,13 +35,15 @@
(function( $ ){ (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 * into an OpenSeadragon Viewer. Basically, this translates to the historically
* common practice of starting with a 'master' image, maybe a tiff for example, * 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 * 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 * resolution image and a high resolution image in standard web formats like
* png or jpg. * png or jpg.
* @class *
* @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @param {Array} levels An array of file descriptions, each is an object with * @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 * a 'url', a 'width', and a 'height'. Overriding classes can expect more
@ -96,12 +98,11 @@ $.LegacyTileSource = function( levels ) {
this.levels = options.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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -119,7 +120,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.configure
* @param {Object|XMLDocument} configuration - the raw configuration * @param {Object|XMLDocument} configuration - the raw configuration
* @param {String} dataUrl - the url the data was retreived from if any. * @param {String} dataUrl - the url the data was retreived from if any.
* @return {Object} options - A dictionary of keyword arguments sufficient * @return {Object} options - A dictionary of keyword arguments sufficient
@ -144,7 +144,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.getLevelScale
* @param {Number} level * @param {Number} level
*/ */
getLevelScale: function ( level ) { getLevelScale: function ( level ) {
@ -159,7 +158,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.getNumTiles
* @param {Number} level * @param {Number} level
*/ */
getNumTiles: function( level ) { getNumTiles: function( level ) {
@ -173,7 +171,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.getTileAtPoint
* @param {Number} level * @param {Number} level
* @param {OpenSeadragon.Point} point * @param {OpenSeadragon.Point} point
*/ */
@ -188,7 +185,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
* server technologies, and various specifications for building image * server technologies, and various specifications for building image
* pyramids, this method is here to allow easy integration. * pyramids, this method is here to allow easy integration.
* @function * @function
* @name OpenSeadragon.LegacyTileSource.prototype.getTileUrl
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

115
src/mousetracker.js
View File

@ -46,17 +46,19 @@
THIS = {}; THIS = {};
/** /**
* The MouseTracker allows other classes to set handlers for common mouse * @class MouseTracker
* events on a specific element like, 'enter', 'exit', 'press', 'release', * @classdesc Provides simplified handling of common mouse, touch, and keyboard
* events on a specific element, like 'enter', 'exit', 'press', 'release',
* 'scroll', 'click', and 'drag'. * 'scroll', 'click', and 'drag'.
* @class *
* @memberof OpenSeadragon
* @param {Object} options * @param {Object} options
* Allows configurable properties to be entirely specified by passing * Allows configurable properties to be entirely specified by passing
* an options object to the constructor. The constructor also supports * 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. * and 'clickDistThreshold' in that order.
* @param {Element|String} options.element * @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. * events will be monitored.
* @param {Number} options.clickTimeThreshold * @param {Number} options.clickTimeThreshold
* The number of milliseconds within which multiple mouse clicks * The number of milliseconds within which multiple mouse clicks
@ -64,43 +66,33 @@
* @param {Number} options.clickDistThreshold * @param {Number} options.clickDistThreshold
* The distance between mouse click within multiple mouse clicks * The distance between mouse click within multiple mouse clicks
* will be treated as a single event. * 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 * The number of milliseconds without mouse move before the mouse stop
* event is fired. * event is fired.
* @param {Function} options.enterHandler * @param {OpenSeadragon.EventHandler} [options.enterHandler=null]
* An optional handler for mouse enter. * An optional handler for mouse enter.
* @param {Function} options.exitHandler * @param {OpenSeadragon.EventHandler} [options.exitHandler=null]
* An optional handler for mouse exit. * An optional handler for mouse exit.
* @param {Function} options.pressHandler * @param {OpenSeadragon.EventHandler} [options.pressHandler=null]
* An optional handler for mouse press. * An optional handler for mouse press.
* @param {Function} options.releaseHandler * @param {OpenSeadragon.EventHandler} [options.releaseHandler=null]
* An optional handler for mouse release. * An optional handler for mouse release.
* @param {Function} options.moveHandler * @param {OpenSeadragon.EventHandler} [options.moveHandler=null]
* An optional handler for mouse move. * An optional handler for mouse move.
* @param {Function} options.scrollHandler * @param {OpenSeadragon.EventHandler} [options.scrollHandler=null]
* An optional handler for mouse scroll. * An optional handler for mouse scroll.
* @param {Function} options.clickHandler * @param {OpenSeadragon.EventHandler} [options.clickHandler=null]
* An optional handler for mouse click. * An optional handler for mouse click.
* @param {Function} options.dragHandler * @param {OpenSeadragon.EventHandler} [options.dragHandler=null]
* An optional handler for mouse drag. * An optional handler for mouse drag.
* @param {Function} options.keyHandler * @param {OpenSeadragon.EventHandler} [options.keyHandler=null]
* An optional handler for keypress. * An optional handler for keypress.
* @param {Function} options.focusHandler * @param {OpenSeadragon.EventHandler} [options.focusHandler=null]
* An optional handler for focus. * An optional handler for focus.
* @param {Function} options.blurHandler * @param {OpenSeadragon.EventHandler} [options.blurHandler=null]
* An optional handler for blur. * An optional handler for blur.
* @param {Object} [options.userData=null] * @param {Object} [options.userData=null]
* Arbitrary object to be passed unchanged to any attached handler methods. * 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 ) { $.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 ); 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; 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.clickDistThreshold = options.clickDistThreshold;
this.userData = options.userData || null; this.userData = options.userData || null;
this.stopDelay = options.stopDelay || 50; 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. * 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. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -268,8 +275,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -288,8 +295,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -313,8 +320,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -333,8 +340,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -357,8 +364,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -374,15 +381,15 @@
* @param {OpenSeadragon.Point} event.position * @param {OpenSeadragon.Point} event.position
* The position of the event relative to the tracked element. * The position of the event relative to the tracked element.
* @param {Number} event.quick * @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 * @param {Boolean} event.shift
* True if the shift key was pressed during this event. * True if the shift key was pressed during this event.
* @param {Boolean} event.isTouchEvent * @param {Boolean} event.isTouchEvent
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -405,8 +412,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -425,8 +432,8 @@
* True if the original event is a touch event, otherwise false. * True if the original event is a touch event, otherwise false.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -445,8 +452,8 @@
* True if the shift key was pressed during this event. * True if the shift key was pressed during this event.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -461,8 +468,8 @@
* A reference to the tracker instance. * A reference to the tracker instance.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */
@ -477,8 +484,8 @@
* A reference to the tracker instance. * A reference to the tracker instance.
* @param {Object} event.originalEvent * @param {Object} event.originalEvent
* The original event object. * The original event object.
* @param {Boolean} [event.preventDefaultAction=false] * @param {Boolean} event.preventDefaultAction
* Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). * Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
* @param {Object} event.userData * @param {Object} event.userData
* Arbitrary user-defined object. * Arbitrary user-defined object.
*/ */

11
src/navigator.js
View File

@ -35,17 +35,17 @@
(function( $ ){ (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 * 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 * of reference in the larger viewport as to which portion of the image
* is currently being examined. The navigator's viewport can be interacted * is currently being examined. The navigator's viewport can be interacted
* with using the keyboard or the mouse. * with using the keyboard or the mouse.
* @class *
* @name OpenSeadragon.Navigator * @memberof OpenSeadragon
* @extends OpenSeadragon.Viewer * @extends OpenSeadragon.Viewer
* @extends OpenSeadragon.EventSource * @extends OpenSeadragon.EventSource
* @param {Object} options * @param {Object} options
* @param {String} options.viewerId
*/ */
$.Navigator = function( options ){ $.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 * @function
* @name OpenSeadragon.Navigator.prototype.update
*/ */
update: function( viewport ){ update: function( viewport ){

573
src/openseadragon.js
View File

@ -82,45 +82,53 @@
*/ */
/**
* @version <%= pkg.name %> <%= pkg.version %>
*
* @file
* <h2><strong>OpenSeadragon - Javascript Deep Zooming</strong></h2>
* <p>
* 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.
* </p>
*
*/
/**
* @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 * @typedef {Object} Options
* <h2> * @memberof OpenSeadragon
* <strong>
* OpenSeadragon - Javascript Deep Zooming
* </strong>
* </h2>
* <p>
* 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.
* </p>
*/
/**
* 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.
* *
* @namespace * @property {String} id
* @function * Id of the element to append the viewer's container element to. If not provided, the 'element' property must be provided.
* @name OpenSeadragon * If both the element and id properties are specified, the viewer is appended to the element provided in the element property.
* @exports $ as OpenSeadragon
* *
* @param {Object} options All required and optional settings for instantiating * @property {Element} element
* a new instance of an OpenSeadragon image viewer. * 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 * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null]
* DEPRECATED. A relative path to load a DZI file from the server. * As an Array, the tileSource can hold either Objects or mixed
* Prefer the newer options.tileSources. * types of Arrays of Objects, Strings, or Functions. When a value is a String,
*
* @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,
* the tileSource is used to create a {@link OpenSeadragon.DziTileSource}. * the tileSource is used to create a {@link OpenSeadragon.DziTileSource}.
* When a value is a Function, the function is used to create a new * When a value is a Function, the function is used to create a new
* {@link OpenSeadragon.TileSource} whose abstract method * {@link OpenSeadragon.TileSource} whose abstract method
@ -128,144 +136,273 @@
* is an Array of objects, it is used to create a * is an Array of objects, it is used to create a
* {@link OpenSeadragon.LegacyTileSource}. * {@link OpenSeadragon.LegacyTileSource}.
* *
* @param {Boolean} [options.debugMode=true] * @property {String} [xmlPath=null]
* Currently does nothing. TODO: provide an in-screen panel providing event * <strong>DEPRECATED</strong>. A relative path to load a DZI file from the server.
* detail feedback. * Prefer the newer Options.tileSources.
* *
* @param {Number} [options.animationTime=1.5] * @property {String} [prefixUrl='/images/']
* 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 {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/']
* Prepends the prefixUrl to navImages paths, which is very useful * Prepends the prefixUrl to navImages paths, which is very useful
* since the default paths are rarely useful for production * since the default paths are rarely useful for production
* environments. * environments.
* *
* @param {Object} [options.navImages=] * @property {OpenSeadragon.NavImages} [navImages]
* An object with a property for each button or other built-in navigation * An object with a property for each button or other built-in navigation
* control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'. * 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 * or navigation control, eg 'REST', 'GROUP', 'HOVER', 'PRESS'. Finally the
* image paths, by default assume there is a folder on the servers root path * 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 * called '/images', eg '/images/zoomin_rest.png'. If you need to adjust
* these paths, prefer setting the option.prefixUrl rather than overriding * these paths, prefer setting the option.prefixUrl rather than overriding
* every image path directly through this setting. * 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 {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. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the click-to-zoom feature.</em>
*
* @property {Number} [zoomPerScroll=1.2]
* The "zoom distance" per mouse scroll or touch pinch. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the mouse-wheel zoom feature.</em>
*
* @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 * 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 * image and if the 'next' button will wrap to the first image when viewing
* the last image. * 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} * @returns {OpenSeadragon.Viewer}
*/ */
window.OpenSeadragon = window.OpenSeadragon || function( options ){ window.OpenSeadragon = window.OpenSeadragon || function( options ){
@ -274,6 +411,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
}; };
(function( $ ){ (function( $ ){
@ -298,9 +436,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.isFunction * @function isFunction
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.isFunction = function( obj ) { $.isFunction = function( obj ) {
return $.type(obj) === "function"; return $.type(obj) === "function";
@ -309,9 +447,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.isArray * @function isArray
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.isArray = Array.isArray || function( obj ) { $.isArray = Array.isArray || function( obj ) {
return $.type(obj) === "array"; return $.type(obj) === "array";
@ -321,9 +459,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* A crude way of determining if an object is a window. * A crude way of determining if an object is a window.
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.isWindow * @function isWindow
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.isWindow = function( obj ) { $.isWindow = function( obj ) {
return obj && typeof obj === "object" && "setInterval" in obj; return obj && typeof obj === "object" && "setInterval" in obj;
@ -332,9 +470,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.type * @function type
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.type = function( obj ) { $.type = function( obj ) {
return ( obj === null ) || ( obj === undefined ) ? return ( obj === null ) || ( obj === undefined ) ?
@ -345,9 +483,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.isPlainObject * @function isPlainObject
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.isPlainObject = function( obj ) { $.isPlainObject = function( obj ) {
// Must be an Object. // Must be an Object.
@ -376,9 +514,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @name $.isEmptyObject * @function isEmptyObject
* @function * @memberof OpenSeadragon
* @see <a href='http://www.jquery.com/'>jQuery</a> * @see {@link http://www.jquery.com/ jQuery}
*/ */
$.isEmptyObject = function( obj ) { $.isEmptyObject = function( obj ) {
for ( var name in obj ) { for ( var name in obj ) {
@ -390,8 +528,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* True if the browser supports the HTML5 canvas element * True if the browser supports the HTML5 canvas element
* @name $.supportsCanvas * @member {Boolean} supportsCanvas
* @property * @memberof OpenSeadragon
*/ */
$.supportsCanvas = (function () { $.supportsCanvas = (function () {
var canvasElement = document.createElement( 'canvas' ); var canvasElement = document.createElement( 'canvas' );
@ -418,7 +556,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @see <a href='http://www.jquery.com/'>jQuery</a> * @function extend
* @memberof OpenSeadragon
* @see {@link http://www.jquery.com/ jQuery}
*/ */
$.extend = function() { $.extend = function() {
var options, var options,
@ -491,12 +631,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
}; };
$.extend( $, { $.extend( $, /** @lends OpenSeadragon */{
/** /**
* These are the default values for the optional settings documented * The default values for the optional settings documented at {@link OpenSeadragon.Options}.
* in the {@link OpenSeadragon} constructor detail.
* @name $.DEFAULT_SETTINGS
* @static * @static
* @type {Object}
*/ */
DEFAULT_SETTINGS: { DEFAULT_SETTINGS: {
//DATA SOURCE DETAILS //DATA SOURCE DETAILS
@ -631,11 +770,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Invokes the the method as if it where a method belonging to the object. * Returns a function which invokes the method as if it were a method belonging to the object.
* @name $.delegate
* @function * @function
* @param {Object} object * @param {Object} object
* @param {Function} method * @param {Function} method
* @returns {Function}
*/ */
delegate: function( object, method ) { delegate: function( object, method ) {
return function(){ return function(){
@ -649,10 +788,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* An enumeration of Browser vendors including UNKNOWN, IE, FIREFOX, * An enumeration of Browser vendors.
* SAFARI, CHROME, and OPERA.
* @name $.BROWSERS
* @static * @static
* @type {Object}
* @property {Number} UNKNOWN
* @property {Number} IE
* @property {Number} FIREFOX
* @property {Number} SAFARI
* @property {Number} CHROME
* @property {Number} OPERA
*/ */
BROWSERS: { BROWSERS: {
UNKNOWN: 0, UNKNOWN: 0,
@ -667,7 +811,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Returns a DOM Element for the given id or element. * Returns a DOM Element for the given id or element.
* @function * @function
* @name OpenSeadragon.getElement
* @param {String|Element} element Accepts an id or element. * @param {String|Element} element Accepts an id or element.
* @returns {Element} The element with the given id, null, or the element itself. * @returns {Element} The element with the given id, null, or the element itself.
*/ */
@ -682,9 +825,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Determines the position of the upper-left corner of the element. * Determines the position of the upper-left corner of the element.
* @function * @function
* @name OpenSeadragon.getElementPosition
* @param {Element|String} element - the elemenet we want the position for. * @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 ) { getElementPosition: function( element ) {
var result = new $.Point(), var result = new $.Point(),
@ -716,9 +858,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. * Determines the position of the upper-left corner of the element adjusted for current page and/or element scroll.
* @function * @function
* @name OpenSeadragon.getElementOffset
* @param {Element|String} element - the element we want the position for. * @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 ) { getElementOffset: function( element ) {
element = $.getElement( element ); element = $.getElement( element );
@ -754,9 +895,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Determines the height and width of the given element. * Determines the height and width of the given element.
* @function * @function
* @name OpenSeadragon.getElementSize
* @param {Element|String} element * @param {Element|String} element
* @returns {Point} * @returns {OpenSeadragon.Point}
*/ */
getElementSize: function( element ) { getElementSize: function( element ) {
element = $.getElement( element ); element = $.getElement( element );
@ -771,7 +911,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Returns the CSSStyle object for the given element. * Returns the CSSStyle object for the given element.
* @function * @function
* @name OpenSeadragon.getElementStyle
* @param {Element|String} element * @param {Element|String} element
* @returns {CSSStyle} * @returns {CSSStyle}
*/ */
@ -789,12 +928,12 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Gets the latest event, really only useful internally since its * Gets the latest event, really only useful internally since its
* specific to IE behavior. TODO: Deprecate this from the api and * specific to IE behavior.
* use it internally.
* @function * @function
* @name OpenSeadragon.getEvent
* @param {Event} [event] * @param {Event} [event]
* @returns {Event} * @returns {Event}
* @deprecated For internal use only
* @private
*/ */
getEvent: function( event ) { getEvent: function( event ) {
if( event ){ if( event ){
@ -813,9 +952,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Gets the position of the mouse on the screen for a given event. * Gets the position of the mouse on the screen for a given event.
* @function * @function
* @name OpenSeadragon.getMousePosition
* @param {Event} [event] * @param {Event} [event]
* @returns {Point} * @returns {OpenSeadragon.Point}
*/ */
getMousePosition: function( event ) { getMousePosition: function( event ) {
@ -858,8 +996,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Determines the page's current scroll position. * Determines the page's current scroll position.
* @function * @function
* @name OpenSeadragon.getPageScroll * @returns {OpenSeadragon.Point}
* @returns {Point}
*/ */
getPageScroll: function() { getPageScroll: function() {
var docElement = document.documentElement || {}, var docElement = document.documentElement || {},
@ -897,8 +1034,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Set the page scroll position. * Set the page scroll position.
* @function * @function
* @name OpenSeadragon.getPageScroll * @returns {OpenSeadragon.Point}
* @returns {Point}
*/ */
setPageScroll: function( scroll ) { setPageScroll: function( scroll ) {
if ( typeof ( window.scrollTo ) !== "undefined" ) { if ( typeof ( window.scrollTo ) !== "undefined" ) {
@ -949,8 +1085,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Determines the size of the browsers window. * Determines the size of the browsers window.
* @function * @function
* @name OpenSeadragon.getWindowSize * @returns {OpenSeadragon.Point}
* @returns {Point}
*/ */
getWindowSize: function() { getWindowSize: function() {
var docElement = document.documentElement || {}, var docElement = document.documentElement || {},
@ -989,7 +1124,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Wraps the given element in a nest of divs so that the element can * Wraps the given element in a nest of divs so that the element can
* be easily centered using CSS tables * be easily centered using CSS tables
* @function * @function
* @name OpenSeadragon.makeCenteredNode
* @param {Element|String} element * @param {Element|String} element
* @returns {Element} outermost wrapper element * @returns {Element} outermost wrapper element
*/ */
@ -1037,7 +1171,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Creates an easily positionable element of the given type that therefor * Creates an easily positionable element of the given type that therefor
* serves as an excellent container element. * serves as an excellent container element.
* @function * @function
* @name OpenSeadragon.makeNeutralElement
* @param {String} tagName * @param {String} tagName
* @returns {Element} * @returns {Element}
*/ */
@ -1057,7 +1190,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Returns the current milliseconds, using Date.now() if available * Returns the current milliseconds, using Date.now() if available
* @name $.now
* @function * @function
*/ */
now: function( ) { now: function( ) {
@ -1076,7 +1208,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Generally only IE has issues doing this correctly for formats like * Generally only IE has issues doing this correctly for formats like
* png. * png.
* @function * @function
* @name OpenSeadragon.makeTransparentImage
* @param {String} src * @param {String} src
* @returns {Element} * @returns {Element}
*/ */
@ -1125,7 +1256,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Sets the opacity of the specified element. * Sets the opacity of the specified element.
* @function * @function
* @name OpenSeadragon.setElementOpacity
* @param {Element|String} element * @param {Element|String} element
* @param {Number} opacity * @param {Number} opacity
* @param {Boolean} [usesAlpha] * @param {Boolean} [usesAlpha]
@ -1157,7 +1287,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Add the specified CSS class to the element if not present. * Add the specified CSS class to the element if not present.
* @name $.addClass
* @function * @function
* @param {Element|String} element * @param {Element|String} element
* @param {String} className * @param {String} className
@ -1176,7 +1305,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Remove the specified CSS class from the element. * Remove the specified CSS class from the element.
* @name $.removeClass
* @function * @function
* @param {Element|String} element * @param {Element|String} element
* @param {String} className * @param {String} className
@ -1200,7 +1328,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Adds an event listener for the given element, eventName and handler. * Adds an event listener for the given element, eventName and handler.
* @function * @function
* @name OpenSeadragon.addEvent
* @param {Element|String} element * @param {Element|String} element
* @param {String} eventName * @param {String} eventName
* @param {Function} handler * @param {Function} handler
@ -1230,7 +1357,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Remove a given event listener for the given element, event type and * Remove a given event listener for the given element, event type and
* handler. * handler.
* @function * @function
* @name OpenSeadragon.removeEvent
* @param {Element|String} element * @param {Element|String} element
* @param {String} eventName * @param {String} eventName
* @param {Function} handler * @param {Function} handler
@ -1260,7 +1386,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Cancels the default browser behavior had the event propagated all * Cancels the default browser behavior had the event propagated all
* the way up the DOM to the window object. * the way up the DOM to the window object.
* @function * @function
* @name OpenSeadragon.cancelEvent
* @param {Event} [event] * @param {Event} [event]
*/ */
cancelEvent: function( event ) { cancelEvent: function( event ) {
@ -1287,7 +1412,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Stops the propagation of the event up the DOM. * Stops the propagation of the event up the DOM.
* @function * @function
* @name OpenSeadragon.stopEvent
* @param {Event} [event] * @param {Event} [event]
*/ */
stopEvent: function( event ) { stopEvent: function( event ) {
@ -1319,7 +1443,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* invocation, and each invocation can add additional arguments as well. * invocation, and each invocation can add additional arguments as well.
* *
* @function * @function
* @name OpenSeadragon.createCallback
* @param {Object} object * @param {Object} object
* @param {Function} method * @param {Function} method
* @param [args] any additional arguments are passed as arguments to the * @param [args] any additional arguments are passed as arguments to the
@ -1351,7 +1474,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Retreives the value of a url parameter from the window.location string. * Retreives the value of a url parameter from the window.location string.
* @function * @function
* @name OpenSeadragon.getUrlParameter
* @param {String} key * @param {String} key
* @returns {String} The value of the url parameter or null if no param matches. * @returns {String} The value of the url parameter or null if no param matches.
*/ */
@ -1396,7 +1518,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Makes an AJAX request. * Makes an AJAX request.
* @function * @function
* @name OpenSeadragon.makeAjaxRequest
* @param {String} url - the url to request * @param {String} url - the url to request
* @param {Function} onSuccess - a function to call on a successful response * @param {Function} onSuccess - a function to call on a successful response
* @param {Function} onError - a function to call on when an error occurs * @param {Function} onError - a function to call on when an error occurs
@ -1461,7 +1582,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Taken from jQuery 1.6.1 * Taken from jQuery 1.6.1
* @function * @function
* @name OpenSeadragon.jsonp
* @param {Object} options * @param {Object} options
* @param {String} options.url * @param {String} options.url
* @param {Function} options.callback * @param {Function} options.callback
@ -1542,8 +1662,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Fully deprecated. Will throw an error. * Fully deprecated. Will throw an error.
* @function * @function
* @name OpenSeadragon.createFromDZI * @deprecated use {@link OpenSeadragon.Viewer#open}
* @deprecated - use OpenSeadragon.Viewer.prototype.open
*/ */
createFromDZI: function() { createFromDZI: function() {
throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open."; throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open.";
@ -1552,7 +1671,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* Parses an XML string into a DOM Document. * Parses an XML string into a DOM Document.
* @function * @function
* @name OpenSeadragon.parseXml
* @param {String} string * @param {String} string
* @returns {Document} * @returns {Document}
*/ */
@ -1594,7 +1712,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
* Reports whether the image format is supported for tiling in this * Reports whether the image format is supported for tiling in this
* version. * version.
* @function * @function
* @name OpenSeadragon.imageFormatSupported
* @param {String} [extension] * @param {String} [extension]
* @returns {Boolean} * @returns {Boolean}
*/ */
@ -1607,12 +1724,14 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
/** /**
* The current browser vendor, version, and related information regarding * The current browser vendor, version, and related information regarding detected features.
* detected features. Features include <br/> * @member {Object} Browser
* <strong>'alpha'</strong> - Does the browser support image alpha * @memberof OpenSeadragon
* transparency.<br/>
* @name $.Browser
* @static * @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 = { $.Browser = {
vendor: $.BROWSERS.UNKNOWN, vendor: $.BROWSERS.UNKNOWN,

12
src/osmtilesource.js
View File

@ -43,12 +43,13 @@
(function( $ ){ (function( $ ){
/** /**
* A tilesource implementation for OpenStreetMap. * @class OsmTileSource
* @classdesc A tilesource implementation for OpenStreetMap.<br><br>
* *
* Note 1. Zoomlevels. Deep Zoom and OSM define zoom levels differently. In Deep * 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 * 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 * 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.<br><br>
* *
* Note 2. Image dimension. According to the OSM Wiki * Note 2. Image dimension. According to the OSM Wiki
* (http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Zoom_levels) * (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 * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864
* pixels. * pixels.
* *
* @class * @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @param {Number|Object} width - the pixel width of the image or the idiomatic * @param {Number|Object} width - the pixel width of the image or the idiomatic
* options object which is used instead of positional arguments. * 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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @function
* @name OpenSeadragon.OsmTileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -120,7 +120,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.OsmTileSource.prototype.configure
* @param {Object} data - the raw configuration * @param {Object} data - the raw configuration
* @param {String} url - the url the data was retreived from if any. * @param {String} url - the url the data was retreived from if any.
* @return {Object} options - A dictionary of keyword arguments sufficient * @return {Object} options - A dictionary of keyword arguments sufficient
@ -133,7 +132,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.OsmTileSource.prototype.getTileUrl
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

39
src/overlay.js
View File

@ -35,10 +35,20 @@
(function( $ ){ (function( $ ){
/** /**
* An enumeration of positions that an overlay may be assigned relative * An enumeration of positions that an overlay may be assigned relative to the viewport.
* to the viewport including CENTER, TOP_LEFT (default), TOP, TOP_RIGHT, * @member OverlayPlacement
* RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT. * @memberof OpenSeadragon
* @static * @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 = { $.OverlayPlacement = {
CENTER: 0, CENTER: 0,
@ -53,11 +63,28 @@
}; };
/** /**
* An Overlay provides a * @class Overlay
* @class * @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 ) { $.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; var options;
if( $.isPlainObject( element ) ){ if( $.isPlainObject( element ) ){
options = element; options = element;
@ -93,7 +120,7 @@
this.onDraw = options.onDraw; this.onDraw = options.onDraw;
}; };
$.Overlay.prototype = { $.Overlay.prototype = /** @lends OpenSeadragon.Overlay.prototype */{
/** /**
* @function * @function

20
src/point.js
View File

@ -35,21 +35,31 @@
(function( $ ){ (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 * representing a point on a plane, or the height and width of a plane
* not requiring any other frame of reference. * 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} [x] The vector component 'x'. Defaults to the origin at 0.
* @param {Number} [y] The vector component 'y'. 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 ) { $.Point = function( x, y ) {
/**
* The vector component 'x'.
* @member {Number} x
* @memberof OpenSeadragon.Point#
*/
this.x = typeof ( x ) == "number" ? x : 0; this.x = typeof ( x ) == "number" ? x : 0;
/**
* The vector component 'y'.
* @member {Number} y
* @memberof OpenSeadragon.Point#
*/
this.y = typeof ( y ) == "number" ? y : 0; 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. * Add another Point to this point and return a new Point.

8
src/profiler.js
View File

@ -35,9 +35,11 @@
(function( $ ){ (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. * metrics of rendering routines.
* @class *
* @memberof OpenSeadragon
* @property {Boolean} midUpdate * @property {Boolean} midUpdate
* @property {Number} numUpdates * @property {Number} numUpdates
* @property {Number} lastBeginTime * @property {Number} lastBeginTime
@ -66,7 +68,7 @@ $.Profiler = function() {
this.maxIdleTime = 0; this.maxIdleTime = 0;
}; };
$.Profiler.prototype = { $.Profiler.prototype = /** @lends OpenSeadragon.Profiler.prototype */{
/** /**
* @function * @function

31
src/rectangle.js
View File

@ -35,29 +35,46 @@
(function( $ ){ (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 * 2 dimensional vector component, the first is (x,y) and the second is
* (width, height). The latter component implies the equation of a simple * (width, height). The latter component implies the equation of a simple
* plane. * plane.
* *
* @class * @memberof OpenSeadragon
* @param {Number} x The vector component 'x'. * @param {Number} x The vector component 'x'.
* @param {Number} y The vector component 'y'. * @param {Number} y The vector component 'y'.
* @param {Number} width The vector component 'height'. * @param {Number} width The vector component 'height'.
* @param {Number} height The vector component 'width'. * @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 ) { $.Rect = function( x, y, width, height ) {
/**
* The vector component 'x'.
* @member {Number} x
* @memberof OpenSeadragon.Rect#
*/
this.x = typeof ( x ) == "number" ? x : 0; this.x = typeof ( x ) == "number" ? x : 0;
/**
* The vector component 'y'.
* @member {Number} y
* @memberof OpenSeadragon.Rect#
*/
this.y = typeof ( y ) == "number" ? y : 0; this.y = typeof ( y ) == "number" ? y : 0;
/**
* The vector component 'width'.
* @member {Number} width
* @memberof OpenSeadragon.Rect#
*/
this.width = typeof ( width ) == "number" ? width : 0; this.width = typeof ( width ) == "number" ? width : 0;
/**
* The vector component 'height'.
* @member {Number} height
* @memberof OpenSeadragon.Rect#
*/
this.height = typeof ( height ) == "number" ? height : 0; 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. * The aspect ratio is simply the ratio of width to height.

12
src/referencestrip.js
View File

@ -56,6 +56,11 @@ var THIS = {};
* require better abstraction at those points in order to effeciently * require better abstraction at those points in order to effeciently
* reuse those paradigms. * reuse those paradigms.
*/ */
/**
* @class ReferenceStrip
* @memberof OpenSeadragon
* @param {Object} options
*/
$.ReferenceStrip = function ( options ) { $.ReferenceStrip = function ( options ) {
var _this = this, 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 ) { setFocus: function ( page ) {
var element = $.getElement( this.element.id + '-' + page ), var element = $.getElement( this.element.id + '-' + page ),
viewerSize = $.getElementSize( this.viewer.canvas ), viewerSize = $.getElementSize( this.viewer.canvas ),
@ -268,9 +276,9 @@ $.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototyp
onStripEnter.call( this, { eventSource: this.innerTracker } ); onStripEnter.call( this, { eventSource: this.innerTracker } );
} }
}, },
/** /**
* @function * @function
* @name OpenSeadragon.ReferenceStrip.prototype.update
*/ */
update: function () { update: function () {
if ( THIS[this.id].animating ) { if ( THIS[this.id].animating ) {

42
src/spring.js
View File

@ -35,20 +35,13 @@
(function( $ ){ (function( $ ){
/** /**
* @class * @class Spring
* @memberof OpenSeadragon
* @param {Object} options - Spring configuration settings. * @param {Object} options - Spring configuration settings.
* @param {Number} options.initial - Initial value of spring, default to 0 so * @param {Number} options.initial - Initial value of spring, default to 0 so
* spring is not in motion initally by default. * spring is not in motion initally by default.
* @param {Number} options.springStiffness - Spring stiffness. * @param {Number} options.springStiffness - Spring stiffness.
* @param {Number} options.animationTime - Animation duration per spring. * @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 ) { $.Spring = function( options ) {
var args = arguments; var args = arguments;
@ -60,9 +53,19 @@ $.Spring = function( options ) {
initial: args.length && typeof ( args[ 0 ] ) == "number" ? initial: args.length && typeof ( args[ 0 ] ) == "number" ?
args[ 0 ] : args[ 0 ] :
0, 0,
/**
* Spring stiffness.
* @member {Number} springStiffness
* @memberof OpenSeadragon.Spring#
*/
springStiffness: args.length > 1 ? springStiffness: args.length > 1 ?
args[ 1 ].springStiffness : args[ 1 ].springStiffness :
5.0, 5.0,
/**
* Animation duration per spring.
* @member {Number} animationTime
* @memberof OpenSeadragon.Spring#
*/
animationTime: args.length > 1 ? animationTime: args.length > 1 ?
args[ 1 ].animationTime : args[ 1 ].animationTime :
1.5 1.5
@ -71,7 +74,12 @@ $.Spring = function( options ) {
$.extend( true, this, options); $.extend( true, this, options);
/**
* @member {Object} current
* @memberof OpenSeadragon.Spring#
* @property {Number} value
* @property {Number} time
*/
this.current = { this.current = {
value: typeof ( this.initial ) == "number" ? value: typeof ( this.initial ) == "number" ?
this.initial : this.initial :
@ -79,18 +87,30 @@ $.Spring = function( options ) {
time: $.now() // always work in milliseconds time: $.now() // always work in milliseconds
}; };
/**
* @member {Object} start
* @memberof OpenSeadragon.Spring#
* @property {Number} value
* @property {Number} time
*/
this.start = { this.start = {
value: this.current.value, value: this.current.value,
time: this.current.time time: this.current.time
}; };
/**
* @member {Object} target
* @memberof OpenSeadragon.Spring#
* @property {Number} value
* @property {Number} time
*/
this.target = { this.target = {
value: this.current.value, value: this.current.value,
time: this.current.time time: this.current.time
}; };
}; };
$.Spring.prototype = { $.Spring.prototype = /** @lends OpenSeadragon.Spring.prototype */{
/** /**
* @function * @function

4
src/strings.js
View File

@ -59,11 +59,10 @@ var I18N = {
} }
}; };
$.extend( $, { $.extend( $, /** @lends OpenSeadragon */{
/** /**
* @function * @function
* @name OpenSeadragon.getString
* @param {String} property * @param {String} property
*/ */
getString: function( prop ) { getString: function( prop ) {
@ -95,7 +94,6 @@ $.extend( $, {
/** /**
* @function * @function
* @name OpenSeadragon.setString
* @param {String} property * @param {String} property
* @param {*} value * @param {*} value
*/ */

128
src/tile.js
View File

@ -35,7 +35,8 @@
(function( $ ){ (function( $ ){
var TILE_CACHE = {}; var TILE_CACHE = {};
/** /**
* @class * @class Tile
* @memberof OpenSeadragon
* @param {Number} level The zoom level this tile belongs to. * @param {Number} level The zoom level this tile belongs to.
* @param {Number} x The vector component 'x'. * @param {Number} x The vector component 'x'.
* @param {Number} y The vector component 'y'. * @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 * @param {Boolean} exists Is this tile a part of a sparse image? ( Also has
* this tile failed to load? ) * this tile failed to load? )
* @param {String} url The URL of this tile's image. * @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) { $.Tile = function(level, x, y, bounds, exists, url) {
/**
* The zoom level this tile belongs to.
* @member {Number} level
* @memberof OpenSeadragon.Tile#
*/
this.level = level; this.level = level;
/**
* The vector component 'x'.
* @member {Number} x
* @memberof OpenSeadragon.Tile#
*/
this.x = x; this.x = x;
/**
* The vector component 'y'.
* @member {Number} y
* @memberof OpenSeadragon.Tile#
*/
this.y = y; this.y = y;
/**
* Where this tile fits, in normalized coordinates
* @member {OpenSeadragon.Point} bounds
* @memberof OpenSeadragon.Tile#
*/
this.bounds = bounds; 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; this.exists = exists;
/**
* The URL of this tile's image.
* @member {String} url
* @memberof OpenSeadragon.Tile#
*/
this.url = url; this.url = url;
/**
* Is this tile loaded?
* @member {Boolean} loaded
* @memberof OpenSeadragon.Tile#
*/
this.loaded = false; this.loaded = false;
/**
* Is this tile loading?
* @member {Boolean} loading
* @memberof OpenSeadragon.Tile#
*/
this.loading = false; this.loading = false;
/**
* The HTML div element for this tile
* @member {Element} element
* @memberof OpenSeadragon.Tile#
*/
this.element = null; this.element = null;
/**
* The HTML img element for this tile.
* @member {Element} imgElement
* @memberof OpenSeadragon.Tile#
*/
this.imgElement = null; this.imgElement = null;
/**
* The Image object for this tile.
* @member {Object} image
* @memberof OpenSeadragon.Tile#
*/
this.image = null; this.image = null;
/**
* The alias of this.element.style.
* @member {String} style
* @memberof OpenSeadragon.Tile#
*/
this.style = null; this.style = null;
/**
* This tile's position on screen, in pixels.
* @member {OpenSeadragon.Point} position
* @memberof OpenSeadragon.Tile#
*/
this.position = null; this.position = null;
/**
* This tile's size on screen, in pixels.
* @member {OpenSeadragon.Point} size
* @memberof OpenSeadragon.Tile#
*/
this.size = null; this.size = null;
/**
* The start time of this tile's blending.
* @member {Number} blendStart
* @memberof OpenSeadragon.Tile#
*/
this.blendStart = null; this.blendStart = null;
/**
* The current opacity this tile should be.
* @member {Number} opacity
* @memberof OpenSeadragon.Tile#
*/
this.opacity = null; this.opacity = null;
/**
* The distance of this tile to the viewport center.
* @member {Number} distance
* @memberof OpenSeadragon.Tile#
*/
this.distance = null; this.distance = null;
/**
* The visibility score of this tile.
* @member {Number} visibility
* @memberof OpenSeadragon.Tile#
*/
this.visibility = null; this.visibility = null;
/**
* Whether this tile is currently being drawn.
* @member {Boolean} beingDrawn
* @memberof OpenSeadragon.Tile#
*/
this.beingDrawn = false; this.beingDrawn = false;
/**
* Timestamp the tile was last touched.
* @member {Number} lastTouchTime
* @memberof OpenSeadragon.Tile#
*/
this.lastTouchTime = 0; this.lastTouchTime = 0;
}; };
$.Tile.prototype = { $.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{
/** /**
* Provides a string representation of this tiles level and (x,y) * Provides a string representation of this tiles level and (x,y)

92
src/tilesource.js
View File

@ -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 * smooth transition between layer in an image pyramid. It has only a single key
* interface that must be implemented to complete it key functionality: * interface that must be implemented to complete it key functionality:
* 'getTileUrl'. It also has several optional interfaces that can be * '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 * 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 * side in M (in pixels), where N is the smallest integer which satisfies
* <strong>2^(N+1) >= M</strong>. * <strong>2^(N+1) >= M</strong>.
* @class *
* @memberof OpenSeadragon
* @extends OpenSeadragon.EventSource * @extends OpenSeadragon.EventSource
* @param {Number|Object|Array|String} width * @param {Number|Object|Array|String} width
* If more than a single argument is supplied, the traditional use of * If more than a single argument is supplied, the traditional use of
@ -70,18 +72,6 @@
* The minimum level to attempt to load. * The minimum level to attempt to load.
* @param {Number} maxLevel * @param {Number} maxLevel
* The maximum level to attempt to load. * 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 ) { $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLevel ) {
var callback = null, 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 ] ) ){ if( 'string' == $.type( arguments[ 0 ] ) ){
//in case the getImageInfo method is overriden and/or implies an //in case the getImageInfo method is overriden and/or implies an
//async mechanism set some safe defaults first //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 * @function
@ -297,6 +323,17 @@ $.TileSource.prototype = {
} }
var $TileSource = $.TileSource.determineType( _this, data, url ); var $TileSource = $.TileSource.determineType( _this, data, url );
if ( !$TileSource ) { 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 } ); _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } );
return; return;
} }
@ -304,6 +341,16 @@ $.TileSource.prototype = {
options = $TileSource.prototype.configure.apply( _this, [ data, url ]); options = $TileSource.prototype.configure.apply( _this, [ data, url ]);
readySource = new $TileSource( options ); readySource = new $TileSource( options );
_this.ready = true; _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 } ); _this.raiseEvent( 'ready', { tileSource: readySource } );
}; };
@ -344,6 +391,17 @@ $.TileSource.prototype = {
msg = formattedExc + " attempting to load TileSource"; 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', { _this.raiseEvent( 'open-failed', {
message: msg, message: msg,
source: url 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 * Decides whether to try to process the response as xml, json, or hand back
* the text * the text
* @eprivate * @private
* @inner * @inner
* @function * @function
* @param {XMLHttpRequest} xhr - the completed network request * @param {XMLHttpRequest} xhr - the completed network request
@ -473,7 +531,7 @@ function processResponse( xhr ){
/** /**
* Determines the TileSource Implementation by introspection of OpenSeadragon * Determines the TileSource Implementation by introspection of OpenSeadragon
* namespace, calling each TileSource implementation of 'isType' * namespace, calling each TileSource implementation of 'isType'
* @eprivate * @private
* @inner * @inner
* @function * @function
* @param {Object|Array|Document} data - the tile source configuration object * @param {Object|Array|Document} data - the tile source configuration object

8
src/tilesourcecollection.js
View File

@ -35,7 +35,8 @@
(function( $ ){ (function( $ ){
/** /**
* @class * @class TileSourceCollection
* @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
*/ */
$.TileSourceCollection = function( tileSize, tileSources, rows, layout ) { $.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 * @function
* @name OpenSeadragon.TileSourceCollection.prototype.getTileBounds
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y
@ -118,7 +118,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.TileSourceCollection.prototype.configure
*/ */
configure: function( data, url ){ configure: function( data, url ){
return; return;
@ -127,7 +126,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.TileSourceCollection.prototype.getTileUrl
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

10
src/tmstilesource.js
View File

@ -43,11 +43,12 @@
(function( $ ){ (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 * TMS tile scheme ( [ as supported by OpenLayers ] is described here
* ( http://openlayers.org/dev/examples/tms.html ). * ( http://openlayers.org/dev/examples/tms.html ).
* *
* @class * @memberof OpenSeadragon
* @extends OpenSeadragon.TileSource * @extends OpenSeadragon.TileSource
* @param {Number|Object} width - the pixel width of the image or the idiomatic * @param {Number|Object} width - the pixel width of the image or the idiomatic
* options object which is used instead of positional arguments. * 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 * Determine if the data and/or url imply the image service is supported by
* this tile source. * this tile source.
* @function * @function
* @name OpenSeadragon.TmsTileSource.prototype.supports
* @param {Object|Array} data * @param {Object|Array} data
* @param {String} optional - url * @param {String} optional - url
*/ */
@ -109,7 +109,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, {
/** /**
* *
* @function * @function
* @name OpenSeadragon.TmsTileSource.prototype.configure
* @param {Object} data - the raw configuration * @param {Object} data - the raw configuration
* @param {String} url - the url the data was retreived from if any. * @param {String} url - the url the data was retreived from if any.
* @return {Object} options - A dictionary of keyword arguments sufficient * @return {Object} options - A dictionary of keyword arguments sufficient
@ -122,7 +121,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, {
/** /**
* @function * @function
* @name OpenSeadragon.TmsTileSource.prototype.getTileUrl
* @param {Number} level * @param {Number} level
* @param {Number} x * @param {Number} x
* @param {Number} y * @param {Number} y

350
src/viewer.js
View File

@ -50,20 +50,13 @@ var THIS = {},
* The options below are given in order that they appeared in the constructor * 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. * 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.EventSource
* @extends OpenSeadragon.ControlDock * @extends OpenSeadragon.ControlDock
* @param {Object} options * @param {OpenSeadragon.Options} options - Viewer 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.
* *
**/ **/
$.Viewer = function( options ) { $.Viewer = function( options ) {
@ -103,9 +96,36 @@ $.Viewer = function( options ) {
hash: options.hash || options.id, hash: options.hash || options.id,
//dom nodes //dom nodes
/**
* The parent element of this Viewer instance, passed in when the Viewer was created.
* @member {Element} element
* @memberof OpenSeadragon.Viewer#
*/
element: null, element: null,
canvas: null, /**
* A &lt;form&gt; element (provided by {@link OpenSeadragon.ControlDock}), the base element of this Viewer instance.<br><br>
* Child element of {@link OpenSeadragon.Viewer#element}.
* @member {Element} container
* @memberof OpenSeadragon.Viewer#
*/
container: null, container: null,
/**
* A &lt;textarea&gt; element, the element where keyboard events are handled.<br><br>
* Child element of {@link OpenSeadragon.Viewer#container},
* positioned below {@link OpenSeadragon.Viewer#canvas}.
* @member {Element} keyboardCommandArea
* @memberof OpenSeadragon.Viewer#
*/
keyboardCommandArea: null,
/**
* A &lt;div&gt; element, the element where user-input events are handled for panning and zooming.<br><br>
* Child element of {@link OpenSeadragon.Viewer#container},
* positioned on top of {@link OpenSeadragon.Viewer#keyboardCommandArea}.<br><br>
* The parent of {@link OpenSeadragon.Drawer#canvas} instances.
* @member {Element} canvas
* @memberof OpenSeadragon.Viewer#
*/
canvas: null,
//TODO: not sure how to best describe these //TODO: not sure how to best describe these
overlays: [], overlays: [],
@ -123,15 +143,29 @@ $.Viewer = function( options ) {
customControls: [], customControls: [],
//These are originally not part options but declared as members //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, source: null,
/**
* Handles rendering of tiles in the viewer. Created for each TileSource opened.
* @member {OpenSeadragon.Drawer} drawer
* @memberof OpenSeadragon.Viewer#
*/
drawer: null, drawer: null,
drawers: [], drawers: [],
/**
* Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened.
* @member {OpenSeadragon.Viewport} viewport
* @memberof OpenSeadragon.Viewer#
*/
viewport: null, viewport: null,
/**
* @member {OpenSeadragon.Navigator} navigator
* @memberof OpenSeadragon.Viewer#
*/
navigator: null, navigator: null,
//A collection viewport is a seperate viewport used to provide //A collection viewport is a separate viewport used to provide
//simultanious rendering of sets of tiless //simultaneous rendering of sets of tiles
collectionViewport: null, collectionViewport: null,
collectionDrawer: 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 * @function
* @name OpenSeadragon.Viewer.prototype.isOpen
* @return {Boolean} * @return {Boolean}
*/ */
isOpen: function () { isOpen: function () {
@ -400,11 +433,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
* A deprecated function, renamed to 'open' to match event name and * A deprecated function, renamed to 'open' to match event name and
* match current 'close' method. * match current 'close' method.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.openDzi
* @param {String} dzi xml string or the url to a DZI xml document. * @param {String} dzi xml string or the url to a DZI xml document.
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* *
* @deprecated - use 'open' instead. * @deprecated - use {@link OpenSeadragon.Viewer#open} instead.
*/ */
openDzi: function ( dzi ) { openDzi: function ( dzi ) {
return this.open( 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 * A deprecated function, renamed to 'open' to match event name and
* match current 'close' method. * match current 'close' method.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.openTileSource
* @param {String|Object|Function} See OpenSeadragon.Viewer.prototype.open * @param {String|Object|Function} See OpenSeadragon.Viewer.prototype.open
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* *
* @deprecated - use 'open' instead. * @deprecated - use {@link OpenSeadragon.Viewer#open} instead.
*/ */
openTileSource: function ( tileSource ) { openTileSource: function ( tileSource ) {
return this.open( 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 * implementation. If the object has a property which is a function
* named 'getTileUrl', it is treated as a custom TileSource. * named 'getTileUrl', it is treated as a custom TileSource.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.open
* @param {String|Object|Function} * @param {String|Object|Function}
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:open
* @fires OpenSeadragon.Viewer.event:open-failed
*/ */
open: function ( tileSource ) { open: function ( tileSource ) {
var _this = this, var _this = this,
@ -470,6 +502,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
openTileSource( _this, event.tileSource ); openTileSource( _this, event.tileSource );
}); });
tileSource.addHandler( 'open-failed', function ( event ) { 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 ); _this.raiseEvent( 'open-failed', event );
}); });
@ -483,6 +526,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
//inline configuration //inline configuration
$TileSource = $.TileSource.determineType( _this, tileSource ); $TileSource = $.TileSource.determineType( _this, tileSource );
if ( !$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', { _this.raiseEvent( 'open-failed', {
message: "Unable to load TileSource", message: "Unable to load TileSource",
source: tileSource source: tileSource
@ -505,8 +559,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.close
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:close
*/ */
close: function ( ) { close: function ( ) {
if ( this._updateRequestId !== null ) { if ( this._updateRequestId !== null ) {
@ -534,6 +588,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
VIEWERS[ this.hash ] = null; VIEWERS[ this.hash ] = null;
delete VIEWERS[ this.hash ]; 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' ); this.raiseEvent( 'close' );
return this; return this;
@ -544,7 +607,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
* Function to destroy the viewer and clean up everything created by * Function to destroy the viewer and clean up everything created by
* OpenSeadragon. * OpenSeadragon.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.destroy
*/ */
destroy: function( ) { destroy: function( ) {
this.close(); this.close();
@ -583,7 +645,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.isMouseNavEnabled
* @return {Boolean} * @return {Boolean}
*/ */
isMouseNavEnabled: function () { isMouseNavEnabled: function () {
@ -592,11 +653,22 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled * @param {Boolean} enabled - true to enable, false to disable
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:mouse-enabled
*/ */
setMouseNavEnabled: function( enabled ){ setMouseNavEnabled: function( enabled ){
this.innerTracker.setTracking( 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 } ); this.raiseEvent( 'mouse-enabled', { enabled: enabled } );
return this; return this;
}, },
@ -604,7 +676,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.areControlsEnabled
* @return {Boolean} * @return {Boolean}
*/ */
areControlsEnabled: function () { areControlsEnabled: function () {
@ -621,9 +692,9 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
* Shows or hides the controls (e.g. the default navigation buttons). * Shows or hides the controls (e.g. the default navigation buttons).
* *
* @function * @function
* @name OpenSeadragon.Viewer.prototype.setControlsEnabled
* @param {Boolean} true to show, false to hide. * @param {Boolean} true to show, false to hide.
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:controls-enabled
*/ */
setControlsEnabled: function( enabled ) { setControlsEnabled: function( enabled ) {
if( enabled ){ if( enabled ){
@ -631,6 +702,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
} else { } else {
beginControlsAutoHide( this ); 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 } ); this.raiseEvent( 'controls-enabled', { enabled: enabled } );
return this; return this;
}, },
@ -638,7 +719,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.isFullPage
* @return {Boolean} * @return {Boolean}
*/ */
isFullPage: function () { isFullPage: function () {
@ -649,10 +729,11 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Toggle full page mode. * Toggle full page mode.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.setFullPage
* @param {Boolean} fullPage * @param {Boolean} fullPage
* If true, enter full page mode. If false, exit full page mode. * If true, enter full page mode. If false, exit full page mode.
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:pre-full-page
* @fires OpenSeadragon.Viewer.event:full-page
*/ */
setFullPage: function( fullPage ) { setFullPage: function( fullPage ) {
@ -673,6 +754,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
fullPage: fullPage, fullPage: fullPage,
preventDefaultAction: false 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 ); this.raiseEvent( 'pre-full-page', fullPageEventArgs );
if ( fullPageEventArgs.preventDefaultAction ) { if ( fullPageEventArgs.preventDefaultAction ) {
return this; 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 } ); this.raiseEvent( 'full-page', { fullPage: fullPage } );
return this; return this;
@ -826,10 +928,11 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Toggle full screen mode if supported. Toggle full page mode otherwise. * Toggle full screen mode if supported. Toggle full page mode otherwise.
* @function * @function
* @name OpenSeadragon.Viewer.prototype.setFullScreen
* @param {Boolean} fullScreen * @param {Boolean} fullScreen
* If true, enter full screen mode. If false, exit full screen mode. * If true, enter full screen mode. If false, exit full screen mode.
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:pre-full-screen
* @fires OpenSeadragon.Viewer.event:full-screen
*/ */
setFullScreen: function( fullScreen ) { setFullScreen: function( fullScreen ) {
var _this = this; var _this = this;
@ -846,6 +949,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
fullScreen: fullScreen, fullScreen: fullScreen,
preventDefaultAction: false 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 ); this.raiseEvent( 'pre-full-screen', fullScreeEventArgs );
if ( fullScreeEventArgs.preventDefaultAction ) { if ( fullScreeEventArgs.preventDefaultAction ) {
return this; return this;
@ -877,6 +991,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
_this.element.style.height = _this.fullPageStyleHeight; _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 } ); _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } );
}; };
$.addEvent( document, $.fullScreenEventName, onFullScreenChange ); $.addEvent( document, $.fullScreenEventName, onFullScreenChange );
@ -892,7 +1016,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.isVisible
* @return {Boolean} * @return {Boolean}
*/ */
isVisible: function () { isVisible: function () {
@ -902,11 +1025,22 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.setVisible * @param {Boolean} visible
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:visible
*/ */
setVisible: function( visible ){ setVisible: function( visible ){
this.container.style.visibility = visible ? "" : "hidden"; 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 } ); this.raiseEvent( 'visible', { visible: visible } );
return this; return this;
}, },
@ -914,7 +1048,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.bindSequenceControls
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
*/ */
bindSequenceControls: function(){ bindSequenceControls: function(){
@ -1000,7 +1133,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.bindStandardControls
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
*/ */
bindStandardControls: function(){ bindStandardControls: function(){
@ -1123,7 +1255,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Gets the active page of a sequence * Gets the active page of a sequence
* @function * @function
* @name OpenSeadragon.Viewer.prototype.currentPage
* @return {Number} * @return {Number}
*/ */
currentPage: function () { currentPage: function () {
@ -1132,13 +1263,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* @function * @function
* @name OpenSeadragon.Viewer.prototype.goToPage
* @return {OpenSeadragon.Viewer} Chainable. * @return {OpenSeadragon.Viewer} Chainable.
* @fires OpenSeadragon.Viewer.event:page
*/ */
goToPage: function( page ){ goToPage: function( page ){
if( page >= 0 && page < this.tileSources.length ){ 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 * @event page
* @memberof OpenSeadragon.Viewer * @memberof OpenSeadragon.Viewer
@ -1165,7 +1296,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Updates the sequence buttons. * Updates the sequence buttons.
* @function * @function OpenSeadragon.Viewer.prototype._updateSequenceButtons
* @private * @private
* @param {Number} Sequence Value * @param {Number} Sequence Value
*/ */
@ -1195,7 +1326,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Display a message in the viewport * Display a message in the viewport
* @function * @function OpenSeadragon.Viewer.prototype._showMessage
* @private * @private
* @param {String} text message * @param {String} text message
*/ */
@ -1214,7 +1345,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
/** /**
* Hide any currently displayed viewport message * Hide any currently displayed viewport message
* @function * @function OpenSeadragon.Viewer.prototype._hideMessage
* @private * @private
*/ */
_hideMessage: function () { _hideMessage: function () {
@ -1409,6 +1540,16 @@ function openTileSource( viewer, source ) {
} }
VIEWERS[ _this.hash ] = _this; 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 } ); _this.raiseEvent( 'open', { source: source } );
return _this; return _this;
@ -1514,6 +1655,20 @@ function onCanvasClick( event ) {
); );
this.viewport.applyConstraints(); 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', { this.raiseEvent( 'canvas-click', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1540,6 +1695,20 @@ function onCanvasDrag( event ) {
this.viewport.applyConstraints(); 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', { this.raiseEvent( 'canvas-drag', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1553,6 +1722,20 @@ function onCanvasRelease( event ) {
if ( event.insideElementPressed && this.viewport ) { if ( event.insideElementPressed && this.viewport ) {
this.viewport.applyConstraints(); 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', { this.raiseEvent( 'canvas-release', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1572,6 +1755,20 @@ function onCanvasScroll( event ) {
); );
this.viewport.applyConstraints(); 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', { this.raiseEvent( 'canvas-scroll', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1590,6 +1787,20 @@ function onContainerExit( event ) {
beginControlsAutoHide( this ); 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', { this.raiseEvent( 'container-exit', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1606,6 +1817,20 @@ function onContainerRelease( event ) {
beginControlsAutoHide( this ); 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', { this.raiseEvent( 'container-release', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1618,6 +1843,20 @@ function onContainerRelease( event ) {
function onContainerEnter( event ) { function onContainerEnter( event ) {
THIS[ this.hash ].mouseInside = true; THIS[ this.hash ].mouseInside = true;
abortControlsAutoHide( this ); 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', { this.raiseEvent( 'container-enter', {
tracker: event.eventSource, tracker: event.eventSource,
position: event.position, position: event.position,
@ -1674,6 +1913,15 @@ function updateOnce( viewer ) {
} }
if ( !THIS[ viewer.hash ].animating && animated ) { 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" ); viewer.raiseEvent( "animation-start" );
abortControlsAutoHide( viewer ); abortControlsAutoHide( viewer );
} }
@ -1683,6 +1931,15 @@ function updateOnce( viewer ) {
if( viewer.navigator ){ if( viewer.navigator ){
viewer.navigator.update( viewer.viewport ); 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" ); viewer.raiseEvent( "animation" );
} else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) { } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) {
viewer.drawer.update(); viewer.drawer.update();
@ -1693,6 +1950,15 @@ function updateOnce( viewer ) {
} }
if ( THIS[ viewer.hash ].animating && !animated ) { 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" ); viewer.raiseEvent( "animation-finish" );
if ( !THIS[ viewer.hash ].mouseInside ) { if ( !THIS[ viewer.hash ].mouseInside ) {

82
src/viewport.js
View File

@ -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 ) { $.Viewport = function( options ) {
@ -105,11 +109,12 @@ $.Viewport = function( options ) {
this.update(); this.update();
}; };
$.Viewport.prototype = { $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
/** /**
* @function * @function
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:reset-size
*/ */
resetContentSize: function( contentSize ){ resetContentSize: function( contentSize ){
this.contentSize = contentSize; this.contentSize = contentSize;
@ -121,6 +126,16 @@ $.Viewport.prototype = {
this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY ); this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY );
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'reset-size', {
contentSize: contentSize contentSize: contentSize
}); });
@ -164,9 +179,20 @@ $.Viewport.prototype = {
/** /**
* @function * @function
* @param {Boolean} immediately * @param {Boolean} immediately
* @fires OpenSeadragon.Viewer.event:home
*/ */
goHome: function( immediately ) { goHome: function( immediately ) {
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'home', {
immediately: immediately immediately: immediately
}); });
@ -297,6 +323,7 @@ $.Viewport.prototype = {
/** /**
* @function * @function
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:constrain
*/ */
applyConstraints: function( immediately ) { applyConstraints: function( immediately ) {
var actualZoom = this.getZoom(), var actualZoom = this.getZoom(),
@ -367,6 +394,16 @@ $.Viewport.prototype = {
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'constrain', {
immediately: immediately immediately: immediately
}); });
@ -492,6 +529,7 @@ $.Viewport.prototype = {
* @param {OpenSeadragon.Point} delta * @param {OpenSeadragon.Point} delta
* @param {Boolean} immediately * @param {Boolean} immediately
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:pan
*/ */
panBy: function( delta, immediately ) { panBy: function( delta, immediately ) {
var center = new $.Point( var center = new $.Point(
@ -507,6 +545,7 @@ $.Viewport.prototype = {
* @param {OpenSeadragon.Point} center * @param {OpenSeadragon.Point} center
* @param {Boolean} immediately * @param {Boolean} immediately
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:pan
*/ */
panTo: function( center, immediately ) { panTo: function( center, immediately ) {
if ( immediately ) { if ( immediately ) {
@ -518,6 +557,17 @@ $.Viewport.prototype = {
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'pan', {
center: center, center: center,
immediately: immediately immediately: immediately
@ -530,6 +580,7 @@ $.Viewport.prototype = {
/** /**
* @function * @function
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:zoom
*/ */
zoomBy: function( factor, refPoint, immediately ) { zoomBy: function( factor, refPoint, immediately ) {
if( refPoint instanceof $.Point && !isNaN( refPoint.x ) && !isNaN( refPoint.y ) ) { if( refPoint instanceof $.Point && !isNaN( refPoint.x ) && !isNaN( refPoint.y ) ) {
@ -544,6 +595,7 @@ $.Viewport.prototype = {
/** /**
* @function * @function
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:zoom
*/ */
zoomTo: function( zoom, refPoint, immediately ) { zoomTo: function( zoom, refPoint, immediately ) {
@ -560,6 +612,18 @@ $.Viewport.prototype = {
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'zoom', {
zoom: zoom, zoom: zoom,
refPoint: refPoint, refPoint: refPoint,
@ -576,7 +640,6 @@ $.Viewport.prototype = {
* debug mode doesn't rotate yet, and overlay rotation is only * debug mode doesn't rotate yet, and overlay rotation is only
* partially supported. * partially supported.
* @function * @function
* @name OpenSeadragon.Viewport.prototype.setRotation
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
*/ */
setRotation: function( degrees ) { setRotation: function( degrees ) {
@ -597,7 +660,6 @@ $.Viewport.prototype = {
/** /**
* Gets the current rotation in degrees. * Gets the current rotation in degrees.
* @function * @function
* @name OpenSeadragon.Viewport.prototype.getRotation
* @return {Number} The current rotation in degrees. * @return {Number} The current rotation in degrees.
*/ */
getRotation: function() { getRotation: function() {
@ -607,6 +669,7 @@ $.Viewport.prototype = {
/** /**
* @function * @function
* @return {OpenSeadragon.Viewport} Chainable. * @return {OpenSeadragon.Viewport} Chainable.
* @fires OpenSeadragon.Viewer.event:resize
*/ */
resize: function( newContainerSize, maintain ) { resize: function( newContainerSize, maintain ) {
var oldBounds = this.getBounds(), var oldBounds = this.getBounds(),
@ -624,6 +687,17 @@ $.Viewport.prototype = {
} }
if( this.viewer ){ 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', { this.viewer.raiseEvent( 'resize', {
newContainerSize: newContainerSize, newContainerSize: newContainerSize,
maintain: maintain maintain: maintain