mozilla/pdf.js — Issue #1100: API draft
Author: arturadib
Created: 2012-01-18 21:03:54+00:00
State: open

This is the initial draft for our proposed new API. A brief overview of the existing API is also provided below for reference. The API should serve two uses cases:

# High-level

This use case is the simplest one where the API consumer wants to embed a PDF reader in their app, much like Scribd's embedded reader. The reader UI can be light-weight: no scrolling, simply next/previous page and page #.

Basically the consumer gives a `div` and a document `src`, and pdf.js embeds the aforementioned reader in that `div`, perhaps with optional parameters to enable/disable features (text layer, search, annotations):

```javascript
PDFJS.embed(div, 'my-super-doc.pdf', {
selection: true,
search: false,
annotations: true
});
```
The `.embed()` interface does all the job of downloading the file and inserting all features into the div.

# Low-level

This is the API for consumers who need more detailed control. It can mirror the current API:

### Current API

This is a summary of calls currently made by the `web/` application to PDFJS objects. They are summarized here because it's not clear from `core.js` which methods are meant to be called externally and which are for internal use only.

**PDFDoc()**

+ `var pdf = new PDFJS.PDFDoc(data)`
+ `pdf.numPages`
+ `pdf.fingerprint`
+ `pdf.catalog.destinations`
+ `pdf.catalog.documentOutline`

**Page()**

+ `var page = pdf.getPage(num)`
+ `page.width`
+ `page.height`
+ `page.stats`
+ `page.ref`
+ `page.view` (from here on the calls are actually `content.*` in `viewer.js`)
+ `page.getAnnotations()`
+ `page.rotatePoint(x, y, reverse)`
+ `page.startRendering(ctx, callback, textlayer)`