PrizmDoc® Viewer v14.0 Release - Updated
PrizmDoc Viewer / API Reference / Viewer Control
In This Topic
    Viewer Control
    In This Topic

    The Viewer API permits programmatic control over the Viewer.

    Most API functionality is exposed by the ViewerControl - the core component of the Viewer. The Viewer UI/chrome builds off of the API members of the ViewerControl.

    The Viewer API is required to:

    • Modify the behavior of the Viewer
    • Augment the behavior of the Viewer
    • Build custom Viewer menus

    The Viewer API is not required to:

    • Customize the Viewer’s layout or style
    • Add or remove tabs
    • Move or remove buttons and other inputs

    You may want to review Configuring the Viewer for additional information. In addition, see the API Examples, which demonstrate using the API to implement common scenarios.

    This topic provides information about the following:

    API Functionality

    The Viewer API exposes the following functionality:

    • Creating and destroying the Viewer
    • Events
    • Page navigation
    • Zooming and fitting content
    • Mark (annotation and redaction) CRUD
    • Markup saving and loading
    • Customizing mouse tools
    • Searching document text
    • Printing
    • Getting page and document attributes

    Getting Started

    This section provides basic information for getting started using the API.

    Access to the API

    The API classes are exposed through the global PCCViewer object.

    Example

    window.PCCViewer;
    
    

    A ViewerControl is created when instantiating the Viewer with the jQuery plugin, and it is accessible through the viewerControl property of the returned object.

    Example

    var viewer = $("#mydiv").pccViewer(options);
    var viewerControl = viewer.viewerControl;
    
    

    Viewer Ready

    While initialization of the Viewer is being performed, it is unsafe to call some of the ViewerControl methods (these methods will throw an error during initialization). The ViewerReady event signals that initialization has completed, and it is safe to call all ViewerControl methods with valid data.

    Example

    var viewerControl = $("#mydiv").pccViewer(options).viewerControl;
    
    // Subscribe to the "ViewerReady" event
    viewerControl.on(PCCViewer.EventType.ViewerReady, function(ev) {
        // It is now safe to call all ViewerControl methods
        viewerControl.setCurrentMouseTool("AccusoftLineAnnotation");
    
        // It’s also safe to use ECMA5 properties
        // (in supporting browsers).
        var currentPageNumber = viewerControl.pageNumber;
    
        // This is also a good time to subscribe to other events,
        // if you want to keep all API code in one place.
        viewerControl.on(PCCViewer.EventType.PageDisplayed, ...);
    });
    
    

    Page Count Ready

    The ViewerControl will not get the page count of a document from PrizmDoc Server until after the ViewerReady event. Before the page count is returned, the ViewerControl assumes every document has one page.

    The PageCountReady event signals when the ViewerControl has the actual page count from the server. Subscribe to this event to know when you can navigate to and interact with other pages in the document.

    Example

    var viewerControl = $("#mydiv").pccViewer(options).viewerControl;
    
    // Subscribe to the "PageCountReady" event
    viewerControl.on(PCCViewer.EventType.PageCountReady, function(ev) {
        var pageCount = ev.pageCount;
    
        // We can now navigate to other pages in the document.
        if (pageCount > 1) {
            // Go to the second page of the document.
            viewerControl.setPageNumber(2);
        }
    });
    
    

    It is safe to call Viewer navigation API members before the page count is available to the ViewerControl, but navigation outside of the known page count (of one) is not possible.

    EstimatedPageCountReady Event

    Calculating the actual page count of some document formats can take a significant amount of time, and therefore waiting on an actual page count could make the Viewer appear unresponsive to the end user. To address this problem, the PrizmDoc Server may quickly generate an estimated page count.

    The EstimatedPageCountEvent signals that the Viewer has an estimated page count and that navigation to other pages is possible.

    Example

    var viewerControl = $("#mydiv").pccViewer(options).viewerControl;
    
    // Subscribe to the "PageCountReady" event
    viewerControl.on(PCCViewer.EventType.EstimatedPageCountReady, ...);
    
    
    • The estimated page count will not always be triggered.
    • The estimated and actual page count can be different. If the estimated page count is greater than the actual page count, then for a short time it will be possible to navigate past the actual last page of the document. The Viewer will display a placeholder for these pages until the actual page count is available, when these placeholders will be removed.

    Page Numbering

    Page numbering in the API starts with 1. This is true for events and methods. The API does not support 0-based page indexes, so be careful when iterating over pages.

    Example

    // Navigate to the first page of the document
    viewerControl.changeToFirstPage();
    
    // An equivalent call would be
    viewerControl.setPageNumber(1);
    
    

    Pixels

    In the API, the unit of measure for height, width, location, and other sizes is a pixel. To determine the height and width of a page in pixels, use the ViewerControl’s requestPageAttributes method.

    Example

    // Get attributes of page 1.
    viewerControl.requestPageAttributes(1).then(function(attributes) {
        var pageWidth = attributes.width;
        var pageHeight = attributes.height;
    
        // Add a rectangle that is the full width and height of page 1
        viewerControl.addMark(1, "RectangleAnnotation")
            .setRectangle({x:0,
                           y:0,
                           height: pageHeight,
                           width: pageWidth});
    });
    
    

    It is advised to check page attributes before getting or setting the location of a Mark object.

    • For vector data provided by the server, a resolution of 72dpi is chosen, from which dimensions in pixels are calculated.
    • It is not safe to assume that vector data will be provided by the server for a given document type.

    Getters, Setters, and ECMA5 Properties

    The API commonly uses getter and setter methods for accessing and modifying data associated with objects. Typically these methods are in pairs, unless the data is read-only.

    Example

    // read-write
    viewerControl.getPageNumber();    // get the current page number
    viewerControl.setPageNumber(1);   // set the current page to 1
    
    // read-only
    viewerControl.getPageCount();     // get the page count
    
    

    The API also offers ECMA5 Accessor properties that correspond to the getter and setters. These accessor properties offer a different style of coding, and they are only available in modern browsers that implement Object.defineProperties.

    Example

    if (Object.defineProperties) {
        viewerControl.pageNumber;      // get the current page number
        viewerControl.pageNumber = 1;  // set the current page to 1
        viewerControl.pageCount;       // get the page count
    }
    
    

    Fluent Style: Method Chaining

    The API is designed to support method chaining. Most methods will return the current context (object on which the method was called) in order to promote method chaining. Exceptions to this rule are getter methods and methods that complete asynchronously.

    Example

    // Method chaining when creating a rectangle annotation
    viewerControl.addMark(1, "RectangleAnnotation")
        .setRectangle({x: 0, y:0, width: 100, height: 100})
        .setFillColor("#FFFFFF")
        .setOpacity(127)
        .setBorderThickness(6);
    
    // Method chaining when manipulating the page
    viewerControl
        .rotatePage(90)
        .zoomIn(1.2);
    
    

    Note that using the ECMA5 accessor properties often discourages method chaining.

    Promises

    The API implements the Promises/A+ spec in the class PCCViewer.Promise.

    Many methods that complete asynchronously return a PCCViewer.Promise object. Use the returned promise object to subscribe callbacks for the completion of the asynchronous event.

    Example

    // Use the promise to subscribe a callback to requestPageText
    viewerControl.requestPageText(1).then(function(pageText) {
        alert("Text of page 1 is: " \+ pageText);
    });
    
    

    Two exceptions are ViewerControl#print and ViewerControl#search, which complete asynchronously but do not return a PCCViewer.Promise object. These methods both return objects that represent the requested print and search. Searching and printing have status events and are cancellable, for which they cannot be suitably represented with a promise object.