diff --git a/src/button.js b/src/button.js index 8a09cdb0..1cc819ef 100644 --- a/src/button.js +++ b/src/button.js @@ -36,6 +36,8 @@ /** * An enumeration of button states including, REST, GROUP, HOVER, and DOWN + * @member ButtonState + * @memberof OpenSeadragon * @static */ $.ButtonState = { @@ -49,7 +51,8 @@ $.ButtonState = { * Manages events, hover states for individual buttons, tool-tips, as well * as fading the bottons out when the user has not interacted with them * for a specified period. - * @class + * @class Button + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Object} options * @param {String} options.tooltip Provides context help for the button we the @@ -178,6 +181,14 @@ $.Button = function( options ) { enterHandler: function( event ) { if ( event.insideElementPressed ) { inTo( _this, $.ButtonState.DOWN ); + /** + * @event enter + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "enter", { originalEvent: event.originalEvent } ); } else if ( !event.buttonDownAny ) { inTo( _this, $.ButtonState.HOVER ); @@ -186,29 +197,69 @@ $.Button = function( options ) { focusHandler: function ( event ) { this.enterHandler( event ); + /** + * @event focus + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "focus", { originalEvent: event.originalEvent } ); }, exitHandler: function( event ) { outTo( _this, $.ButtonState.GROUP ); if ( event.insideElementPressed ) { + /** + * @event exit + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "exit", { originalEvent: event.originalEvent } ); } }, blurHandler: function ( event ) { this.exitHandler( event ); + /** + * @event blur + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "blur", { originalEvent: event.originalEvent } ); }, pressHandler: function ( event ) { inTo( _this, $.ButtonState.DOWN ); + /** + * @event press + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "press", { originalEvent: event.originalEvent } ); }, releaseHandler: function( event ) { if ( event.insideElementPressed && event.insideElementReleased ) { outTo( _this, $.ButtonState.HOVER ); + /** + * @event release + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); } else if ( event.insideElementPressed ) { outTo( _this, $.ButtonState.GROUP ); @@ -219,6 +270,14 @@ $.Button = function( options ) { clickHandler: function( event ) { if ( event.quick ) { + /** + * @event click + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent("click", { originalEvent: event.originalEvent }); } }, @@ -226,7 +285,23 @@ $.Button = function( options ) { keyHandler: function( event ){ //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode); if( 13 === event.keyCode ){ + /*** + * @event click + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "click", { originalEvent: event.originalEvent } ); + /*** + * @event release + * @memberof OpenSeadragon.Button + * @type {object} + * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( "release", { originalEvent: event.originalEvent } ); return false; } @@ -238,13 +313,12 @@ $.Button = function( options ) { outTo( this, $.ButtonState.REST ); }; -$.extend( $.Button.prototype, $.EventSource.prototype, { +$.extend( $.Button.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.Button.prototype */{ /** * TODO: Determine what this function is intended to do and if it's actually * useful as an API point. * @function - * @name OpenSeadragon.Button.prototype.notifyGroupEnter */ notifyGroupEnter: function() { inTo( this, $.ButtonState.GROUP ); @@ -254,18 +328,23 @@ $.extend( $.Button.prototype, $.EventSource.prototype, { * TODO: Determine what this function is intended to do and if it's actually * useful as an API point. * @function - * @name OpenSeadragon.Button.prototype.notifyGroupExit */ notifyGroupExit: function() { outTo( this, $.ButtonState.REST ); }, + /** + * @function + */ disable: function(){ this.notifyGroupExit(); this.element.disabled = true; $.setElementOpacity( this.element, 0.2, true ); }, + /** + * @function + */ enable: function(){ this.element.disabled = false; $.setElementOpacity( this.element, 1.0, true ); diff --git a/src/buttongroup.js b/src/buttongroup.js index e6b51091..9f1ea2b5 100644 --- a/src/buttongroup.js +++ b/src/buttongroup.js @@ -35,7 +35,8 @@ (function( $ ){ /** * Manages events on groups of buttons. - * @class + * @class ButtonGroup + * @memberof OpenSeadragon * @param {Object} options - a dictionary of settings applied against the entire * group of buttons * @param {Array} options.buttons Array of buttons @@ -110,13 +111,12 @@ $.ButtonGroup = function( options ) { }).setTracking( true ); }; -$.ButtonGroup.prototype = { +$.ButtonGroup.prototype = /** @lends OpenSeadragon.ButtonGroup.prototype */{ /** * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function - * @name OpenSeadragon.ButtonGroup.prototype.emulateEnter */ emulateEnter: function() { this.tracker.enterHandler( { eventSource: this.tracker } ); @@ -126,7 +126,6 @@ $.ButtonGroup.prototype = { * TODO: Figure out why this is used on the public API and if a more useful * api can be created. * @function - * @name OpenSeadragon.ButtonGroup.prototype.emulateExit */ emulateExit: function() { this.tracker.exitHandler( { eventSource: this.tracker } ); diff --git a/src/control.js b/src/control.js index ed682f85..3f0565a7 100644 --- a/src/control.js +++ b/src/control.js @@ -52,7 +52,8 @@ $.ControlAnchor = { * A Control represents any interface element which is meant to allow the user * to interact with the zoomable interface. Any control can be anchored to any * element. - * @class + * @class Control + * @memberof OpenSeadragon * @param {Element} element - the control element to be anchored in the container. * @param {Object } options - All required and optional settings for configuring a control element. * @param {OpenSeadragon.ControlAnchor} [options.anchor=OpenSeadragon.ControlAnchor.NONE] - the position of the control @@ -110,7 +111,7 @@ $.Control = function ( element, options, container ) { } }; -$.Control.prototype = { +$.Control.prototype = /** @lends OpenSeadragon.Control.prototype */{ /** * Removes the control from the container. diff --git a/src/controldock.js b/src/controldock.js index 94d0c224..ed6e60a0 100644 --- a/src/controldock.js +++ b/src/controldock.js @@ -34,7 +34,8 @@ (function( $ ){ /** - * @class + * @class ControlDock + * @memberof OpenSeadragon */ $.ControlDock = function( options ){ var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'], @@ -85,7 +86,7 @@ this.container.appendChild( this.controls.bottomleft ); }; - $.ControlDock.prototype = { + $.ControlDock.prototype = /** @lends OpenSeadragon.ControlDock.prototype */{ /** * @function diff --git a/src/displayrectangle.js b/src/displayrectangle.js index 389e9bbd..0b20b3d6 100644 --- a/src/displayrectangle.js +++ b/src/displayrectangle.js @@ -38,7 +38,8 @@ * A display rectanlge is very similar to the OpenSeadragon.Rect but adds two * fields, 'minLevel' and 'maxLevel' which denote the supported zoom levels * for this rectangle. - * @class + * @class DisplayRect + * @memberof OpenSeadragon * @extends OpenSeadragon.Rect * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. diff --git a/src/drawer.js b/src/drawer.js index 5a049469..85ae741b 100644 --- a/src/drawer.js +++ b/src/drawer.js @@ -48,7 +48,8 @@ var DEVICE_SCREEN = $.getWindowSize(), /** - * @class + * @class Drawer + * @memberof OpenSeadragon * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source. * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport. * @param {Element} element - Reference to Viewer 'canvas'. @@ -153,7 +154,7 @@ $.Drawer = function( options ) { //this.profiler = new $.Profiler(); }; -$.Drawer.prototype = { +$.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{ /** * Adds an html element as an overlay to the current viewport. Useful for @@ -199,6 +200,16 @@ $.Drawer.prototype = { }) ); this.updateAgain = true; if( this.viewer ){ + /** + * @event add-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location + * @property {OpenSeadragon.OverlayPlacement} placement + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'add-overlay', { element: element, location: options.location, @@ -230,6 +241,16 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event update-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location + * @property {OpenSeadragon.OverlayPlacement} placement + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'update-overlay', { element: element, location: location, @@ -259,6 +280,14 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event remove-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Element} element + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'remove-overlay', { element: element }); @@ -278,6 +307,13 @@ $.Drawer.prototype = { this.updateAgain = true; } if( this.viewer ){ + /** + * @event clear-overlay + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'clear-overlay', {} ); } return this; @@ -471,6 +507,13 @@ function updateViewport( drawer ) { drawer.updateAgain = false; if( drawer.viewer ){ + /** + * @event update-viewport + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-viewport', {} ); } @@ -645,6 +688,21 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi if( drawer.viewer ){ + /** + * @event update-level + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} havedrawn + * @property {Object} level + * @property {Object} opacity + * @property {Object} visibility + * @property {Object} topleft + * @property {Object} bottomright + * @property {Object} currenttime + * @property {Object} best + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-level', { havedrawn: haveDrawn, level: level, @@ -708,6 +766,14 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le drawTile = drawLevel; if( drawer.viewer ){ + /** + * @event update-tile + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} tile + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'update-tile', { tile: tile }); @@ -1222,6 +1288,14 @@ function drawTiles( drawer, lastDrawn ){ } if( drawer.viewer ){ + /** + * @event tile-drawn + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} tile + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ drawer.viewer.raiseEvent( 'tile-drawn', { tile: tile }); diff --git a/src/dzitilesource.js b/src/dzitilesource.js index 1bdfa9cf..9a3b1d03 100644 --- a/src/dzitilesource.js +++ b/src/dzitilesource.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class DziTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -92,14 +93,13 @@ $.DziTileSource = function( width, height, tileSize, tileOverlap, tilesUrl, file }; -$.extend( $.DziTileSource.prototype, $.TileSource.prototype, { +$.extend( $.DziTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.DziTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.DziTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -118,7 +118,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.DziTileSource.prototype.configure * @param {Object|XMLDocument} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -147,7 +146,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.DziTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y @@ -159,7 +157,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.DziTileSource.prototype.tileExists * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/eventsource.js b/src/eventsource.js index 4349c197..16abb4b8 100644 --- a/src/eventsource.js +++ b/src/eventsource.js @@ -34,23 +34,33 @@ (function($){ +/** + * Event handler method signature used by all OpenSeadragon events. + * + * @callback EventHandler + * @memberof OpenSeadragon + * @param {Object} event - See individual events for event properties passed. + */ + + /** * For use by classes which want to support custom, non-browser events. * TODO: Add a method 'one' which automatically unbinds a listener after * the first triggered event that matches. - * @class + * @class EventSource + * @memberof OpenSeadragon */ $.EventSource = function() { this.events = {}; }; -$.EventSource.prototype = { +$.EventSource.prototype = /** @lends OpenSeadragon.EventSource.prototype */{ /** * Add an event handler for a given event. * @function * @param {String} eventName - Name of event to register. - * @param {Function} handler - Function to call when event is triggered. + * @param {OpenSeadragon.EventHandler} handler - Function to call when event is triggered. * @param {Object} [userData=null] - Arbitrary object to be passed unchanged to the handler. */ addHandler: function ( eventName, handler, userData ) { @@ -67,7 +77,7 @@ $.EventSource.prototype = { * Remove a specific event handler for a given event. * @function * @param {String} eventName - Name of event for which the handler is to be removed. - * @param {Function} handler - Function to be removed. + * @param {OpenSeadragon.EventHandler} handler - Function to be removed. */ removeHandler: function ( eventName, handler ) { var events = this.events[ eventName ], @@ -104,7 +114,7 @@ $.EventSource.prototype = { }, /** - * Retrive the list of all handlers registered for a given event. + * Get a function which iterates the list of all handlers registered for a given event, calling the handler for each. * @function * @param {String} eventName - Name of event to get handlers for. */ @@ -133,7 +143,7 @@ $.EventSource.prototype = { * Trigger an event, optionally passing additional information. * @function * @param {String} eventName - Name of event to register. - * @param {Function} handler - Function to call when event is triggered. + * @param {Object} eventArgs - Event-specific data. */ raiseEvent: function( eventName, eventArgs ) { //uncomment if you want to get a log of all events diff --git a/src/iiif1_1tilesource.js b/src/iiif1_1tilesource.js index 6e022d3b..2f90355c 100644 --- a/src/iiif1_1tilesource.js +++ b/src/iiif1_1tilesource.js @@ -36,10 +36,10 @@ /** * A client implementation of the International Image Interoperability - * Format: Image API 1.1 - Please read more about the specification - * at + * Format: Image API 1.1 * - * @class + * @class IIIF1_1TileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ */ @@ -69,12 +69,11 @@ $.IIIF1_1TileSource = function( options ){ $.TileSource.apply( this, [ options ] ); }; -$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { +$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIF1_1TileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -91,7 +90,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.configure * @param {Object} data - the raw configuration */ // IIIF 1.1 Info Looks like this (XML syntax is no more): @@ -114,7 +112,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, { * Responsible for retreiving the url which will return an image for the * region specified by the given x, y, and level components. * @function - * @name OpenSeadragon.IIIF1_1TileSource.prototype.getTileUrl * @param {Number} level - z index * @param {Number} x * @param {Number} y diff --git a/src/iiiftilesource.js b/src/iiiftilesource.js index 99a07798..3050d9e2 100644 --- a/src/iiiftilesource.js +++ b/src/iiiftilesource.js @@ -43,10 +43,10 @@ /** * A client implementation of the International Image Interoperability - * Format: Image API Draft 0.2 - Please read more about the specification - * at + * Format: Image API Draft 0.2 * - * @class + * @class IIIFTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @see http://library.stanford.edu/iiif/image-api/ */ @@ -81,12 +81,11 @@ $.IIIFTileSource = function( options ){ $.TileSource.apply( this, [ options ] ); }; -$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { +$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIFTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.supports + * @method * @param {Object|Array} data * @param {String} optional - url */ @@ -109,10 +108,9 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { ); }, - /** + /** * - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.configure + * @method * @param {Object|XMLDocument} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -152,8 +150,7 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { /** * Responsible for retreiving the url which will return an image for the * region speified by the given x, y, and level components. - * @function - * @name OpenSeadragon.IIIFTileSource.prototype.getTileUrl + * @method * @param {Number} level - z index * @param {Number} x * @param {Number} y @@ -215,28 +212,28 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, { * @private * @inner * @function - * - - - 1E34750D-38DB-4825-A38A-B60A345E591C - 6000 - 4000 - - 1 - 2 - 4 - - 1024 - 1024 - - jpg - png - - - native - grey - - + * @example + * + * + * 1E34750D-38DB-4825-A38A-B60A345E591C + * 6000 + * 4000 + * + * 1 + * 2 + * 4 + * + * 1024 + * 1024 + * + * jpg + * png + * + * + * native + * grey + * + * */ function configureFromXml( tileSource, xmlDoc ){ @@ -306,18 +303,18 @@ function parseXML( node, configuration, property ){ * @private * @inner * @function - * - { - "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1", - "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C", - "width" : 6000, - "height" : 4000, - "scale_factors" : [ 1, 2, 4 ], - "tile_width" : 1024, - "tile_height" : 1024, - "formats" : [ "jpg", "png" ], - "quality" : [ "native", "grey" ] - } + * @example + * { + * "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1", + * "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C", + * "width" : 6000, + * "height" : 4000, + * "scale_factors" : [ 1, 2, 4 ], + * "tile_width" : 1024, + * "tile_height" : 1024, + * "formats" : [ "jpg", "png" ], + * "quality" : [ "native", "grey" ] + * } */ function configureFromObject( tileSource, configuration ){ //the image_host property is not part of the iiif standard but is included here to diff --git a/src/legacytilesource.js b/src/legacytilesource.js index 6bc9ef89..a1cb47f5 100644 --- a/src/legacytilesource.js +++ b/src/legacytilesource.js @@ -41,7 +41,8 @@ * and generating a set of 'service' images like one or more thumbnails, a medium * resolution image and a high resolution image in standard web formats like * png or jpg. - * @class + * @class LegacyTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Array} levels An array of file descriptions, each is an object with * a 'url', a 'width', and a 'height'. Overriding classes can expect more @@ -96,12 +97,11 @@ $.LegacyTileSource = function( levels ) { this.levels = options.levels; }; -$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { +$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.LegacyTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.LegacyTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -119,7 +119,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.LegacyTileSource.prototype.configure * @param {Object|XMLDocument} configuration - the raw configuration * @param {String} dataUrl - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -144,7 +143,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getLevelScale * @param {Number} level */ getLevelScale: function ( level ) { @@ -159,7 +157,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getNumTiles * @param {Number} level */ getNumTiles: function( level ) { @@ -173,7 +170,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getTileAtPoint * @param {Number} level * @param {OpenSeadragon.Point} point */ @@ -188,7 +184,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, { * server technologies, and various specifications for building image * pyramids, this method is here to allow easy integration. * @function - * @name OpenSeadragon.LegacyTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/mousetracker.js b/src/mousetracker.js index c2a7d446..95012f85 100644 --- a/src/mousetracker.js +++ b/src/mousetracker.js @@ -49,7 +49,8 @@ * The MouseTracker allows other classes to set handlers for common mouse * events on a specific element like, 'enter', 'exit', 'press', 'release', * 'scroll', 'click', and 'drag'. - * @class + * @class MouseTracker + * @memberof OpenSeadragon * @param {Object} options * Allows configurable properties to be entirely specified by passing * an options object to the constructor. The constructor also supports @@ -67,27 +68,27 @@ * @param {Number} options.stopDelay * The number of milliseconds without mouse move before the mouse stop * event is fired. - * @param {Function} options.enterHandler + * @param {OpenSeadragon.EventHandler} options.enterHandler * An optional handler for mouse enter. - * @param {Function} options.exitHandler + * @param {OpenSeadragon.EventHandler} options.exitHandler * An optional handler for mouse exit. - * @param {Function} options.pressHandler + * @param {OpenSeadragon.EventHandler} options.pressHandler * An optional handler for mouse press. - * @param {Function} options.releaseHandler + * @param {OpenSeadragon.EventHandler} options.releaseHandler * An optional handler for mouse release. - * @param {Function} options.moveHandler + * @param {OpenSeadragon.EventHandler} options.moveHandler * An optional handler for mouse move. - * @param {Function} options.scrollHandler + * @param {OpenSeadragon.EventHandler} options.scrollHandler * An optional handler for mouse scroll. - * @param {Function} options.clickHandler + * @param {OpenSeadragon.EventHandler} options.clickHandler * An optional handler for mouse click. - * @param {Function} options.dragHandler + * @param {OpenSeadragon.EventHandler} options.dragHandler * An optional handler for mouse drag. - * @param {Function} options.keyHandler + * @param {OpenSeadragon.EventHandler} options.keyHandler * An optional handler for keypress. - * @param {Function} options.focusHandler + * @param {OpenSeadragon.EventHandler} options.focusHandler * An optional handler for focus. - * @param {Function} options.blurHandler + * @param {OpenSeadragon.EventHandler} options.blurHandler * An optional handler for blur. * @param {Object} [options.userData=null] * Arbitrary object to be passed unchanged to any attached handler methods. @@ -188,7 +189,7 @@ }; - $.MouseTracker.prototype = { + $.MouseTracker.prototype = /** @lends OpenSeadragon.MouseTracker.prototype */{ /** * Clean up any events or objects created by the mouse tracker. @@ -374,7 +375,7 @@ * @param {OpenSeadragon.Point} event.position * The position of the event relative to the tracked element. * @param {Number} event.quick - * True only if the clickDistThreshold and clickDeltaThreshold are both pased. Useful for ignoring events. + * True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for ignoring events. * @param {Boolean} event.shift * True if the shift key was pressed during this event. * @param {Boolean} event.isTouchEvent diff --git a/src/navigator.js b/src/navigator.js index 8c8d344c..c90aafb0 100644 --- a/src/navigator.js +++ b/src/navigator.js @@ -40,8 +40,8 @@ * of reference in the larger viewport as to which portion of the image * is currently being examined. The navigator's viewport can be interacted * with using the keyboard or the mouse. - * @class - * @name OpenSeadragon.Navigator + * @class Navigator + * @memberof OpenSeadragon * @extends OpenSeadragon.Viewer * @extends OpenSeadragon.EventSource * @param {Object} options @@ -196,11 +196,10 @@ $.Navigator = function( options ){ }; -$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, { +$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, /** @lends OpenSeadragon.Navigator.prototype */{ /** * @function - * @name OpenSeadragon.Navigator.prototype.update */ update: function( viewport ){ diff --git a/src/openseadragon.js b/src/openseadragon.js index 7f452c25..661bca23 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -101,15 +101,15 @@ */ /** - * The root namespace for OpenSeadragon, this function also serves as a single - * point of instantiation for an {@link OpenSeadragon.Viewer}, including all - * combinations of out-of-the-box configurable features. All utility methods - * and classes are defined on or below this namespace. + * @module OpenSeadragon + */ + + /** + * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all + * combinations of out-of-the-box configurable features. * - * @namespace - * @function - * @name OpenSeadragon - * @exports $ as OpenSeadragon + * @function OpenSeadragon + * @memberof module:OpenSeadragon * * @param {Object} options All required and optional settings for instantiating * a new instance of an OpenSeadragon image viewer. @@ -274,6 +274,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; + +/** + * The root namespace for OpenSeadragon. All utility methods + * and classes are defined on or below this namespace. + * + * @namespace OpenSeadragon + */ + + (function( $ ){ @@ -298,9 +307,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isFunction - * @function - * @see jQuery + * @function isFunction + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isFunction = function( obj ) { return $.type(obj) === "function"; @@ -309,9 +318,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isArray - * @function - * @see jQuery + * @function isArray + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isArray = Array.isArray || function( obj ) { return $.type(obj) === "array"; @@ -321,9 +330,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * A crude way of determining if an object is a window. * Taken from jQuery 1.6.1 - * @name $.isWindow - * @function - * @see jQuery + * @function isWindow + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isWindow = function( obj ) { return obj && typeof obj === "object" && "setInterval" in obj; @@ -332,9 +341,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.type - * @function - * @see jQuery + * @function type + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.type = function( obj ) { return ( obj === null ) || ( obj === undefined ) ? @@ -345,9 +354,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isPlainObject - * @function - * @see jQuery + * @function isPlainObject + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isPlainObject = function( obj ) { // Must be an Object. @@ -376,9 +385,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @name $.isEmptyObject - * @function - * @see jQuery + * @function isEmptyObject + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.isEmptyObject = function( obj ) { for ( var name in obj ) { @@ -390,8 +399,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * True if the browser supports the HTML5 canvas element - * @name $.supportsCanvas - * @property + * @member {Boolean} supportsCanvas + * @memberof OpenSeadragon */ $.supportsCanvas = (function () { var canvasElement = document.createElement( 'canvas' ); @@ -418,7 +427,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Taken from jQuery 1.6.1 - * @see jQuery + * @function extend + * @memberof OpenSeadragon + * @see {@link http://www.jquery.com/ jQuery} */ $.extend = function() { var options, @@ -491,7 +502,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ }; - $.extend( $, { + $.extend( $, /** @lends OpenSeadragon */{ /** * These are the default values for the optional settings documented * in the {@link OpenSeadragon} constructor detail. @@ -1611,10 +1622,10 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * The current browser vendor, version, and related information regarding - * detected features. Features include
- * 'alpha' - Does the browser support image alpha + * detected features. Features include *'alpha'* - Does the browser support image alpha * transparency.
- * @name $.Browser + * @member {Object} Browser + * @memberof OpenSeadragon * @static */ $.Browser = { diff --git a/src/osmtilesource.js b/src/osmtilesource.js index 23c8d635..11cbc2d6 100644 --- a/src/osmtilesource.js +++ b/src/osmtilesource.js @@ -56,7 +56,8 @@ * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864 * pixels. * - * @class + * @class OsmTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -99,14 +100,13 @@ $.OsmTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) { }; -$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { +$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.OsmTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.OsmTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -120,7 +120,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.OsmTileSource.prototype.configure * @param {Object} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -133,7 +132,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.OsmTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/overlay.js b/src/overlay.js index b828ac9e..109f34c5 100644 --- a/src/overlay.js +++ b/src/overlay.js @@ -38,6 +38,8 @@ * An enumeration of positions that an overlay may be assigned relative * to the viewport including CENTER, TOP_LEFT (default), TOP, TOP_RIGHT, * RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT. + * @member OverlayPlacement + * @memberof OpenSeadragon * @static */ $.OverlayPlacement = { @@ -54,7 +56,8 @@ /** * An Overlay provides a - * @class + * @class Overlay + * @memberof OpenSeadragon */ $.Overlay = function( element, location, placement ) { @@ -93,7 +96,7 @@ this.onDraw = options.onDraw; }; - $.Overlay.prototype = { + $.Overlay.prototype = /** @lends OpenSeadragon.Overlay.prototype */{ /** * @function diff --git a/src/point.js b/src/point.js index 806f9fdb..285071e4 100644 --- a/src/point.js +++ b/src/point.js @@ -38,7 +38,8 @@ * A Point is really used as a 2-dimensional vector, equally useful for * representing a point on a plane, or the height and width of a plane * not requiring any other frame of reference. - * @class + * @class Point + * @memberof OpenSeadragon * @param {Number} [x] The vector component 'x'. Defaults to the origin at 0. * @param {Number} [y] The vector component 'y'. Defaults to the origin at 0. * @property {Number} [x] The vector component 'x'. @@ -49,7 +50,7 @@ $.Point = function( x, y ) { this.y = typeof ( y ) == "number" ? y : 0; }; -$.Point.prototype = { +$.Point.prototype = /** @lends OpenSeadragon.Point.prototype */{ /** * Add another Point to this point and return a new Point. diff --git a/src/profiler.js b/src/profiler.js index b7ed0712..1e229b2e 100644 --- a/src/profiler.js +++ b/src/profiler.js @@ -37,7 +37,8 @@ /** * A utility class useful for developers to establish baseline performance * metrics of rendering routines. - * @class + * @class Profiler + * @memberof OpenSeadragon * @property {Boolean} midUpdate * @property {Number} numUpdates * @property {Number} lastBeginTime @@ -66,7 +67,7 @@ $.Profiler = function() { this.maxIdleTime = 0; }; -$.Profiler.prototype = { +$.Profiler.prototype = /** @lends OpenSeadragon.Profiler.prototype */{ /** * @function diff --git a/src/rectangle.js b/src/rectangle.js index a3b1c7dd..819fa7a9 100644 --- a/src/rectangle.js +++ b/src/rectangle.js @@ -40,7 +40,8 @@ * (width, height). The latter component implies the equation of a simple * plane. * - * @class + * @class Rect + * @memberof OpenSeadragon * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. * @param {Number} width The vector component 'height'. @@ -57,7 +58,7 @@ $.Rect = function( x, y, width, height ) { this.height = typeof ( height ) == "number" ? height : 0; }; -$.Rect.prototype = { +$.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{ /** * The aspect ratio is simply the ratio of width to height. diff --git a/src/spring.js b/src/spring.js index 2ef2d220..353c5289 100644 --- a/src/spring.js +++ b/src/spring.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class Spring + * @memberof OpenSeadragon * @param {Object} options - Spring configuration settings. * @param {Number} options.initial - Initial value of spring, default to 0 so * spring is not in motion initally by default. @@ -90,7 +91,7 @@ $.Spring = function( options ) { }; }; -$.Spring.prototype = { +$.Spring.prototype = /** @lends OpenSeadragon.Spring.prototype */{ /** * @function diff --git a/src/tile.js b/src/tile.js index fc985d1e..21eea985 100644 --- a/src/tile.js +++ b/src/tile.js @@ -35,7 +35,8 @@ (function( $ ){ var TILE_CACHE = {}; /** - * @class + * @class Tile + * @memberof OpenSeadragon * @param {Number} level The zoom level this tile belongs to. * @param {Number} x The vector component 'x'. * @param {Number} y The vector component 'y'. @@ -94,7 +95,7 @@ $.Tile = function(level, x, y, bounds, exists, url) { this.lastTouchTime = 0; }; -$.Tile.prototype = { +$.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{ /** * Provides a string representation of this tiles level and (x,y) diff --git a/src/tilesource.js b/src/tilesource.js index 7448ba42..58d13718 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -48,7 +48,8 @@ * By default the image pyramid is split into N layers where the images longest * side in M (in pixels), where N is the smallest integer which satisfies * 2^(N+1) >= M. - * @class + * @class TileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @param {Number|Object|Array|String} width * If more than a single argument is supplied, the traditional use of @@ -166,7 +167,7 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve }; -$.TileSource.prototype = { +$.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{ /** * @function @@ -297,6 +298,15 @@ $.TileSource.prototype = { } var $TileSource = $.TileSource.determineType( _this, data, url ); if ( !$TileSource ) { + /** + * @event open-failed + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } ); return; } @@ -304,6 +314,14 @@ $.TileSource.prototype = { options = $TileSource.prototype.configure.apply( _this, [ data, url ]); readySource = new $TileSource( options ); _this.ready = true; + /** + * @event ready + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {Object} tileSource + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'ready', { tileSource: readySource } ); }; @@ -344,6 +362,15 @@ $.TileSource.prototype = { msg = formattedExc + " attempting to load TileSource"; } + /*** + * @event open-failed + * @memberof OpenSeadragon.TileSource + * @type {object} + * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: msg, source: url @@ -431,7 +458,7 @@ $.extend( true, $.TileSource.prototype, $.EventSource.prototype ); /** * Decides whether to try to process the response as xml, json, or hand back * the text - * @eprivate + * @private * @inner * @function * @param {XMLHttpRequest} xhr - the completed network request @@ -473,7 +500,7 @@ function processResponse( xhr ){ /** * Determines the TileSource Implementation by introspection of OpenSeadragon * namespace, calling each TileSource implementation of 'isType' - * @eprivate + * @private * @inner * @function * @param {Object|Array|Document} data - the tile source configuration object diff --git a/src/tilesourcecollection.js b/src/tilesourcecollection.js index 218b2e4c..52dcbd67 100644 --- a/src/tilesourcecollection.js +++ b/src/tilesourcecollection.js @@ -35,7 +35,8 @@ (function( $ ){ /** - * @class + * @class TileSourceCollection + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource */ $.TileSourceCollection = function( tileSize, tileSources, rows, layout ) { @@ -92,11 +93,10 @@ $.TileSourceCollection = function( tileSize, tileSources, rows, layout ) { }; -$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { +$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TileSourceCollection.prototype */{ /** * @function - * @name OpenSeadragon.TileSourceCollection.prototype.getTileBounds * @param {Number} level * @param {Number} x * @param {Number} y @@ -118,7 +118,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.TileSourceCollection.prototype.configure */ configure: function( data, url ){ return; @@ -127,7 +126,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.TileSourceCollection.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/tmstilesource.js b/src/tmstilesource.js index 8c0f1780..42857d3e 100644 --- a/src/tmstilesource.js +++ b/src/tmstilesource.js @@ -47,7 +47,8 @@ * TMS tile scheme ( [ as supported by OpenLayers ] is described here * ( http://openlayers.org/dev/examples/tms.html ). * - * @class + * @class TmsTileSource + * @memberof OpenSeadragon * @extends OpenSeadragon.TileSource * @param {Number|Object} width - the pixel width of the image or the idiomatic * options object which is used instead of positional arguments. @@ -91,14 +92,13 @@ $.TmsTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) { }; -$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { +$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TmsTileSource.prototype */{ /** * Determine if the data and/or url imply the image service is supported by * this tile source. * @function - * @name OpenSeadragon.TmsTileSource.prototype.supports * @param {Object|Array} data * @param {String} optional - url */ @@ -109,7 +109,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { /** * * @function - * @name OpenSeadragon.TmsTileSource.prototype.configure * @param {Object} data - the raw configuration * @param {String} url - the url the data was retreived from if any. * @return {Object} options - A dictionary of keyword arguments sufficient @@ -122,7 +121,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, { /** * @function - * @name OpenSeadragon.TmsTileSource.prototype.getTileUrl * @param {Number} level * @param {Number} x * @param {Number} y diff --git a/src/viewer.js b/src/viewer.js index 3de2671c..577b112a 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -50,7 +50,8 @@ var THIS = {}, * The options below are given in order that they appeared in the constructor * as arguments and we translate a positional call into an idiomatic call. * - * @class + * @class Viewer + * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource * @extends OpenSeadragon.ControlDock * @param {Object} options @@ -384,12 +385,11 @@ $.Viewer = function( options ) { }; -$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, { +$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** @lends OpenSeadragon.Viewer.prototype */{ /** * @function - * @name OpenSeadragon.Viewer.prototype.isOpen * @return {Boolean} */ isOpen: function () { @@ -400,7 +400,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * A deprecated function, renamed to 'open' to match event name and * match current 'close' method. * @function - * @name OpenSeadragon.Viewer.prototype.openDzi * @param {String} dzi xml string or the url to a DZI xml document. * @return {OpenSeadragon.Viewer} Chainable. * @@ -470,6 +469,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, openTileSource( _this, event.tileSource ); }); tileSource.addHandler( 'open-failed', function ( event ) { + /** + * @event open-failed + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', event ); }); @@ -483,6 +491,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, //inline configuration $TileSource = $.TileSource.determineType( _this, tileSource ); if ( !$TileSource ) { + /*** + * @event open-failed + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {String} message + * @property {String} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: tileSource @@ -534,6 +551,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, VIEWERS[ this.hash ] = null; delete VIEWERS[ this.hash ]; + /** + * @event close + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'close' ); return this; @@ -593,10 +617,19 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function * @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled + * @param {Boolean} enabled - true to enable, false to disable * @return {OpenSeadragon.Viewer} Chainable. */ setMouseNavEnabled: function( enabled ){ this.innerTracker.setTracking( enabled ); + /** + * @event mouse-enabled + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} enabled + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'mouse-enabled', { enabled: enabled } ); return this; }, @@ -631,6 +664,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } else { beginControlsAutoHide( this ); } + /** + * @event controls-enabled + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} enabled + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'controls-enabled', { enabled: enabled } ); return this; }, @@ -673,6 +714,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullPage: fullPage, preventDefaultAction: false }; + /** + * @event pre-full-page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullPage - True if entering full-page mode, false if exiting full-page mode. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-page mode change. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-page', fullPageEventArgs ); if ( fullPageEventArgs.preventDefaultAction ) { return this; @@ -818,6 +868,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, } + /** + * @event full-page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullPage - True if changed to full-page mode, false if exited full-page mode. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'full-page', { fullPage: fullPage } ); return this; @@ -846,6 +904,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, fullScreen: fullScreen, preventDefaultAction: false }; + /** + * @event pre-full-screen + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullScreen - True if entering full-screen mode, false if exiting full-screen mode. + * @property {Boolean} preventDefaultAction - Set to true to prevent full-screen mode change. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'pre-full-screen', fullScreeEventArgs ); if ( fullScreeEventArgs.preventDefaultAction ) { return this; @@ -877,6 +944,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, _this.element.style.height = _this.fullPageStyleHeight; } } + /** + * @event full-screen + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} fullScreen - True if changed to full-screen mode, false if exited full-screen mode. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } ); }; $.addEvent( document, $.fullScreenEventName, onFullScreenChange ); @@ -903,10 +978,19 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * @function * @name OpenSeadragon.Viewer.prototype.setVisible + * @param {Boolean} visible * @return {OpenSeadragon.Viewer} Chainable. */ setVisible: function( visible ){ this.container.style.visibility = visible ? "" : "hidden"; + /** + * @event visible + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Boolean} visible + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'visible', { visible: visible } ); return this; }, @@ -1138,6 +1222,14 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, goToPage: function( page ){ //page is a 1 based index so normalize now //page = page; + /** + * @event page + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {Object} page - The page changed to (1-based). + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'page', { page: page } ); if( this.tileSources.length > page ){ @@ -1163,7 +1255,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Updates the sequence buttons. - * @function + * @function OpenSeadragon.Viewer.prototype._updateSequenceButtons * @private * @param {Number} Sequence Value */ @@ -1193,7 +1285,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Display a message in the viewport - * @function + * @function OpenSeadragon.Viewer.prototype._showMessage * @private * @param {String} text message */ @@ -1212,7 +1304,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** * Hide any currently displayed viewport message - * @function + * @function OpenSeadragon.Viewer.prototype._hideMessage * @private */ _hideMessage: function () { @@ -1407,6 +1499,14 @@ function openTileSource( viewer, source ) { } VIEWERS[ _this.hash ] = _this; + /** + * @event open + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. + * @property {OpenSeadragon.TileSource} source + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ _this.raiseEvent( 'open', { source: source } ); return _this; @@ -1512,6 +1612,18 @@ function onCanvasClick( event ) { ); this.viewport.applyConstraints(); } + /** + * @event canvas-click + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} quick - True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for differentiating between clicks and drags. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-click', { tracker: event.eventSource, position: event.position, @@ -1538,6 +1650,18 @@ function onCanvasDrag( event ) { this.viewport.applyConstraints(); } } + /** + * @event canvas-drag + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {OpenSeadragon.Point} delta - The x,y components of the difference between start drag and end drag. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-drag', { tracker: event.eventSource, position: event.position, @@ -1551,6 +1675,18 @@ function onCanvasRelease( event ) { if ( event.insideElementPressed && this.viewport ) { this.viewport.applyConstraints(); } + /** + * @event canvas-release + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-release', { tracker: event.eventSource, position: event.position, @@ -1570,6 +1706,18 @@ function onCanvasScroll( event ) { ); this.viewport.applyConstraints(); } + /** + * @event canvas-scroll + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Number} scroll - The scroll delta for the event. + * @property {Boolean} shift - True if the shift key was pressed during this event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'canvas-scroll', { tracker: event.eventSource, position: event.position, @@ -1588,6 +1736,18 @@ function onContainerExit( event ) { beginControlsAutoHide( this ); } } + /** + * @event container-exit + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-exit', { tracker: event.eventSource, position: event.position, @@ -1604,6 +1764,18 @@ function onContainerRelease( event ) { beginControlsAutoHide( this ); } } + /** + * @event container-release + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-release', { tracker: event.eventSource, position: event.position, @@ -1616,6 +1788,18 @@ function onContainerRelease( event ) { function onContainerEnter( event ) { THIS[ this.hash ].mouseInside = true; abortControlsAutoHide( this ); + /** + * @event container-enter + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event. + * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element. + * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false. + * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event. + * @property {Object} originalEvent - The original DOM event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.raiseEvent( 'container-enter', { tracker: event.eventSource, position: event.position, @@ -1672,6 +1856,13 @@ function updateOnce( viewer ) { } if ( !THIS[ viewer.hash ].animating && animated ) { + /** + * @event animation-start + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-start" ); abortControlsAutoHide( viewer ); } @@ -1681,6 +1872,13 @@ function updateOnce( viewer ) { if( viewer.navigator ){ viewer.navigator.update( viewer.viewport ); } + /** + * @event animation + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation" ); } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) { viewer.drawer.update(); @@ -1691,6 +1889,13 @@ function updateOnce( viewer ) { } if ( THIS[ viewer.hash ].animating && !animated ) { + /** + * @event animation-finish + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ viewer.raiseEvent( "animation-finish" ); if ( !THIS[ viewer.hash ].mouseInside ) { diff --git a/src/viewport.js b/src/viewport.js index 12fbd956..788aef13 100644 --- a/src/viewport.js +++ b/src/viewport.js @@ -36,7 +36,8 @@ /** - * @class + * @class Viewport + * @memberof OpenSeadragon */ $.Viewport = function( options ) { @@ -105,7 +106,7 @@ $.Viewport = function( options ) { this.update(); }; -$.Viewport.prototype = { +$.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{ /** * @function @@ -121,6 +122,14 @@ $.Viewport.prototype = { this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY ); if( this.viewer ){ + /** + * @event reset-size + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} contentSize + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'reset-size', { contentSize: contentSize }); @@ -167,6 +176,14 @@ $.Viewport.prototype = { */ goHome: function( immediately ) { if( this.viewer ){ + /** + * @event home + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'home', { immediately: immediately }); @@ -367,6 +384,14 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event constrain + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'constrain', { immediately: immediately }); @@ -518,6 +543,15 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event pan + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} center + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'pan', { center: center, immediately: immediately @@ -560,6 +594,16 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event zoom + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {Number} zoom + * @property {OpenSeadragon.Point} refPoint + * @property {Boolean} immediately + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'zoom', { zoom: zoom, refPoint: refPoint, @@ -576,7 +620,6 @@ $.Viewport.prototype = { * debug mode doesn't rotate yet, and overlay rotation is only * partially supported. * @function - * @name OpenSeadragon.Viewport.prototype.setRotation * @return {OpenSeadragon.Viewport} Chainable. */ setRotation: function( degrees ) { @@ -597,7 +640,6 @@ $.Viewport.prototype = { /** * Gets the current rotation in degrees. * @function - * @name OpenSeadragon.Viewport.prototype.getRotation * @return {Number} The current rotation in degrees. */ getRotation: function() { @@ -624,6 +666,15 @@ $.Viewport.prototype = { } if( this.viewer ){ + /** + * @event resize + * @memberof OpenSeadragon.Viewer + * @type {object} + * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event. + * @property {OpenSeadragon.Point} newContainerSize + * @property {Boolean} maintain + * @property {Object} [userData=null] - Arbitrary subscriber-defined object. + */ this.viewer.raiseEvent( 'resize', { newContainerSize: newContainerSize, maintain: maintain