From a89bba35b21c94944f52e22eaac3ac838f9ad9cc Mon Sep 17 00:00:00 2001 From: Yury Delendik Date: Sat, 20 Sep 2014 12:21:49 -0500 Subject: [PATCH] Adds types definitions (jsdoc) for the PDFViewer code. --- web/interfaces.js | 77 ++++++++++++++++++++++++++++++++++++++ web/page_view.js | 14 +++++++ web/pdf_rendering_queue.js | 32 ++++++++++++++-- web/pdf_viewer.js | 42 ++++++++++++++++++++- web/text_layer_builder.js | 12 ++++++ web/thumbnail_view.js | 26 +++++++++++++ web/viewer.js | 3 ++ 7 files changed, 200 insertions(+), 6 deletions(-) create mode 100644 web/interfaces.js diff --git a/web/interfaces.js b/web/interfaces.js new file mode 100644 index 000000000..1c60f9882 --- /dev/null +++ b/web/interfaces.js @@ -0,0 +1,77 @@ +/* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* Copyright 2012 Mozilla Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +'use strict'; + +/** + * @interface + */ +function IPDFLinkService() {} +IPDFLinkService.prototype = { + /** + * @returns {number} + */ + get page() {}, + /** + * @param {number} value + */ + set page(value) {}, + /** + * @param dest - The PDF destination object. + */ + navigateTo: function (dest) {}, + /** + * @param dest - The PDF destination object. + * @returns {string} The hyperlink to the PDF object. + */ + getDestinationHash: function (dest) {}, + /** + * @param hash - The PDF parameters/hash. + * @returns {string} The hyperlink to the PDF object. + */ + getAnchorUrl: function (hash) {}, +}; + +/** + * @interface + */ +function IRenderableView() {} +IRenderableView.prototype = { + /** + * @returns {string} - Unique ID for rendering queue. + */ + get renderingId() {}, + /** + * @returns {RenderingStates} + */ + get renderingState() {}, + /** + * @param {function} callback - The draw completion callback. + */ + draw: function (callback) {}, + resume: function () {}, +}; + +/** + * @interface + */ +function ILastScrollSource() {} +ILastScrollSource.prototype = { + /** + * @returns {number} + */ + get lastScroll() {}, +}; diff --git a/web/page_view.js b/web/page_view.js index 109f0f515..46b53a6db 100644 --- a/web/page_view.js +++ b/web/page_view.js @@ -20,6 +20,20 @@ 'use strict'; +/** + * @constructor + * @param {HTMLDivElement} container - The viewer element. + * @param {number} id - The page unique ID (normally its number). + * @param {number} scale - The page scale display. + * @param {PageViewport} defaultViewport - The page viewport. + * @param {IPDFLinkService} linkService - The navigation/linking service. + * @param {PDFRenderingQueue} renderingQueue - The rendering queue object. + * @param {Cache} cache - The page cache. + * @param {PDFPageSource} pageSource + * @param {PDFViewer} viewer + * + * @implements {IRenderableView} + */ var PageView = function pageView(container, id, scale, defaultViewport, linkService, renderingQueue, cache, pageSource, viewer) { diff --git a/web/pdf_rendering_queue.js b/web/pdf_rendering_queue.js index 65d30b781..c7b1b3aba 100644 --- a/web/pdf_rendering_queue.js +++ b/web/pdf_rendering_queue.js @@ -26,7 +26,14 @@ var RenderingStates = { FINISHED: 3 }; +/** + * Controls rendering of the views for pages and thumbnails. + * @class + */ var PDFRenderingQueue = (function PDFRenderingQueueClosure() { + /** + * @constructs + */ function PDFRenderingQueue() { this.pdfViewer = null; this.pdfThumbnailViewer = null; @@ -38,16 +45,26 @@ var PDFRenderingQueue = (function PDFRenderingQueueClosure() { this.isThumbnailViewEnabled = false; } - PDFRenderingQueue.prototype = { + PDFRenderingQueue.prototype = /** @lends PDFRenderingQueue.prototype */ { + /** + * @param {PDFViewer} pdfViewer + */ setViewer: function PDFRenderingQueue_setViewer(pdfViewer) { this.pdfViewer = pdfViewer; }, + /** + * @param {PDFThumbnailViewer} pdfThumbnailViewer + */ setThumbnailViewer: function PDFRenderingQueue_setThumbnailViewer(pdfThumbnailViewer) { this.pdfThumbnailViewer = pdfThumbnailViewer; }, + /** + * @param {IRenderableView} view + * @returns {boolean} + */ isHighestPriority: function PDFRenderingQueue_isHighestPriority(view) { return this.highestPriorityPage === view.renderingId; }, @@ -120,13 +137,20 @@ var PDFRenderingQueue = (function PDFRenderingQueueClosure() { return null; }, + /** + * @param {IRenderableView} view + * @returns {boolean} + */ isViewFinished: function PDFRenderingQueue_isViewFinished(view) { return view.renderingState === RenderingStates.FINISHED; }, - // Render a page or thumbnail view. This calls the appropriate function - // based on the views state. If the view is already rendered it will return - // false. + /** + * Render a page or thumbnail view. This calls the appropriate function + * based on the views state. If the view is already rendered it will return + * false. + * @param {IRenderableView} view + */ renderView: function PDFRenderingQueue_renderView(view) { var state = view.renderingState; switch (state) { diff --git a/web/pdf_viewer.js b/web/pdf_viewer.js index 9bbba0931..25c882586 100644 --- a/web/pdf_viewer.js +++ b/web/pdf_viewer.js @@ -34,7 +34,26 @@ var IGNORE_CURRENT_POSITION_ON_ZOOM = false; //#include page_view.js //#include text_layer_builder.js +/** + * @typedef {Object} PDFViewerOptions + * @property {HTMLDivElement} container - The container for the viewer element. + * @property {HTMLDivElement} viewer - (optional) The viewer element. + * @property {IPDFLinkService} linkService - The navigation/linking service. + * @property {PDFRenderingQueue} renderingQueue - (optional) The rendering + * queue object. + */ + +/** + * Simple viewer control to display PDF content/pages. + * @class + * @implements {ILastScrollSource} + * @implements {IRenderableView} + */ var PDFViewer = (function pdfViewer() { + /** + * @constructs PDFViewer + * @param {PDFViewerOptions} options + */ function PDFViewer(options) { this.container = options.container; this.viewer = options.viewer || options.container.firstElementChild; @@ -56,7 +75,7 @@ var PDFViewer = (function pdfViewer() { this._resetView(); } - PDFViewer.prototype = { + PDFViewer.prototype = /** @lends PDFViewer.prototype */{ get pagesCount() { return this.pages.length; }, @@ -496,6 +515,12 @@ var PDFViewer = (function pdfViewer() { }); }, + /** + * @param textLayerDiv {HTMLDivElement} + * @param pageIndex {number} + * @param viewport {PageViewport} + * @returns {TextLayerBuilder} + */ createTextLayerBuilder: function (textLayerDiv, pageIndex, viewport) { var isViewerInPresentationMode = this.presentationModeState === PresentationModeState.FULLSCREEN; @@ -517,13 +542,26 @@ var PDFViewer = (function pdfViewer() { return PDFViewer; })(); +/** + * PDFPage object source. + * @class + */ var PDFPageSource = (function PDFPageSourceClosure() { + /** + * @constructs + * @param {PDFDocument} pdfDocument + * @param {number} pageNumber + * @constructor + */ function PDFPageSource(pdfDocument, pageNumber) { this.pdfDocument = pdfDocument; this.pageNumber = pageNumber; } - PDFPageSource.prototype = { + PDFPageSource.prototype = /** @lends PDFPageSource.prototype */ { + /** + * @returns {Promise} + */ getPage: function () { return this.pdfDocument.getPage(this.pageNumber); } diff --git a/web/text_layer_builder.js b/web/text_layer_builder.js index bc27bb81b..5fac1c493 100644 --- a/web/text_layer_builder.js +++ b/web/text_layer_builder.js @@ -28,11 +28,23 @@ function isAllWhitespace(str) { return !NonWhitespaceRegexp.test(str); } +/** + * @typedef {Object} TextLayerBuilderOptions + * @property {HTMLDivElement} textLayerDiv - The text layer container. + * @property {number} pageIndex - The page index. + * @property {PageViewport} viewport - The viewport of the text layer. + * @property {ILastScrollSource} lastScrollSource - The object that records when + * last time scroll happened. + * @property {boolean} isViewerInPresentationMode + * @property {PDFFindController} findController + */ + /** * TextLayerBuilder provides text-selection functionality for the PDF. * It does this by creating overlay divs over the PDF text. These divs * contain text that matches the PDF text they are overlaying. This object * also provides a way to highlight text that is being searched for. + * @class */ var TextLayerBuilder = (function TextLayerBuilderClosure() { function TextLayerBuilder(options) { diff --git a/web/thumbnail_view.js b/web/thumbnail_view.js index 205e31fd6..1e16a7de4 100644 --- a/web/thumbnail_view.js +++ b/web/thumbnail_view.js @@ -21,6 +21,17 @@ var THUMBNAIL_SCROLL_MARGIN = -19; +/** + * @constructor + * @param container + * @param id + * @param defaultViewport + * @param linkService + * @param renderingQueue + * @param pageSource + * + * @implements {IRenderableView} + */ var ThumbnailView = function thumbnailView(container, id, defaultViewport, linkService, renderingQueue, pageSource) { @@ -241,7 +252,22 @@ var ThumbnailView = function thumbnailView(container, id, defaultViewport, ThumbnailView.tempImageCache = null; +/** + * @typedef {Object} PDFThumbnailViewerOptions + * @property {HTMLDivElement} container - The container for the thumbs elements. + * @property {IPDFLinkService} linkService - The navigation/linking service. + * @property {PDFRenderingQueue} renderingQueue - The rendering queue object. + */ + +/** + * Simple viewer control to display thumbs for pages. + * @class + */ var PDFThumbnailViewer = (function pdfThumbnailViewer() { + /** + * @constructs + * @param {PDFThumbnailViewerOptions} options + */ function PDFThumbnailViewer(options) { this.container = options.container; this.renderingQueue = options.renderingQueue; diff --git a/web/viewer.js b/web/viewer.js index 99f277a57..ac8810472 100644 --- a/web/viewer.js +++ b/web/viewer.js @@ -92,8 +92,11 @@ var PDFView = { pdfDocument: null, sidebarOpen: false, printing: false, + /** @type {PDFViewer} */ pdfViewer: null, + /** @type {PDFThumbnailViewer} */ pdfThumbnailViewer: null, + /** @type {PDFRenderingQueue} */ pdfRenderingQueue: null, pageRotation: 0, updateScaleControls: true,