From c207d4a7d6e383de4c9b1b1eedbda6f56860f1b7 Mon Sep 17 00:00:00 2001 From: Brendan Dahl Date: Fri, 13 Apr 2012 09:25:08 -0700 Subject: [PATCH] Add docs to API. --- src/api.js | 118 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 9 deletions(-) diff --git a/src/api.js b/src/api.js index f1baefade..74c58a61d 100644 --- a/src/api.js +++ b/src/api.js @@ -1,6 +1,16 @@ /* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* vim: set shiftwidth=2 tabstop=2 autoindent cindent expandtab: */ +/** + * This is the main entry point for loading a PDF and interacting with it. + * NOTE: If a URL is used to fetch the PDF data a standard XMLHttpRequest(XHR) + * is used, which means it must follow the same origin rules that any XHR does + * e.g. No cross domain requests without CORS. + * + * @param {string|TypedAray} source Either a url to a PDF is located or a + * typed array already populated with data. + * @return {Promise} A promise that is resolved with {PDFDocumentProxy} object. + */ PDFJS.getDocument = function getDocument(source) { var promise = new PDFJS.Promise(); var transport = new WorkerTransport(promise); @@ -31,33 +41,74 @@ PDFJS.getDocument = function getDocument(source) { return promise; }; +/** + * Proxy to a PDFDocument in the worker thread. Also, contains commonly used + * properties that can be read synchronously. + */ var PDFDocumentProxy = (function() { function PDFDocumentProxy(pdfInfo, transport) { this.pdfInfo = pdfInfo; this.transport = transport; } PDFDocumentProxy.prototype = { + /** + * @return {number} Total number of pages the PDF contains. + */ get numPages() { return this.pdfInfo.numPages; }, + /** + * @return {string} A unique ID to identify a PDF. Not guaranteed to be + * unique. + */ get fingerprint() { return this.pdfInfo.fingerprint; }, + /** + * @param {number} The page number to get. The first page is 1. + * @return {Promise} A promise that is resolved with a {PDFPageProxy} + * object. + */ getPage: function(number) { return this.transport.getPage(number); }, + /** + * @return {Promise} A promise that is resolved with a lookup table for + * mapping named destinations to reference numbers. + */ getDestinations: function() { var promise = new PDFJS.Promise(); var destinations = this.pdfInfo.destinations; promise.resolve(destinations); return promise; }, + /** + * @return {Promise} A promise that is resolved with an {array} that is a + * tree outline (if it has one) of the PDF. The tree is in the format of: + * [ + * { + * title: string, + * bold: boolean, + * italic: boolean, + * color: rgb array, + * dest: dest obj, + * items: array of more items like this + * }, + * ... + * ]. + */ getOutline: function() { var promise = new PDFJS.Promise(); var outline = this.pdfInfo.outline; promise.resolve(outline); return promise; }, + /** + * @return {Promise} A promise that is resolved with an {object} that has + * info and metadata properties. Info is an {object} filled with anything + * available in the information dictionary and similarly metadata is a + * {Metadata} object with information from the metadata section of the PDF. + */ getMetadata: function() { var promise = new PDFJS.Promise(); var info = this.pdfInfo.info; @@ -84,30 +135,66 @@ var PDFPageProxy = (function PDFPageProxyClosure() { this.objs = transport.objs; } PDFPageProxy.prototype = { + /** + * @return {number} Page number of the page. First page is 1. + */ get pageNumber() { return this.pageInfo.pageIndex + 1; }, + /** + * @return {number} The number of degrees the page is rotated clockwise. + */ get rotate() { return this.pageInfo.rotate; }, + /** + * @return {object} The reference that points to this page. It has 'num' and + * 'gen' properties. + */ get ref() { return this.pageInfo.ref; }, + /** + * @return {array} An array of the visible portion of the PDF page in the + * user space units - [x1, y1, x2, y2]. + */ get view() { return this.pageInfo.view; }, + /** + * @param {number} scale The desired scale of the viewport. + * @param {number} rotate Degrees to rotate the viewport. If omitted this + * defaults to the page rotation. + * @return {PageViewport} Contains 'width' and 'height' properties along + * with transforms required for rendering. + */ getViewport: function(scale, rotate) { if (arguments.length < 2) rotate = this.rotate; return new PDFJS.PageViewport(this.view, scale, rotate, 0, 0); }, + /** + * @return {Promise} A promise that is resolved with an {array} of the + * annotation objects. + */ getAnnotations: function() { var promise = new PDFJS.Promise(); var annotations = this.pageInfo.annotations; promise.resolve(annotations); return promise; }, - render: function(renderContext) { + /** + * Begins the process of rendering a page to the desired context. + * @param {object} params A parameter object that supports: + * { + * canvasContext(required): A 2D context of a DOM Canvas object., + * textLayer(optional): An object that has beginLayout, endLayout, and + * appendText functions. + * } + * @return {Promise} A promise that is resolved when the page finishes + * rendering. + */ + render: function(params) { var promise = new Promise(); var stats = this.stats; stats.time('Overall'); @@ -132,10 +219,10 @@ var PDFPageProxy = (function PDFPageProxyClosure() { // Once the operatorList and fonts are loaded, do the actual rendering. this.displayReadyPromise.then( function pageDisplayReadyPromise() { - var gfx = new CanvasGraphics(renderContext.canvasContext, - this.objs, renderContext.textLayer); + var gfx = new CanvasGraphics(params.canvasContext, + this.objs, params.textLayer); try { - this.display(gfx, renderContext.viewport, complete); + this.display(gfx, params.viewport, complete); } catch (e) { complete(e); } @@ -147,7 +234,9 @@ var PDFPageProxy = (function PDFPageProxyClosure() { return promise; }, - + /** + * For internal use only. + */ startRenderingFromOperatorList: function PDFPageWrapper_startRenderingFromOperatorList(operatorList, fonts) { @@ -168,7 +257,9 @@ var PDFPageProxy = (function PDFPageProxyClosure() { } ); }, - + /** + * For internal use only. + */ ensureFonts: function PDFPageWrapper_ensureFonts(fonts, callback) { this.stats.time('Font Loading'); // Convert the font names to the corresponding font obj. @@ -186,7 +277,9 @@ var PDFPageProxy = (function PDFPageProxyClosure() { }.bind(this) ); }, - + /** + * For internal use only. + */ display: function PDFPageWrapper_display(gfx, viewport, callback) { var stats = this.stats; stats.time('Rendering'); @@ -216,13 +309,18 @@ var PDFPageProxy = (function PDFPageProxyClosure() { } next(); }, - + /** + * Stub for future feature. + */ getTextContent: function() { var promise = new PDFJS.Promise(); var textContent = 'page text'; // not implemented promise.resolve(textContent); return promise; }, + /** + * Stub for future feature. + */ getOperationList: function() { var promise = new PDFJS.Promise(); var operationList = { // not implemented @@ -235,7 +333,9 @@ var PDFPageProxy = (function PDFPageProxyClosure() { }; return PDFPageProxy; })(); - +/** + * For internal use only. + */ var WorkerTransport = (function WorkerTransportClosure() { function WorkerTransport(promise) { this.workerReadyPromise = promise;