PrizmDoc® Viewer v13.28 Release - Updated
PrizmDoc Viewer / API Reference / Viewer Control / Namespace: PCCViewer / Class: ViewerControl
In This Topic
    Class: ViewerControl
    In This Topic

    PCCViewer. ViewerControl

    The ViewerControl is a document viewer without any menus, buttons, dialogs, etc. The UI only consists of a page list, which allows a user to scroll through the pages of a document. It is the most basic viewer which shows a document. It can be used alone, or it can be augmented with UI elements (chrome) to expose more functionality to the end user.

    Our out-of-the-box HTML5 viewer uses the ViewerControl to build a desktop and mobile ready viewer, with extensive UI chrome and a responsive design.

    The ViewerControl has an API, which covers the full set of viewer functionality. Code that directly uses the ViewerControl will typically create UI elements - buttons, menus, and inputs - for the end user to interact with. These UI elements will be hooked up to call the ViewerControl API when the user interacts with the UI elements (e.g. on button click, call .changeToNextPage()).

    When the ViewerControl is instantiated it fires initialization events in the following order:

    NOTE: do not use the ViewerControl API until PCCViewer.EventType.ViewerReady has fired.

    When viewing session is changed with PCCViewer.ViewerControl#changeViewingSession method call, ViewerControl fires events in the following order:

    NOTE: once the PCCViewer.EventType.ViewingSessionChanging event has fired, do not use the ViewerControl API until PCCViewer.EventType.ViewingSessionChanged event fires.

    The ViewerControl also permits mouse and touch interaction. The behavior of the mouse tool or touch is set using the API method PCCViewer.ViewerControl#setCurrentMouseTool. Once the tool is set, the user can interact with the viewer using the mouse tool or touch.

    Constructor

    new ViewerControl(element, options)

    Creates a new PCCViewer.ViewerControl object.

    Parameters:

    Name Type Description
    element HTMLDivElement

    Embed the ViewerControl in this element.

    options PCCViewer.ViewerControl~ViewerControlOptions

    Specify options for the ViewerControl object. Some options are required.

    Members

    (readonly) atMaxScale :boolean

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    It checks whether the viewer is currently at the maximum zoom level.

    Type:

    • boolean
    See:

    (readonly) atMinScale :boolean

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    It checks whether the viewer is currently at the minimum zoom level.

    Type:

    • boolean
    See:

    currentMouseTool :string

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets and sets the current mouse tool of the viewer by name.

    Type:

    • string
    See:

    (readonly) isCommentsPanelOpen :boolean

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets a value indicating whether the comments panel is open.

    Type:

    • boolean
    See:

    markHandleMode :PCCViewer.MarkHandleMode

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets or sets the mark handle mode.

    Type:

    See:

    (readonly) pageCount :number

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets the document page count.

    Type:

    • number
    See:

    pageNumber :number

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets and sets the current page of the viewer to the specified page number in the document. Setting the page number to a value other than the current page number will cause the viewer to navigate to the page number provided in the parameter.

    Type:

    • number
    See:

    redactionViewMode :PCCViewer.RedactionViewMode

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets or sets the redaction view mode. This defines whether the document content text underneath redaction rectangles needs to be visible in a "Draft" mode PCCViewer.RedactionViewMode enumerable values.

    Type:

    See:

    scaleFactor :number

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets or sets the scale factor to use in the viewer, with 1 being 100% zoom.

    Type:

    • number
    See:

    (readonly) searchRequest :PCCViewer.SearchRequest

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets the SearchRequest object from the last call to PCCViewer.ViewerControl#search.

    Type:

    See:

    selectedConversation :PCCViewer.Conversation

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets and sets the selected conversation.

    Type:

    See:

    (readonly) selectedMarks :Array.<PCCViewer.Mark>

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets an array of selected marks.

    Type:

    See:

    selectedPiiEntity :PCCViewer.PiiEntity|null

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets and sets the selected PiiEntity object. Returns null if no PII entities are selected. Note: Setting the PII entity through this property will always scroll to it.

    Type:

    See:

    selectedSearchResult :PCCViewer.SearchResult|null

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets and sets the selected SearchResult object. Returns null if no search results are selected. Note: Setting the search result through this property will always scroll to it.

    Type:

    See:

    viewMode :PCCViewer.ViewMode

    An ECMA 5 accessor property that is defined only in browsers supporting ECMA 5. This property is not available in the older browsers like IE8.

    Gets or sets the view mode. This defines how the document pages will be scaled, based on the values of the PCCViewer.ViewMode enumerable values.

    Type:

    See:

    (inner) TextSelection

    A plain object convention describing a text selection.

    Properties:

    Name Description
    pageNumber : number

    The page number that the selection starts on.

    length : number

    The length of the text (number of characters).

    text : string

    The selected text. This is plain text without any formatting.

    startIndex : number

    The index at which the selection starts in the page.

    rectangles : Array.<PCCViewer.ViewerControl~TextSelectionRectangle>

    An array of all the rectangles that make up the text selection.

    (inner) TextSelectionRectangle

    A plain object convention describing a text selection rectangle.

    Properties:

    Name Description
    x : number

    The x-coordinate of the top-left corner of the rectangle.

    y : number

    The y-coordinate of the top-left corner of the rectangle.

    width : number

    The width of the rectangle.

    height : number

    The height of the rectangle.

    pageNumber : number

    The page number of the rectangle.

    Methods

    addMark(pageNumber, markType) → {PCCViewer.Mark}

    Creates a new mark of a specific type and adds to the specified page.

    Example

    viewerControl.addMark(1, "LineAnnotation");
    
    

    Parameters:

    Name Type Description
    pageNumber number

    Indicates the page to which to add the mark.

    markType PCCViewer.Mark.Type | string

    Indicates the type of mark being added

    Throws:

    Returns:

    The new mark.

    Type
    PCCViewer.Mark

    addMarkFromSearchResult()

    Deprecated since v13.26 (use the PCCViewer.ViewerControl#addMarkFromTextSelection method instead).

    addMarkFromTextSelection(textSelection, markType) → {PCCViewer.Mark}

    Creates a new mark of a specific type and adds to the location where the specified text selection, search result, or PII (Personally Identifiable Information) entity is.

    Example using search

     const requestObject = viewerControl.search('Con');
     const marks = [];
     let newMark;
     requestObject.on(PCCViewer.EventType.SearchCompleted, function (event) {
         let searchResults = event.completedSearchResults;
         for (let i = 0; i < searchResults.length; i++) {
             newMark = viewer.addMarkFromTextSelection(searchResults[i], PCCViewer.Mark.Type.TextSelectionRedaction);
             marks.push(newMark);
         }
     });
    
    

    Example using PII detection

     const piiDetectionRequest = viewerControl.detectPii();
     const marks = [];
     let newMark;
     piiDetectionRequest.on('PartialPiiAvailable', function(event) {
         let newPiiEntities = event.partialPiiEntities;
         for(let i = 0; i < newPiiEntities.length; i++) {
             newMark = viewerControl.addMarkFromTextSelection(newPiiEntities[i], PCCViewer.Mark.Type.TextSelectionRedaction);
             marks.push(newMark);
         }
     });
    
    

    Parameters:

    Name Type Description
    textSelection PCCViewer.ViewerControl~TextSelection | PCCViewer.SearchResult | PCCViewer.PiiEntity

    Indicates the text selection, search result, or PII entity that will include the location for the new mark.

    markType PCCViewer.Mark.Type | string

    Indicates the type of mark being added.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If the textSelection argument is not a valid TextSelection, SearchResult, or PiiEntity.

      Type
      Error
    • If an invalid text based mark type is provided.

      Type
      Error

    Returns:

    The new mark.

    Type
    PCCViewer.Mark

    burnMarkup(optionsopt) → {PCCViewer.BurnRequest}

    Burns redactions and signatures in the document. Note: CAD files are not supported.

    If the parameter options.removeFormFields is invalid, then the PCCViewer.Promise object that is returned will be rejected with the reason set to a PCCViewer.Error object with its code property set to InvalidArgument.

    Example

    function onSuccessfulBurn(burnturl) {
       alert("burntURL = " + burnturl);
       console.log(burnturl);
    }
    function onFailedBurn(error) {
       alert("burn Process failed, error:" + (error.message ? error.message : error));
    }
    
    // A BurnRequest object is created by and returned from the call to the burnMarkup method
    var burnRequest = viewerControl.burnMarkup();
    burnRequest.then(onSuccessfulBurn, onFailedBurn);
    
    //register some events
    burnRequest
      .on(PCCViewer.BurnRequest.EventType.BurnCompleted,
          function(ev) {
              alert("Document burn completed.");
          })
      .on(PCCViewer.BurnRequest.EventType.BurnProgress,
          function(event) {
              alert("Burn progress: " + event.percent + "%");
          })
      .on(PCCViewer.BurnRequest.EventType.BurnFailed,
          function(event) {
              alert("Document burn failed.");
          });
    
      // Also, methods on the burnRequest object can be used
    
      // get the options used to burn the document.
      var optionsUsed = burnRequest.getOptions();
    
      //if the process is still incomplete, cancel can be used to stop queries to the server.
      if (burnRequest.getProgress() >= 0 && burnRequest.getProgress() < 100) {
           burnRequest.cancel();
      }
    
    

    Parameters:

    Name Type Attributes Description
    options Object <optional>

    This optional parameter specifies burn options to be used for burning the document.

    Properties
    Name Type Attributes Default Description
    marks PCCViewer.Mark | Array.<PCCViewer.Mark> <optional>

    Indicates which marks to burn regardless of their type.

    burnSignatures boolean <optional>
    true

    Indicates whether signatures are required to be burned. Note: If options.marks exists, this parameter is ignored.

    burnRedactions boolean <optional>
    true

    Indicates whether redactions are required to be burned. Note: If options.marks exists, this parameter is ignored.

    burnAnnotations boolean <optional>
    false

    Indicates whether annotations are required to be burned. Note: If options.marks exists, this parameter is ignored.

    filename string <optional>

    Sets the value of the Content-Disposition filename in the header of the response from the URL to download the document. If not set, then the burned document will be downloaded with a default filename.

    removeFormFields Array.<string> <optional>

    Specifies a list of the types of form fields to remove from the document. Currently, only a list including the value 'acroform' is supported. If not set, then form fields are not removed.

    redactionOptions Object <optional>

    The parameters object takes the following properties:

    • mode {PCCViewer.RedactionViewMode enum}. How redactions should be applied. May be one of the following:
    • "Normal" (default) - Actually redact the document, removing document content covered by redactions, drawing opaque redaction rectangles, and drawing any associated redaction reason text in the center of the rectangles.
    • "Draft" - Do NOT actually redact the document. Instead, indicate which parts of the document would be redacted by drawing partially transparent redaction rectangles over the parts of the document that would be redacted. In order to avoid interfering with the original document content, redaction reason text will not be drawn in the center of the transparent redaction rectangles.
    • draftOptions {object} - Options to apply when mode is set to "Draft" (ignored otherwise). May contain:
    • opacity {number} Controls the opacity of redactions when redactionOptions.mode is set to "Draft". Must be a value between 0 and 1 where 0 is fully transparent and 1 is fully opaque. Default is 0.2.
    See:

    Returns:

    A result BurnRequest for this task.

    Type
    PCCViewer.BurnRequest

    canPrintMarks() → {boolean}

    Informs whether the current browser is capable of printing the annotations and redactions on a document. If true, the document can be printed with annotations and redactions. If false, the document will be printed without annotations, regardless of the print request made.

    Example

    var printWithMarks = true;
    viewerControl.print({
     includeMarks: (printWithMarks && viewerControl.canPrintMarks())
    });
    
    

    Returns:

    A value indicating whether the browser is capable of printing annotations and redactions on a document.

    Type
    boolean

    changeToFirstPage() → {PCCViewer.ViewerControl}

    Sets the current page of the viewer to the first page of the document.

    Note: Does nothing if the current page is the first page of the document.

    Example

    viewerControl.changeToFirstPage();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    changeToLastPage() → {PCCViewer.ViewerControl}

    Sets the current page of the viewer to the last known page of the document.

    Note: Does nothing if the current page is the last known page of the document.

    Example

    viewerControl.changeToLastPage();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    changeToNextPage() → {PCCViewer.ViewerControl}

    Sets the current page of the viewer to the next page of the document.

    Note: Does nothing if the current page is the last known page of the document.

    Example

    viewerControl.changeToNextPage();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    changeToPrevPage() → {PCCViewer.ViewerControl}

    Sets the current page of the viewer to the previous page of the document.

    Example

    viewerControl.changeToPrevPage();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    changeViewingSession(viewingSessionId, isRestorable) → {PCCViewer.ViewerControl}

    Changes the viewer to a different viewing session, allowing the viewer to work with a different document. If you intend to return to the current viewing session in the future, set isRestorable to true. Otherwise, the current viewer state and any annotation data in memory will be disposed.

    Example

    viewerControl.changeViewingSession(anotherViewingSessionId)
        .on(PCCViewer.EventType.ViewingSessionChanged, function(ev) {
            alert("Viewing session changed.");
        });
    
    

    Parameters:

    Name Type Description
    viewingSessionId string

    viewingSessionId for the new viewing session to switch to, changing the document in use for the end user.

    isRestorable boolean

    When true, unsaved changes to markup will be kept in memory and automatically restored if you change back to the current viewing session. When false, unsaved changes to markup will be discarded.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clearMouseSelectedText(textSelection) → {PCCViewer.ViewerControl}

    Deselects the text provided in a TextSelected event.

    Example

    var onTextSelected = function(ev){
        var mark = viewerControl.addMark(ev.textSelection.pageNumber, 'HighlightAnnotation');
        mark.setPosition(ev.textSelection);
    
        // clear the highlighted text
        ViewerControl.clearMouseSelectedText(ev.textSelection);
    };
    
    viewerControl.on('TextSelected', onTextSelected);
    
    

    Parameters:

    Name Type Description
    textSelection PCCViewer.ViewerControl~TextSelection

    The textSelection object provided in the TextSelected event arguments.

    Throws:

    • If textSelection is undefined.

      Type
      Error
    • If textSelection.pageNumber is not a known page number.

      Type
      Error
    • If textSelection.startIndex is not a number or is negative.

      Type
      Error
    • If textSelection.length is not a number or is less than 1.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clearPiiDetection() → {PCCViewer.ViewerControl}

    Clears the PII hit highlights and removes the PiiDetectionRequest from the ViewerControl.

    Example

    viewerControl.detectPii();
    // As PII entities become available, they are highlighted on the document.
    
    // Clear search result highlights from the document.
    viewerControl.clearPiiDetection();
    
    

    Throws:

    If the PCCViewer.EventType.ViewerReady event has not fired prior to using this method.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clearSearch() → {PCCViewer.ViewerControl}

    Clears the search hit highlights and removes the SearchRequest from the ViewerControl.

    After calling this, PCCViewer.ViewerControl#getSearchRequest will not return the last SearchRequest.

    Example

    viewerControl.search("Foo");
    // As search results become available, they are highlighted on the document.
    
    // Clear search result highlights from the document.
    viewerControl.clearSearch();
    
    

    Throws:

    If the PCCViewer.EventType.ViewerReady event has not fired prior to using this method.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clearSelectedPiiEntity() → {PCCViewer.ViewerControl}

    This methods clears the PII entity selection, or in other words, it deselects the PII entity. If there is not a selected PII entity when this method is called, then the method has no effect.

    This method is offered as a convenience to API callers, who could also call PCCViewer.ViewerControl#setSelectedPiiEntity(null).

    Example

    var piiDetectionRequest = viewerControl.detectPii();
    
    // add events to the PII entity
    piiDetectionRequest.on("PiiDetectionCompleted", function(){
        // get the PII entities
        entities = piiDetectionRequest.getPiiEntities();
    
        // set the entity to the first
        viewerControl.setSelectedPiiEntity(entities[0], true);
    
        // clear the selected search result
        viewerControl.clearSelectedPiiEntity();
    });
    
    
    See:

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clearSelectedSearchResult() → {PCCViewer.ViewerControl}

    This methods clears the search result selection, or in other words, it deselects the search result. If there is not a selected search result when this method is called, then the method has no effect.

    This method is offered as a convenience to API callers, who could also call PCCViewer.ViewerControl#setSelectedSearchResult(null).

    Example

    var searchRequest = viewerControl.search('Accusoft');
    
    // add events to the search request
    searchRequest.on("SearchCompleted", function(){
        // get the search results
        results = searchRequest.getResults();
    
        // set the result to the first
        viewerControl.setSelectedSearchResult(results[0], true);
    
        // clear the selected search result
        viewerControl.clearSelectedSearchResult();
    });
    
    
    See:

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    clientSearch(searchQuery) → {PCCViewer.SearchRequest}

    Searches the text of the document for the given searchQuery. The search is performed client-side, which requires requesting from the server text for each page. This is efficient for smaller documents, but for large documents it is more efficient to use the PCCViewer.ViewerControl#serverSearch method instead.

    This query can be a single search term or a hash specifying one or more terms and options. If only a single search term (string) is supplied, then default options are used.

    Search completes asynchronously. The returned PCCViewer.SearchRequest object, provides events for search progress and members to access search results.

    Example

    // Search on a single term with default options
    var searchRequest = viewerControl.clientSearch("Hello");
    
    // Subscribe to the PartialSearchResultsAvailable event to get search results as they become available.
    searchRequest.on('PartialSearchResultsAvailable', function(_event) {
        // Get the newly available search results.
        var newResults = _event.partialSearchResults;
    });
    
    

    Example

    // Search on multiple terms and specify options
    var searchQuery = {
        searchTerms: [{
            searchTerm: "sub",
            contextPadding: 25,
            highlightColor: '#B22222',
            matchingOptions: {
                beginsWith: true,
            }
        },
        {
            searchTerm: "Accusoft"
        }]
    };
    
    var requestObject = viewerControl.clientSearch(searchQuery);
    
    //subscribe to the search request
    requestObject.on('PartialSearchResultsAvailable', function(_event) {
        var newResults = [];
        //Retrieve results
        newResults = _event.partialSearchResults;
    });
    
    

    Parameters:

    Name Type Description
    searchQuery string | PCCViewer.ViewerControl~SearchQuery

    A value specifying the search query. The value specifies a single search term (string) or an object specifying multiple search terms and options.

    See:

    Returns:

    An object that represents the search request. This object allows the calling code to subscribe to search progress events and access search results.

    Type
    PCCViewer.SearchRequest

    closeCommentsPanel() → {PCCViewer.ViewerControl}

    Closes the comments panel.

    Example

    viewerControl.closeCommentsPanel();
    
    

    Throws:

    If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    convertDocument()

    Deprecated since v11.0 (use the PCCViewer.ViewerControl#requestDocumentConversion method instead).

    convertPageToWindowCoordinates(pageNumber, points) → {Array.<Object>|Object}

    Converts page-based coordinates to the current window coordinates. This allows passing in a coordinate point or an array of points as used in the ViewerControl API, in order to get the position of that point or points relative to the window.

    Parameters:

    Name Type Description
    pageNumber number

    A known page number to the viewer.

    points Array.<Object> | Object

    A point or array of points in page coordinates. Each point will have the following properties:

    Properties
    Name Type Description
    x number

    the x page coordinate

    y number

    the y page coordinate

    Throws:

    • If the PCCViewer.EventType.ViewerReady event has not fired prior to calling this method.

      Type
      Error
    • If pageNumber is not a currently known page.

      Type
      Error
    • If any of the points do not have a valid x and y numeric parameters.

      Type
      Error

    Returns:

    A window point or an array of window points, depending on how the method was called. These points will be in the same order as the points passed into the function. Each window point will have the following parameters:

    • clientX {number} The x window coordinate in pixels.
    • clientY {number} The y window coordinate in pixels.
    Type
    Array.<Object> | Object

    convertToHighlight()

    Deprecated since v13.16 (use the PCCViewer.ViewerControl#addMarkFromTextSelection method instead).

    convertToRedaction()

    Deprecated since v13.16 (use the PCCViewer.ViewerControl#addMarkFromTextSelection method instead).

    copyMarks(marks) → {Array.<PCCViewer.Mark>}

    Makes a copy of the specified marks.

    Note: This method requires that attributes of each page referenced by the marks have been obtained by the viewer prior to calling. Use PCCViewer.ViewerControl#requestPageAttributes to obtain the necessary page attributes before calling this method.

    Example

    // Make a copy of the selected marks.
    var copiedMarks = viewerControl.copyMarks(viewerControl.getSelectedMarks());
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An array of marks to copy.

    Throws:

    If marks is not an array of marks known to the viewer.

    Type
    Error

    Returns:

    An array of the copied marks.

    Type
    Array.<PCCViewer.Mark>

    deleteAllMarks() → {PCCViewer.ViewerControl}

    Deletes all marks in all the pages of the document.

    Example

    viewerControl.deleteAllMarks();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    deleteMarks(marks) → {PCCViewer.ViewerControl}

    Deletes the specified marks.

    Example

    // delete all selected marks
    viewerControl.deleteMarks(viewer.getSelectedMarks());
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An Array of objects of type PCCViewer.Mark.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    deselectAllMarks() → {PCCViewer.ViewerControl}

    Deselects all previously selected marks.

    Example

    viewerControl.deselectAllMarks();
    
    

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    deselectMarks(marks) → {PCCViewer.ViewerControl}

    Deselects the marks provided in the parameter array object.

    Example

    // deselect all marks with an odd-number ID
    viewerControl.getSelectedMarks().forEach(function(mark){
        var arr = [];
        if (+mark.getId() % 2) arr.push(mark);
        viewerControl.deselectMarks(arr);
    });
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An array of PCCViewer.Mark objects that exist in the document and need to be deselected.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to calling this method.

      Type
      Error
    • If any of the mark objects are not valid PCCViewer.Mark objects, the id of the mark provided does not match the id of mark loaded in the viewer, or the mark provided was not previously added to the document pages.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    deserializeMarks(values)

    Deserializes JSON or a JSON-like object to PCCViewer.Mark objects, and adds them to the ViewerControl. This will display all deserialized marks.

    Example

    var markData = {
        "type": "RectangleAnnotation",
        "rectangle": {
            "x": 0,
            "y": 10,
            "width": 200,
            "height": 200
        },
        "fillColor": "#FB0404",
        "lineWidth": 4,
        "pageNumber": 1,
        "uid": "dW9qaV8yMDE5LTA4LTAxVDA2OjUzOjA1LjgxOVpfazhhbDFi",
        "data": {},
        "conversation": {
            "data": {}
        }
    };
    
    // Deserialize mark from object value
    viewerControl.deserializeMarks(markData);
    
    // Deserialize mark from JSON string
    var markJson = JSON.stringify(markData);
    viewerControl.deserializeMarks(markJson);
    
    // Deserialize marks from array of objects
    var markData2 = { ... };
    viewerControl.deserializeMarks([markData, markData2]);
    
    

    Parameters:

    Name Type Description
    values String.<JSON> | Object | Array.<Object>

    The value to deserialize.

    See:

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If the json parameter as a string is not a valid JSON string.

      Type
      Error
    • If any mark has an unknown page number in the pageNumber property. Note that if marks are being added before the PageCountReady event fires, this method will only know about page 1, and throw an error if adding marks to other pages.

      Type
      Error
    • If any mark has an unknown type in the type property.

      Type
      Error

    destroy() → {Promise.<undefined>}

    Closes the ViewerControl and cleans up its resources. After this action, a new viewer can be created in its place.

    Note: If the viewer was created using the jQuery plugin (PCCViewer.Viewer), use the PCCViewer.Viewer.destroy method instead.

    Example

    var element = document.querySelector('#mydiv');
    var viewerControl = new PCCViewer.ViewerControl(element, options);
    
    viewerControl.destroy().then(() => {
      console.log('the viewer has been destroyed');
    });
    
    

    Returns:

    a Promise object, on success indicating the ViewerControl has been destroyed. This promise resolves with undefined.

    Type
    Promise.<undefined>

    detectPii(options) → {PCCViewer.PiiDetectionRequest}

    Requests the PII of the document.

    A PII detection request completes asynchronously. The returned PCCViewer.PiiDetectionRequest object provides events for PII detection progress and members to access the detected PII.

    Example

    var piiDetectionRequest = viewerControl.detectPii();
    
    // Subscribe to the PartialPiiAvailable event to get PII entities as they become available.
    piiDetectionRequest.on('PartialPiiAvailable', function(eventArgs) {
        // Get the newly available PII entities
        var newPiiEntities = eventArgs.partialPiiEntities;
    });
    
    

    Parameters:

    Name Type Description
    options Object

    An object that contains a highlightColor value, which specifies the highlight color of the PII entity in hex notation (e.g. "#F1F1F1"). This parameter is optional. If an Object containing a highlightColor is not defined, then the default "#1C86EE" is used.

    See:

    Returns:

    An object that represents the PII detection request. This object allows the calling code to subscribe to PII detection progress events and access the detected PII.

    Type
    PCCViewer.PiiDetectionRequest

    disposePageText(pageNumber) → {PCCViewer.ViewerControl}

    Disposes text for the specified page.

    The text for any page requested programmatically by using the PCCViewer.ViewerControl#requestPageText method is not automatically disposed, even when the ViewerControl discardOutOfViewText parameter is set to true. You must use the disposePageText method to dispose of the text when you no longer need it.

    If the specified page is currently displayed when calling this method, the page text will not be disposed immediately, but will be disposed when the page is scrolled out of view and no longer displayed.

    Client search depends on the page text, so page text is not disposed after performing client search.

    Example

    viewerControl.disposePageText(10);
    
    

    Parameters:

    Name Type Description
    pageNumber number

    Page text is disposed for this page number.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If the pageNumber value is not a number.

      Type
      Error
    • If the pageNumber value is out of range.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    documentHasText() → {PCCViewer.Promise}

    Indicates whether or not any pages in the document have text. This method returns a promise, which can resolve at an indefinite time. This promise will resolve at the first instance of finding text in the document, but will not actively search for text if none is yet found. Unless this promise has resolved, the user should assume that the document does not contain text.

    For example, in a 100 page document, where only page 80 has text, this promise will not resolve until the user views page 80. If the document were to have no text at all, the promise will not resolve until all 100 pages were viewed by the user.

    The successful callback be passed only a boolean indicating whether the document has any text or not.

    Example

    var promise = viewerControl.documentHasText().then(
        function success(containsTextBool){
            alert('Document has text: ' + (containsTextBool ? 'Yes' : 'No'));
        },
        function fail(error){
            alert('Document has text: unknown due to error "' + error.message + '"');
        }
    );
    
    

    Returns:

    a Promise object.

    Type
    PCCViewer.Promise

    enterTextMarkEditingMode(mark) → {PCCViewer.ViewerControl}

    Puts a displayed PCCViewer.Mark object of type TextInputSignature, TextAreaSignature, TextRedaction, or TextAnnotation into editing mode. In editing mode, a text input or text box will be drawn for the mark and the input will have focus. When in editing mode, the end user type to modify the text of the mark.

    All marks other than the specified mark will be taken out of text mark editing mode.

    Note that if the mark is not on a page that is currently displayed, then this method may have no perceived effect. The act of changing pages to bring the off screen page into view would take the focus off of the mark that is in editing mode.

    Example

    // Add a mark
    var myMark = viewerControl.addMark(4, PCCViewer.Mark.Type.TextAnnotation)
        .setRectangle({
            x: 0,
            y: 600,
            width: 500,
            height: 100
        });
    
    // Put the mark in editing mode and scroll to the mark.
    viewerControl.enterTextMarkEditingMode(myMark);
    
    

    Parameters:

    Name Type Description
    mark PCCViewer.Mark | null | undefined

    A PCCViewer.Mark object that will be put in editing mode.

    If a value of null or undefined is given, then all marks will be taken out of text mark editing mode.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    fitContent(fitType) → {PCCViewer.ViewerControl}

    Changes the scaling (zoom) of the document to fit the content in the viewer. How the content is fit in the viewer is based on the specified by the values in the PCCViewer.FitType enumerable.

    Example

    // Explicitly specify the fit type
    viewerControl.fitContent("FullWidth");
    
    // or use the enumeration
    viewerControl.fitContent(PCCViewer.FitType.FullWidth);
    
    

    Parameters:

    Name Type Description
    fitType string

    Specifies how the content will be scaled to fit in the viewer.

    See:

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If the value of fitType is unknown.

      Type
      Error
    • If the view mode is set to "EqualFitPages" or "EqualWidthPages", and the value of fitType is "ActualSize". Instead, pass a value of 1 to the PCCViewer.ViewerControl#setScaleFactor method to scale the first page to actual size.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    getActiveMarkupLayer() → {PCCViewer.MarkupLayer}

    Gets the viewer control's active markup layer.

    Example

    var activeMarkupLayer = viewerControl.getActiveMarkupLayer();
    
    

    Returns:

    The viewer control's active markup layer.

    Type
    PCCViewer.MarkupLayer

    getAllMarks() → {Array.<PCCViewer.Mark>}

    Gets all marks.

    Example

    var allMarks = viewer.getAllMarks();
    
    

    Returns:

    An array of PCCViewer.Mark objects. Note: Returns an empty array if the viewer has not been initialized.

    Type
    Array.<PCCViewer.Mark>

    getAtMaxScale() → {boolean}

    Gets a value that indicates whether the viewer is currently at the maximum scale factor. As long as this value is true, the ViewerControl do nothing if asked to zoom in any further.

    This method determines the value each time, and will be affected by the following:

    1. The viewer scale changes due to zoomIn, zoomOut, or fitContent.
    2. The window resizes.
    3. The div that holds the viewer control is resized.

    Example

    // Check for change after the viewer scale changes
    viewerControl.on(PCCViewer.EventType.ScaleChanged, function(ev){
        var atMax = viewer.getAtMaxScale();
    }
    
    

    Example

    // Check for change when the window resizes (using jQuery)
    $(window).resize(function() {
        var atMax = viewer.getAtMaxScale();
    });
    
    
    See:

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    A value that indicates whether the viewer is currently at maximum zoom.

    Type
    boolean

    getAtMinScale() → {boolean}

    Gets a value that indicates whether the viewer is currently at the minimum scale factor. As long as this value is true, the ViewerControl do nothing if asked to zoom out any further.

    This method determines the value each time, and will be affected by the following:

    1. The viewer scale changes due to zoomIn, zoomOut, or fitContent.
    2. The window resizes.
    3. The div that holds the viewer control is resized.

    Example

    // Check for change after the viewer scale changes
    viewerControl.on(PCCViewer.EventType.ScaleChanged, function(ev){
        var atMax = viewer.getAtMinScale();
    }
    
    

    Example

    // Check for change when the window resizes (using jQuery)
    $(window).resize(function() {
        var atMax = viewer.getAtMinScale();
    });
    
    
    See:

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    A value that indicates whether the viewer is currently at minimum zoom.

    Type
    boolean

    getCharacterIndex(sortableObject) → {Number}

    Returns the index of the character at the location of the specified object. If there is no character at the location, the index of the character before the location (based on the closest line of text) is returned.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // get the sort index
    if (theFirstMark) var firstMarkSortIndex = viewerControl.getCharacterIndex(theFirstMark);
    
    

    Parameters:

    Name Type Description
    sortableObject PCCViewer.Mark | PCCViewer.SearchResult | Object

    A mark or search result in a page, or an object containing pageNumber, x, and y values.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If sortableObject is not a valid PCCViewer.Mark or PCCViewer.SearchResult, or if it is not an Object with valid pageNumber, x, and y values. When specifying a pageNumber greater than 1, this method requires that the PageCountReady event has been triggered, otherwise an error is thrown.

      Type
      Error

    Returns:

    The text index at or before the position of the specified object.

    Type
    Number

    getClientRestrictions() → {Promise.<Object>}

    Gets the status of client-side functionality restrictions.

    Example

    var restrictions = await viewerControl.getClientRestrictions();
    
    // restrictions now contains:
    // {
    //     sharpening: "enabled",
    //     gamma: "enabled",
    //     svgLineWidthMuliplier: "enabled",
    //     print: "enabled"
    // }
    
    

    Returns:

    An object with key/value pairs representing the status of functionality restrictions. For entries with a value of ‘disabled’, corresponding API calls to that functionality will return an error or remain nonfunctional. The viewer should disable the corresponding UI functionality. Entries with a value of ‘enabled’ should have their corresponding API calls behave normally.

    The object has the following properties:

    Type
    Promise.<Object>

    getConversationDOMFactory() → {function}

    Gets the conversation DOM factory function. The default factory function is returned if a factory function has not been set using the PCCViewer.ViewerControl#setConversationDOMFactory method.

    Returns:

    The function for creating a conversation DOM element.

    Type
    function

    getCurrentMouseTool() → {string}

    Gets the current mouse tool of the viewer.

    Example

    // get the current mouse tool name
    var mouseToolName = viewerControl.getCurrentMouseTool();
    
    // get the actual MouseTool object
    var mouseToolObject = PCCViewer.MouseTools.getMouseTool(mouseToolName);
    
    
    See:

    Returns:

    A value indicating the name of the current mouse tool.

    Type
    string

    getDownloadDocumentURL() → {string}

    Gets the URL to download the original document.

    Example

    // get the URL
    var documentURL = viewerControl.downloadDocument();
    
    // download the document
    window.location.href = documentURL;
    
    
    See:
    • The help section titled "Digital Rights Management Configuration" for information on disabling document download.

    Returns:

    The URL for downloading the original document. This URL is relative to current page.

    Type
    string

    getGamma() → {Number}

    Gets the gamma factor for the document.

    Example

    var gamma = viewerControl.getGamma();
    
    

    Returns:

    The current gamma factor for the document.

    Type
    Number

    getIsCommentsPanelOpen() → {boolean}

    Returns a value (true or false) indicating if the comments panel is open.

    Example

    var isCommentsPanelOpen = viewerControl.getIsCommentsPanelOpen();  // true if comments panel is open
    
    

    Throws:

    If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

    Type
    Error

    Returns:

    A value indicating if the comments panel is open.

    Type
    boolean

    getMarkById(markId) → {PCCViewer.Mark}

    Gets the specified mark.

    Example

    var mark = viewer.getMarkById(1);
    
    

    Parameters:

    Name Type Description
    markId number

    The ID of the mark to retrieve.

    Returns:

    The mark that corresponds to the specified ID.

    Type
    PCCViewer.Mark

    getMarkHandleMode() → {PCCViewer.MarkHandleMode}

    Gets the mark handle mode.

    Returns:

    The mark handle mode.

    Type
    PCCViewer.MarkHandleMode

    getMarksByType(markType) → {Array.<PCCViewer.Mark>}

    Get marks by type.

    Example

    var marksByType = viewer.getMarksByType(markType);
    
    

    Parameters:

    Name Type Description
    markType PCCViewer.Mark.Type | string

    The mark type being requested. Note: Returns an empty array if the viewer has not been initialized.

    See:

    Throws:

    If the parameter markType is an invalid mark type.

    Type
    Error

    Returns:

    An array of PCCViewer.Mark objects of the requested type.

    Type
    Array.<PCCViewer.Mark>

    getMarkupLayerCollection() → {PCCViewer.MarkupLayerCollection}

    Gets the viewer control's markup layer collection.

    Example

    var markupLayerCollection = viewerControl.getMarkupLayerCollection();
    
    

    Returns:

    The viewer control's markup layer collection.

    Type
    PCCViewer.MarkupLayerCollection

    getMaxScaleFactor() → {number}

    Gets the maximum scale limit.

    Example

    var maxScaleFactor = viewerControl.getMaxScaleFactor();
    viewerControl.setScaleFactor(maxScaleFactor); // Zoom in to the maximum scale limit.
    
    

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to calling this method.

    Type
    Error

    Returns:

    A number indicating the maximum limit at which the document can be scaled.

    Type
    number

    getMinScaleFactor() → {number}

    Gets the minimum scale limit.

    Example

    var minScaleFactor = viewerControl.getMinScaleFactor();
    viewerControl.setScaleFactor(minScaleFactor); // Zoom out to the minimum scale limit.
    
    

    Throws:

    If the PCCViewer.EventType.ViewerReady event was not fired prior to calling this method.

    Type
    Error

    Returns:

    A number indicating the minimum limit at which the document can be scaled.

    Type
    number

    getPageCount() → {number}

    Gets the known page count of the current document.

    This value is updated when the viewer gets the page count or estimated page count from the server. Subscribe to the PCCViewer.EventType.PageCountReady and PCCViewer.EventType.EstimatedPageCountReady events to be notified when the viewer gets the page count from the server.

    The initial value is 1, before any page count event.

    Example

    // First, create the pccViewer.
    var viewerControl = $("#viewer").pccViewer(viewerOptions).viewerControl;
    
    function pageCountReadyHandler(event) {
        // The page count has now been determined.
        var pageCount = viewer.getPageCount();
        alert("Number of pages = " + pageCount);
    
        // Now, unsubscribe from the event.
        viewerControl.off("PageCountReady", pageCountReadyHandler);
    }
    
    // Subscribe to the PageCountReady event exposed by the API
    viewerControl.on("PageCountReady", pageCountReadyHandler);
    
    
    See:

    Returns:

    The known page count.

    Type
    number

    getPageLayout() → {PCCViewer.PageLayout}

    Gets the page layout. This defines how the document pages will be arranged, based on the values of the PCCViewer.PageLayout enumeration.

    Example

    var pageLayout = viewerControl.getPageLayout();
    
    
    See:

    Returns:

    A value indicating the page layout.

    Type
    PCCViewer.PageLayout

    getPageNumber() → {number}

    Gets the current page number of the viewer. This is a 1-based value, so the first page of a document is 1.

    Example

    var currentPageNumber = viewerControl.getPageNumber();
    
    
    See:

    Returns:

    The current page of the viewer.

    Note: A value of 1 is returned before page count is available.

    Type
    number

    getPageRotation(pageNumber) → {number}

    Gets the page rotation value for the specified page number.

    Example

    // first create the pccViewer : Note: if the viewer object has already been created, do not re-create it.
    var viewerControl = $("#viewer").pccViewer(viewerOptions).viewerControl;
    
    var pageNumber = 2;
    var rotationAngle = viewerControl.getPageRotation(pageNumber);
    
    

    Parameters:

    Name Type Description
    pageNumber number | string

    This is an optional parameter. A 1-based page number of the page. An optional string representation of a valid number is also accepted as a parameter. If this parameter is not provided, the implied pageNumber will be the currentPage.

    Throws:

    • If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If the provided optional parameter pageNumber is less than 1 or greater than the value returned by PCCViewer.ViewerControl#getPageCount.

      Type
      Error
    • If the provided optional parameter pageNumber is not a number or a string representation of a number.

      Type
      Error
    • If the provided optional parameter pageNumber is not an integer page number.

      Type
      Error

    Returns:

    The rotation amount in degrees clockwise.

    Type
    number

    getRedactionViewMode() → {PCCViewer.RedactionViewMode}

    Gets the redaction view mode. This defines whether the redaction rectangles would show the underlying document content text PCCViewer.RedactionViewMode enumerable values.

    Example

    var viewMode = viewerControl.getRedactionViewMode();
    
    
    See:

    Returns:

    A value indicating the redaction view mode.

    Type
    PCCViewer.RedactionViewMode

    getSavedMarkupNames() → {PCCViewer.Promise}

    Gets a list of all saved markups from the server for the current document.

    If unable to retrieve markup list from server, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to MarkupListFail.

    If AJAX is not supported, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to AjaxUnsupported.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    The PCCViewer.Promise~onFulfilled function gets passed an Array of Objects. Each object will have a name property, which is a string representation of the name used to save the markup.

    Example

    viewerControl.getSavedMarkupNames().then(
        function onSuccess(markupNameObjects) {
            var namesArray = [];
            for (var i = 0; i < markupNames.length; i++) {
                namesArray.push(markupNames[i].name);
            }
            alert(namesArray.join(', ');
        },
        function onFailure(error) {
            alert((error.message ? error.message : error));
        }
    );
    
    

    Returns:

    Type
    PCCViewer.Promise

    getScaleFactor() → {number}

    Gets the scale factor of the viewer.

    Example

    var scaleFactor = viewerControl.getScaleFactor();
    
    
    See:

    Returns:

    A value indicating the scale factor to use in the viewer, with 1 being 100% zoom.

    For "Document" and '"SinglePage"' view mode, the scale factor represents the amount that each page in the document is scaled. For "EqualFitPages" view mode, the scale factor represents the amount that the first page of the document is scaled.

    Type
    number

    getSearchRequest() → {PCCViewer.SearchRequest}

    Gets the SearchRequest object from the last call to PCCViewer.ViewerControl#search.

    Example

    var searchRequestA = viewerControl.search("Foo");
    var searchRequestB = viewerControl.getSearchRequest();
    searchRequestA === searchRequestB;   // true
    
    

    Returns:

    The SearchRequest from the last search, or null if a search has not been performed or if the search has been cleared with PCCViewer.ViewerControl#clearSearch.

    Type
    PCCViewer.SearchRequest

    getSelectedConversation() → {PCCViewer.Conversation}

    Gets the selected conversation.

    Example

    var selectedConversation = viewerControl.getSelectedConversation();
    
    
    See:

    Returns:

    The selected conversation, or null if no conversation is currently selected.

    Type
    PCCViewer.Conversation

    getSelectedMarks() → {Array.<PCCViewer.Mark>}

    Obtains all the selected marks in the currently loaded document. If none of the marks are selected or if the document does not contain any marks then the returned array will be empty.

    Example

    var selectedMarks = viewerControl.getSelectedMarks();
    
    if (selectedMarks.length) alert(selectedMarks.length + " marks are currently selected");
    else alert("No marks are currently selected");
    
    

    Returns:

    An array of selected PCCViewer.Mark objects.

    Type
    Array.<PCCViewer.Mark>

    getSelectedPiiEntity() → {PCCViewer.PiiEntity|null}

    Gets the selected PCCViewer.PiiEntity object.

    Returns:

    The PCCViewer.PiiEntity object. Returns null if no PII entity is selected.

    Type
    PCCViewer.PiiEntity | null

    getSelectedSearchResult() → {PCCViewer.SearchResult|null}

    Gets the selected PCCViewer.SearchResult object.

    Returns:

    The PCCViewer.SearchResult object. Returns null if no search result is selected.

    Type
    PCCViewer.SearchResult | null

    getSharpening() → {Number}

    gets the sharpening factor for the document.

    Example

    var sharpening = viewerControl.getSharpening();
    
    

    Returns:

    the current sharpening factor for the document.

    Type
    Number

    getSvgLineWidthMultiplier() → {Number}

    Gets the current multiplier used to adjust SVG line widths in the document.

    Example

    var svgLineWidthMultiplier = viewerControl.getSvgLineWidthMultiplier();
    
    

    Returns:

    The current svg line-width multiplier for the document.

    Type
    Number

    getViewMode() → {PCCViewer.ViewMode}

    Gets the view mode. This defines how the document pages will be scaled, based on the values of the PCCViewer.ViewMode enumerable values.

    Example

    var viewMode = viewerControl.getViewMode();
    
    
    See:

    Returns:

    A value indicating the view mode.

    Type
    PCCViewer.ViewMode

    hideMarks(marks) → {PCCViewer.ViewerControl}

    Hides the specified marks.

    Example

    // hides all selected marks
    viewerControl.hideMarks(viewer.getSelectedMarks());
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An Array of objects of type PCCViewer.Mark.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    isPageTextReady(pageNumber) → {boolean}

    Returns a value indicating if the ViewerControl has loaded text for a page from the server.

    Several of the ViewerControl's methods require that the ViewerControl has loaded the text for the page. These methods will not work if the text for the target page(s) is not loaded. This set of methods includes:

    The ViewerControl may delay loading of text for a page, so it is not safe to assume that the ViewerControl has text for a page when ViewerReady is triggered. However, if you have gotten page text through the viewer, then it is safe to assume the viewer has text for the page. For example, if you get text through a SearchResult generated by PCCViewer.ViewerControl#search or by calling PCCViewer.ViewerControl#requestPageText, then the viewer will have loaded page text from the server.

    Example

    if (!viewerControl.isPageTextReady(1)) {
        viewerControl.requestPageText(1).then(
            function(pageText) {
                highlightSomeText({
                    startIndex: 0,
                    length: pageText.length
                });
            }
        );
    } else {
        // Note that it's pretty silly to blindly highlight text, you would almost always want to know
        // the text that you are trying to highlight before calling the API to set the position. But, this is just
        // an example to demonstrate when you don't *have* to request the page text.
        highlightSomeText({startIndex: 0, length: 5});
    }
    
    // Note: An alternative to the if-else above, would be to always call requestPageText, which will immediately resolve
    // if the viewer already has page text. Using this approach, you don't need to call `isPageTextReady`.
    // viewerControl.requestPageText(1).then(
    //     function(pageText) {
    //          highlightSomeText({
    //              startIndex: 0,
    //              length: pageText.length
    //          });
    //      }
    // );
    
    function highlightSomeText(position) {
        viewerControl.addMark(1, "HighlightAnnotation")
            .setPosition(position);
    }
    
    

    Parameters:

    Name Type Description
    pageNumber number

    The method checks if page text is ready for this page number.

    See:

    Throws:

    If the pageNumber argument is less than 1 or greater than the page count of the document.

    Type
    Error

    Returns:

    A value indicating if the ViewerControl has loaded text for a page from the server.

    Type
    boolean

    loadAttachments() → {PCCViewer.Promise}

    Gets a list of all attachments of the document currently loaded on the viewer.

    If unable to retrieve the attachment list from server, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to AttachmentListFail.

    If AJAX is not supported, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to AjaxUnsupported.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    The PCCViewer.Promise~onFulfilled function gets passed an array of attachment objects.

    Example

    viewerControl.loadAttachments().then(
        function onSuccess(attachments) {
            var fileNames = [];
            for (var i = 0; i < attachments.length; i++) {
                fileNames.push(attachments[i].name);
            }
            alert(fileNames.join(', ');
        },
        function onFailure(error) {
            alert((error.message ? error.message : error));
        }
    );
    
    

    Returns:

    Type
    PCCViewer.Promise

    loadMarkup(recordName, retainExistingMarksopt, markupLayeropt) → {PCCViewer.Promise}

    Loads the markup with the specified name from the server. This returns a PCCViewer.Promise object.

    If the parameter recordName is invalid, then the PCCViewer.Promise object that is returned will be rejected with the reason set to a PCCViewer.Error object with its code property set to InvalidAnnotationRecord.

    If the optional parameters retainExistingMarks or markupLayer are specified but invalid, then the PCCViewer.Promise object that is returned will be rejected with the reason set to a `PCCViewer.Error' object.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    If AJAX is not supported, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to AjaxUnsupported.

    Note: Any existing marks in the document are removed before marks are loaded.

    Note: This method triggers the following events: PCCViewer.EventType.MarkCreated, PCCViewer.EventType.MarkChanged and PCCViewer.EventType.MarkChanged.

    Example

    viewerControl.loadMarkup("mymarkup").then(
    function onResolved() {
        // update the UI, or whatever... because the markup loaded successfully
    },
    function onRejected(error) {
        alert("loading failed! " + (error.message ? error.message : error));
    });
    
    

    Parameters:

    Name Type Attributes Default Description
    recordName string

    Name of the annotation record to be loaded.

    retainExistingMarks boolean <optional>
    true

    If true, retains the existing marks.

    markupLayer PCCViewer.MarkupLayer <optional>

    If set to a valid markup layer, the marks are added to the specified markup layer. If not set, the marks are added to the currently active markup layer. Otherwise, clears the existing marks before loading new marks.

    See:

    Returns:

    a Promise object.

    Type
    PCCViewer.Promise

    loadMarkupLayers(layerRecordIds) → {PCCViewer.LoadMarkupLayersRequest}

    Load markup layer records from the server. This method loads one or more layers from the server asynchronously, and returns a PCCViewer.LoadMarkupLayersRequest object.

    LoadMarkupLayersRequest is a thenable object, which allows Promise-like interactions. Its .then() method's onFulfilled callback will receive an object containing PCCViewer.MarkupLayer objects representing the loaded layers, and the onRejected callback will receive a PCCViewer.Error object defining why the load function failed.

    Example

    // load a layer
    
    viewerControl.loadMarkupLayers('abc123').then(
        function onSuccess(layers){
            console.log('layer loaded successfully', layers[0].getId());
        },
        function onFailure(reason){
            console.log('layer failed to load:', reason.code, reason.message);
        }
    );
    
    

    Parameters:

    Name Type Description
    layerRecordIds string | Array.<string>

    A string or an array of layer record IDs.

    Throws:

    For markup that contains marks of type RectangleRedaction and TextSelectionRedaction if the reasons property defined for them and ViewerControlOptions.enableMultipleRedactionReasons property was set to false when initializing ViewerControl.

    Type
    Error

    Returns:

    A LoadMarkupLayersRequest object.

    Type
    PCCViewer.LoadMarkupLayersRequest

    moveMarkBackward(mark) → {PCCViewer.ViewerControl}

    Moves the specified mark one slot backward from its position in the internal z-order. When the marks overlap, marks that are higher in this internal z-order are drawn over the marks that are lower.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // move it backward
    if (theFirstMark) viewerControl.moveMarkBackward(theFirstMark);
    
    

    Parameters:

    Name Type Description
    mark PCCViewer.Mark

    The mark being moved.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    moveMarkForward(mark) → {PCCViewer.ViewerControl}

    Moves the specified mark one slot toward the top of the internal z-order. When the marks overlap, marks that are higher in this internal z-order are drawn over the marks that are lower.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // move it forward
    if (theFirstMark) viewerControl.moveMarkForward(theFirstMark);
    
    

    Parameters:

    Name Type Description
    mark PCCViewer.Mark

    The mark being moved.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    moveMarkToBack(mark) → {PCCViewer.ViewerControl}

    Moves the specified mark to the back. When the marks overlap, the marks that are higher in the internal z-order on a page are drawn over the ones that are lower.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // move to back
    if (theFirstMark) viewerControl.moveMarkToBack(theFirstMark);
    
    

    Parameters:

    Name Type Description
    mark PCCViewer.Mark

    The mark being moved.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    moveMarkToFront(mark) → {PCCViewer.ViewerControl}

    Moves the specified mark to the front or to the top of internal z-order on a page. When the marks overlap, the marks with higher internal z-order are drawn over the ones that are lower.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // move to front
    if (theFirstMark) viewerControl.moveMarkToFront(theFirstMark);
    
    

    Parameters:

    Name Type Description
    mark PCCViewer.Mark

    The mark being moved.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    off(eventType, handler) → {PCCViewer.ViewerControl}

    Unsubscribe an event handler from a specified event type.

    Typically, an event is unsubscribed when you no longer want further notification of the event.

    Example

    // Our event handler declaration
    function handler(event) {
        alert("An event was fired: " + event.getType());
    }
    
    // Subscribe
    viewerControl
        .on("PageChanged", handler)
        .on("PageCountReady", handler);
    
    // Un-subscribe
    viewerControl
        .off("PageChanged", handler)                        // Use string literals or the enum.
        .off(PCCViewer.EventType.PageCountReady, handler);  // Chain unsubscription.
    
    

    Parameters:

    Name Type Description
    eventType string

    A string specifying the event type. See PCCViewer.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that was attached previously to the ViewerControl.

    Note: This must be the same function object previously passed to PCCViewer.ViewerControl#on. It cannot be an different object that is functionally equivalent.

    See:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    on(eventType, handler) → {PCCViewer.ViewerControl}

    Subscribe an event handler to an event of a specified type.

    Example

    // Create the viewer and get the ViewerControl object.
    var viewerControl = $("#viewer").pccViewer(viewerOptions}).viewerControl;
    
    // Our event handler declaration
    function handler(event) {
        alert("An event was fired: " + event.getType());
    }
    
    viewerControl
        .on(PCCViewer.EventType.PageChanged, handler)    // Use the PCCViewer.EventType enum.
        .on(PCCViewer.EventType.PageDisplayed, handler)  // Chain event subscription.
        .on("PageLoadFailed", handler);                  // Use string literals instead of the EventType enum.
    
    

    Parameters:

    Name Type Description
    eventType string

    A string that specifies the event type. This value is case-insensitive. See PCCViewer.EventType for a list and description of all supported events.

    handler PCCViewer.Event~eventHandler

    A function that will be called whenever the event is triggered.

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    openCommentsPanel() → {PCCViewer.ViewerControl}

    Opens the comments panel.

    Example

    viewerControl.openCommentsPanel();
    
    

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    print(optionsopt) → {PCCViewer.PrintRequest}

    Print the document associated with the PCCViewer.ViewerControl object. Note, the "print" method will only work if the correct "printTemplate" value is passed to "ViewerControlOptions" while initializing the "ViewerControl" instance. It is recommended that this value be set to the content of the "printTemplate.html" file. If this value is set to an empty string (default), then printing will be unavailable.

    Example

    // Prints pages 1 and 3 of the document.
    // Any annotations on those pages will also be printed if supported by the browser.
    viewerControl.print({
        range : "1, 3",
        includeMarks : true
    });
    
    

    Parameters:

    Name Type Attributes Description
    options Object <optional>

    Provides instructions for what to print. The object may have the following properties:

    Properties
    Name Type Attributes Default Description
    range string <optional>
    "all"

    A string representing the pages to print. Pages are separated by commas, and ranges are separated by a hyphen.

    • Sample value: "1, 2, 5-7, 9, 15-20"
    • Sample value: "all"
    orientation string <optional>
    "portrait"

    Describes the orientation of the printed pages.

    • Possible values: "portrait" or "landscape"
    paperSize string <optional>
    "letter"

    Describes what size of paper this document should be printed on.

    margins string <optional>
    "default"

    Whether to respect the default browser margins. This affects IE and Safari.

    • Possible values:
      • "default" When necessary, the pages will be smaller, so that the entire page content can fit on one printed page.
      • "none" Content will always be printed as an 8.5x11 inch page. The user is expected to set the browser print margins to 0.
    includeMarks boolean <optional>
    false

    Whether to print marks. Includes both annotations and redactions.

    includeAnnotations boolean <optional>
    false

    Whether to print annotations.

    includeRedactions boolean <optional>
    false

    Whether to print redactions.

    disableAutoRotation boolean <optional>
    false

    Whether to disable automatic rotation of page content to best fit page dimensions.

    • Possible values: true or false
    includeComments string <optional>
    "none"

    Location to print comments.

    • Possible values: "none", "followingPage", or "documentEnd"
    includeReasons string <optional>
    "none"

    Location to print redaction reasons.

    • Possible values: "none", "followingPage", or "documentEnd"
    redactionViewMode string <optional>
    "Normal"

    Whether to print document content text underneath solid rectangle redactions and selection text redactions marks.

    • Possible values:
      • "Normal" The document context text underneath redaction marks is not printed. The redaction marks are opaque.
      • "Draft" Document content text underneath rectangle redactions and text selection redactions will be visible in the printed document.
    See:

    Throws:

    If the page(s) are out of range.

    Type
    Error

    Returns:

    Type
    PCCViewer.PrintRequest

    refreshConversations(conversationsopt) → {PCCViewer.ViewerControl}

    Forces a DOM refresh of a specified conversation or set of conversations, or all conversations known to the ViewerControl.

    Parameters:

    Name Type Attributes Description
    conversations PCCViewer.Conversation | Array.<PCCViewer.Conversation> <optional>

    A single PCCViewer.Conversation object, or an Array of conversation objects. If this parameter is left undefined, all conversations will be refreshed.

    See:

    Throws:

    • If the conversations parameter is not undefined, a PCCViewer.Conversation object, or an array of conversation objects.

      Type
      Error
    • If any of the PCCViewer.Conversation objects in the parameter are not conversations of known marks.

      Type
      Error
    • If during the refresh, any call to the DOM Factory does not return a valid HTMLElement or a falsy value.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    requestDocumentConversion(optionsopt) → {PCCViewer.ConversionRequest}

    Converts the document and provides an array of URLs to download each converted document. Note that this method currently only supports converting to a single PDF file, so the output array will only contain a single URL.

    Example

    function onSuccessfulConversion(convertedUrl) {
       alert("convertedURL = " + convertedUrl);
       console.log(convertedUrl);
    }
    function onFailedConversion(error) {
       alert("conversion process failed, error:" + (error.message ? error.message : error));
    }
    
    // A new ConversionRequest object is returned by the requestDocumentConversion method
    var conversionRequest = viewerControl.requestDocumentConversion();
    conversionRequest.then(onSuccessfulConversion, onFailedConversion);
    
    // Register some events
    conversionRequest
      .on(PCCViewer.ConversionRequest.EventType.ConversionCompleted,
          function(ev) {
              alert("Document conversion completed.");
          })
      .on(PCCViewer.ConversionRequest.EventType.ConversionProgress,
          function(event) {
              alert("Conversion progress: " + event.percent + "%");
          })
      .on(PCCViewer.ConversionRequest.EventType.ConversionFailed,
          function(event) {
              alert("Document conversion failed.");
          });
    
      // Also, methods on the conversionRequest object can be used
    
      // Get the options used to convert the document.
      var optionsUsed = conversionRequest.getOptions();
    
      // If the process is still incomplete, cancel can be used to stop queries to the server.
      if(conversionRequest.getProgress() >= 0 && conversionRequest.getProgress() < 100) {
           conversionRequest.cancel();
      }
    
    

    Parameters:

    Name Type Attributes Description
    options Object <optional>

    This optional parameter specifies conversion options to be used for converting the format of the document.

    Properties
    Name Type Attributes Description
    filename string <optional>

    Sets the value of the Content-Disposition filename in the header of the response from the URL to download the document. If not set, then the converted document will be downloaded with a default filename.

    See:

    Returns:

    A result ConversionRequest for this task.

    Type
    PCCViewer.ConversionRequest

    Requests the DocumentHyperlinks of the specified page.

    The DocumentHyperlinks will be made available via the returned PCCViewer.Promise object. The PCCViewer.Promise~onFulfilled function will be called with an array of DocumentHyperlinks that are contained on the page. If there are no DocumentHyperlinks on the page, then the returned array will be empty.

    If the pageNumber parameter is invalid at the time the method is called, then the returned PCCViewer.Promise object is rejected with either the reason set to a PCCViewer.Error object with its code property set to InvalidArgument, or a RangeError object if the page number was less than 1 or greater than the value returned by PCCViewer.ViewerControl#getPageCount.

    Example

    // use PCCViewer.ViewerControl#requestDocumentHyperlinks(pageNumber)
    var promise = viewerControl.requestDocumentHyperlinks(10);
    
    promise.then(
        function (documentHyperlinks) {
            // Do something with the array of DocumentHyperlink objects.
            // In this example we iterate over.
            documentHyperlinks.forEach(function(dh) {
                // Alert the href of each hyperlink.
                // Note: don't actually do that because it could be really annoying!
                alert("Found another DocumentHyperlink " + dh.getHref());
            });
        },
        function (error) {
            alert("Something went wrong " + (error.message ? error.message : error));
        }
    );
    
    

    Parameters:

    Name Type Description
    pageNumber number

    DocumentHyperlinks are requested for this page number.

    requestMarkupLayerNames(metadata) → {PCCViewer.Promise}

    Gets a list of all saved markups layer records from the server for the current document. This method utilizes an asynchronous server request to fetch the data, and returns a Promise to resolve the request.

    The onFulfilled callback will receive an object representing the annotationLayerRecords persisted on the server.

    The onRejected callback will receive a PCCViewer.Error object defining why the save function failed.

    The PCCViewer.Promise~onFulfilled function gets passed an Array of Objects. Each object will have 1) a name property, which is a string representation of the name used to save the markup layer record and 2) a layerRecordId property which is the string representation the uniquely identifies the record on the server.

    Example

    viewerControl.requestMarkupLayerNames().then(
        function onSuccess(annotationLayerRecords) {
            var annotationLayerRecordsArray = [];
            for (var i = 0; i < annotationLayerRecords.length; i++) {
                annotationLayerRecordsArray.push(annotationLayerRecords[i].name);
            }
            alert(annotationLayerRecordsArray.join(', '));
        },
        function onFailure(error) {
            alert(error.message ? error.message : error);
        }
    );
    
    

    Parameters:

    Name Type Description
    metadata Object

    An optional JSON object that will be passed to the web tier where it can be used for tasks like user identification. The JSON object will be transformed and then passed as GET parameter(s). The metadata JSON object must be flat and only contain values that are strings, numbers, or booleans.

    Returns:

    Type
    PCCViewer.Promise

    requestPageAttributes() → {PCCViewer.Promise}

    Requests attributes for the specified page.

    If the pageNumber parameter is invalid at the time the method is called, then the returned PCCViewer.Promise object is rejected with either the reason set to a PCCViewer.Error object with its code property set to InvalidArgument, or a RangeError object if the page number was less than 1 or greater than the value returned by PCCViewer.ViewerControl#getPageCount.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    The PCCViewer.Promise~onFulfilled function will receive and Object with properties width and height, representing the reported width and height of each page.

    Example

    var promise = viewerControl.requestPageAttributes(10).then(
        function(pageAttributes) {
            alert('Page 10 attributes: width: ' + pageAttributes.width + ', height: ' + pageAttributes.height);
        },
        function(error) {
            alert('Page attributes retrieval for page 10 failed: ' + (error.message ? error.message : error));
        }
    );
    
    

    Returns:

    a Promise object.

    Type
    PCCViewer.Promise

    requestPageText(pageNumber) → {PCCViewer.Promise}

    Requests the specified text page.

    If the pageNumber parameter is invalid at the time the method is called, then the returned PCCViewer.Promise object is rejected with either the reason set to a PCCViewer.Error object with its code property set to InvalidArgument, or a RangeError object if the page number was less than 1 or greater than the value returned by PCCViewer.ViewerControl#getPageCount.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    The PCCViewer.Promise~onFulfilled function will receive and string value, representing the text found on that page. If the page has no text, this will be an empty string.

    Example

    var promise = viewerControl.requestPageText(10).then(
        function(pageText) {
            alert('Text from page 10: ' + pageText);
        },
        function(error) {
            alert('Text retrieval for page 10 failed: ' + (error.message ? error.message : error));
        }
    );
    
    

    Parameters:

    Name Type Description
    pageNumber number

    Page text is requested for this page number.

    Returns:

    a Promise object.

    Type
    PCCViewer.Promise

    requestRevisions() → {PCCViewer.RevisionsRequest}

    Requests the revisions for a given document comparison.

    Revisions request completes asynchronously. The returned PCCViewer.RevisionsRequest object provides events for revisions retrieval progress and members to access retrieved revisions.

    Example

    // Request revisions with default options:
    var revisionsRequest = viewerControl.requestRevisions();
    
    // Subscribe to the PartialRevisionsAvailable event to get revisions as they become available.
    revisionsRequest.on('PartialRevisionsAvailable', function(_event) {
        // Get the newly available revisions:
        var newRevisions = _event.partialRevisions;
    });
    
    
    See:

    Returns:

    An object that represents the revisions request. This object allows the calling code to subscribe to revisions retrieval progress events and access retrieved revisions.

    Type
    PCCViewer.RevisionsRequest

    rotateDocument(degreesClockwise) → {PCCViewer.ViewerControl}

    Rotates all pages in the document by the specified degrees clockwise, relative to each page's current orientation. Note: Using rotateDocument only affects how the document is displayed and does not affect the original document data.

    Example

    viewerControl.rotateDocument(90);    // Rotates 90 degrees clockwise
    viewerControl.rotateDocument(-90);   // Rotates 90 degrees counter-clockwise
    viewerControl.rotateDocument(180);   // Rotates 180 degrees
    viewerControl.rotateDocument(540);   // Also, rotates 180 degrees
    viewerControl.rotateDocument(100);   // Throws!
    
    

    Parameters:

    Name Type Description
    degreesClockwise number

    Degrees clockwise to rotate each page.

    Valid values are multiples of 90: ..., -270, -180, -90, 0, 90, 180, 270, ...

    Throws:

    • If value of degreesClockwise is not valid. The Error object will contain property message with details of the error.

      Type
      Error
    • If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    rotatePage(degreesClockwise) → {PCCViewer.ViewerControl}

    Rotates the current page by the specified degrees clockwise, relative to the page's current orientation. Note: Using rotatePage only affects how the document is displayed and does not affect the original document data.

    Example

    viewerControl.rotatePage(90);    // Rotates 90 degrees clockwise
    viewerControl.rotatePage(-90);   // Rotates 90 degrees counter-clockwise
    viewerControl.rotatePage(180);   // Rotates 180 degrees
    viewerControl.rotatePage(540);   // Also, rotates 180 degrees
    viewerControl.rotatePage(100);   // Throws!
    
    

    Parameters:

    Name Type Description
    degreesClockwise number

    Degrees clockwise to rotate the page.

    Valid values are multiples of 90: ..., -270, -180, -90, 0, 90, 180, 270, ...

    Throws:

    • If value of degreesClockwise is not valid. The Error object will contain property message with details of the error.

      Type
      Error
    • If the PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    saveMarkup(recordName, optionsopt) → {PCCViewer.Promise}

    Saves all markups in the document to the server as a record with a specified name.

    If the parameter recordName is not a string, then the PCCViewer.Promise object that is returned will be rejected with the reason set to a PCCViewer.Error object with its code property set to InvalidArgument.

    If the parameter recordName contains invalid characters in the name, then the PCCViewer.Promise object that is returned will be rejected with the reason set to a PCCViewer.Error object with its code property set to InvalidCharactersFilename.

    If a server error is encountered, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to Error.

    If AJAX is not supported, then the returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object with its code property set to AjaxUnsupported.

    The PCCViewer.Promise~onFulfilled function will receive the recordName string as its only argument.

    Note: This method will overwrite any previous markup stored with the same name. To prevent duplicates, check to see if the name already exists by using PCCViewer.ViewerControl#getSavedMarkupNames.

    Example

    // The following example will save all annotations and redaction mark types. It will not save signature mark types.
    viewerControl.saveMarkup('cool name').then(
        function success(name) {
            alert('Markup was saved as "' + name + '"');
        },
        function fail(error) {
            alert('Markup was not saved. ' + (error.message ? error.message : error));
        }
    );
    
    // The following will save signature mark types only.
    viewerControl.saveMarkup('cool name', {
        includeAnnotations: false,
        includeRedactions: false,
        includeSignatures: true
    }).then(
        function success(name) {
            alert('Markup was saved as "' + name + '"');
        },
        function fail(error) {
            alert('Markup was not saved. ' + (error.message ? error.message : error));
        }
    );
    
    

    Parameters:

    Name Type Attributes Description
    recordName string

    Name of the annotation record. The markup is saved to an XML file using a filename that includes a unique ID for the document being viewed and the provided annotation record name, so valid filename characters are required. When later viewing the document, the saved markup can be loaded by passing the record name to the PCCViewer.ViewerControl#loadMarkup method.

    options PCCViewer.ViewerControl~SaveMarkupOptions <optional>

    This optional parameter specifies options for the markup types to be saved. The PCCViewer.ViewerControl~SaveMarkupOptions details the options object.

    Throws:

    If ViewerControlOptions.enableMultipleRedactionReasons property was set to true when initializing ViewerControl.

    Type
    Error

    Returns:

    a Promise object, on success returns the given record name after the record is saved.

    Type
    PCCViewer.Promise

    saveMarkupLayer(id) → {PCCViewer.Promise}

    Save a markup layer record to the server. This method saves a single layer to the server asynchronously, and returns a Promise to resolve the request.

    The onFulfilled callback will receive an object containing the layerRecordId of the saved layer.

    The onRejected callback will receive a PCCViewer.Error object defining why the save function failed.

    Example

    // save the current active layer
    var layer = viewerControl.getActiveMarkupLayer();
    
    viewerControl.saveMarkupLayer(layer.getId()).then(
        function onSuccess(layerInfo){
            console.log('layer saved successfully', layerInfo.layerRecordId);
        },
        function onFailure(reason){
            console.log('layer failed to save:', reason.code, reason.message);
        }
    );
    
    

    Parameters:

    Name Type Description
    id String

    The ID of the layer, as returned by layer.getId().

    Returns:

    A Promise object.

    Type
    PCCViewer.Promise

    scrollBy(offsetX, offsetY) → {PCCViewer.ViewerControl}

    Scrolls by specified offset.

    Example

    // scroll by specified offset
    viewerControl.scrollBy(100, 100);
    
    

    Parameters:

    Name Type Description
    offsetX number

    integer that contains value to scroll horizontally. Negative value will scroll to the left.

    offsetY number

    integer that contains value to scroll vertically. Negative value will scroll to the top.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to using this method.

      Type
      Error
    • If target is not an Object with valid offsetX and offsetY values.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    scrollTo(target) → {PCCViewer.ViewerControl}

    Scrolls to the specified object.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // scroll to the mark
    viewerControl.scrollTo(theFirstMark);
    
    

    Parameters:

    Name Type Description
    target PCCViewer.Mark | PCCViewer.Conversation | PCCViewer.SearchResult | PCCViewer.PiiEntity | Object

    The mark, conversation, search result, PII entity or an object (that contains pageNumber, x, and y values) to scroll to.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    scrollToAsync(target) → {PCCViewer.Promise}

    Scrolls to the specified object.

    The returned PCCViewer.Promise object will resolve if the page list has completed all scrolling and the page containing the target is displayed.

    The returned PCCViewer.Promise object is rejected with the reason set to a PCCViewer.Error object if:

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // scroll to the mark
    var promise = viewerControl.scrollToAsync(theFirstMark).then(
        function() {
            // after the mark has been scrolled to, select the mark
            viewerControl.selectMarks([theFirstMark]);
        },
        function(error) {
            alert('Scrolling failed: ' + (error.message ? error.message : error));
        }
    );
    
    

    Parameters:

    Name Type Description
    target PCCViewer.Mark | PCCViewer.Conversation | PCCViewer.SearchResult | PCCViewer.PiiEntity | Object

    The mark, conversation, search result, PII entity or an object (that contains pageNumber, x, and y values) to scroll to.

    Returns:

    A Promise object.

    Type
    PCCViewer.Promise

    Searches the text of the document for the given searchQuery.

    This query can be a single search term or a hash specifying one or more terms and options. If only a single search term (string) is supplied, then default options are used.

    Search completes asynchronously. The returned PCCViewer.SearchRequest object, provides events for search progress and members to access search results.

    Example

    // Search on a single term with default options
    var searchRequest = viewerControl.search("Hello");
    
    // Subscribe to the PartialSearchResultsAvailable event to get search results as they become available.
    searchRequest.on('PartialSearchResultsAvailable', function(_event) {
        // Get the newly available search results.
        var newResults = _event.partialSearchResults;
    });
    
    

    Example

    // Search on multiple terms and specify options
    var searchQuery = {
        searchTerms: [{
            searchTerm: "sub",
            contextPadding: 25,
            highlightColor: '#B22222',
            matchingOptions: {
                beginsWith: true,
            }
        },
        {
            searchTerm: "Accusoft"
        }]
    };
    
    var requestObject = viewerControl.search(searchQuery);
    
    //subscribe to the search request
    requestObject.on('PartialSearchResultsAvailable', function(_event) {
        var newResults = [];
        //Retrieve results
        newResults = _event.partialSearchResults;
    });
    
    

    Parameters:

    Name Type Description
    searchQuery string | PCCViewer.ViewerControl~SearchQuery

    A value specifying the search query. The value specifies a single search term (string) or an object specifying multiple search terms and options.

    See:

    Returns:

    An object that represents the search request. This object allows the calling code to subscribe to search progress events and access search results.

    Type
    PCCViewer.SearchRequest

    selectEditorText() → {PCCViewer.ViewerControl}

    Selects the editable text in a mark's text editor

    Example

    var viewerControl = viewerControl.enterTextMarkEditingMode(textAnnotation).selectEditorText();
    
    

    Throws:

    • If there is no active text mark editor.

      Type
      Error
    • If the active mark is not a TextInputSignature Mark.

      Type
      Error
    • If the PCCViewer.EventType.ViewerReady event has not fired prior to calling this method.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    selectMarks(marks) → {PCCViewer.ViewerControl}

    Selects the marks provided in the Array parameter.

    Note: This method ignores any Mark objects with the interaction mode set to PCCViewer.Mark.InteractionMode.SelectionDisabled.

    Example

    // get all of the marks
    var allMarks = viewerControl.getAllMarks();
    
    // select all of them
    viewerControl.selectMarks(allMarks);
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An array of PCCViewer.Mark objects that exist in the document and need to be selected.

    Throws:

    • If PCCViewer.EventType.ViewerReady event was not fired prior to calling this method.

      Type
      Error
    • If any of the mark objects are not valid objects, the id of the mark provided does not match the id of mark loaded in the viewer, or the mark provided was not previously added to the document pages.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    serializeMarks(marks) → {PCCViewer.Promise}

    Serializes any amount of Marks passed into the method.

    This serialization needs to happen asynchronously, so the method will return a Promise, which wil resolve once all marks have been serialized, or get rejected if any error occurs in the process.

    A successfully resolved Promise will receive an Array as its only argument, which will contain a plain Object representation of each mark that was passed into the method. These objects can be used with PCCViewer.ViewerControl#deserializeMarks in order to recreate the same marks at a later time.

    Example

    // get all selected marks, so we can serialize then
    var marksToUse = viewerControl.getSelectedMarks();
    
    viewerControl.serializeMarks(marksToUse).then(
        function success(markObjects) {
            // markObjects is an array of plain objects
            // they can be converted to a JSON string
            var markStr = JSON.stringify(markObjects);
        },
        function fail(reason) {
            alert('could not serialize marks: ' + reason);
        }
    );
    
    

    Parameters:

    Name Type Description
    marks PCCViewer.Mark | Array.<PCCViewer.Mark>

    A single mark or array of marks to be serialized.

    See:

    Returns:

    A promise object.

    Type
    PCCViewer.Promise

    serverSearch(searchQuery) → {PCCViewer.SearchRequest}

    Searches the text of the document for the given searchQuery. The search is performed server-side. This is efficient for larger documents, but for smaller documents it is more efficient to use the PCCViewer.ViewerControl#clientSearch method instead.

    This query can be a single search term or a hash specifying one or more terms and options. If only a single search term (string) is supplied, then default options are used.

    Search completes asynchronously. The returned PCCViewer.SearchRequest object, provides events for search progress and members to access search results.

    Example

    // Search on a single term with default options
    var searchRequest = viewerControl.serverSearch("Hello");
    
    // Subscribe to the PartialSearchResultsAvailable event to get search results as they become available.
    searchRequest.on('PartialSearchResultsAvailable', function(_event) {
        // Get the newly available search results.
        var newResults = _event.partialSearchResults;
    });
    
    

    Example

    // Search on multiple terms and specify options
    var searchQuery = {
        searchTerms: [{
            searchTerm: "sub",
            contextPadding: 25,
            highlightColor: '#B22222',
            matchingOptions: {
                beginsWith: true,
            }
        },
        {
            searchTerm: "Accusoft"
        }]
    };
    
    var requestObject = viewerControl.serverSearch(searchQuery);
    
    //subscribe to the search request
    requestObject.on('PartialSearchResultsAvailable', function(_event) {
        var newResults = [];
        //Retrieve results
        newResults = _event.partialSearchResults;
    });
    
    

    Parameters:

    Name Type Description
    searchQuery string | PCCViewer.ViewerControl~SearchQuery

    A value specifying the search query. The value specifies a single search term (string) or an object specifying multiple search terms and options.

    See:

    Returns:

    An object that represents the search request. This object allows the calling code to subscribe to search progress events and access search results.

    Type
    PCCViewer.SearchRequest

    setActiveMarkupLayer(markupLayer)

    Sets the viewer control's active markup layer.

    Example

    viewerControl.loadMarkupLayers('abc123').then(
        function onSuccess(layers){
            var activeMarkupLayer = viewerControl.setActiveMarkupLayer(layers[0]);
        },
        function onFailure(reason){
            console.log('layer failed to load:', reason.code, reason.message);
        }
    );
    
    

    Parameters:

    Name Type Description
    markupLayer PCCViewer.MarkupLayer

    A markup layer.

    Throws:

    setConversationDOMFactory(factoryFunction) → {PCCViewer.ViewerControl}

    Sets the conversation DOM factory function.

    Example

    var conversationFactoryFunction = function(conversation, state, existingDOM) {
        var conversationDiv = document.createElement('div'); // Create a conversation DOM element.
    
        // Set the style of the conversation DOM element.
        conversationDiv.style.position = 'absolute';
        if (state.isSelected) { // Set a different background if the conversation is selected.
            conversationDiv.style.backgroundColor = 'white';
        } else {
            conversationDiv.style.backgroundColor = 'lightgray';
        }
        conversationDiv.style.left = '10px';
        conversationDiv.style.right = '0';
        conversationDiv.style.textAlign = 'left';
    
        // For each comment in the conversation, create a comment DOM element.
        var comments = conversation.getComments();
        for (var i = 0; i < comments.length; i++) {
            var commentDiv = document.createElement('div');
    
            // Set the style of the comment DOM element.
            commentDiv.style.position = 'relative';
            commentDiv.style.padding = '5px';
            commentDiv.style.border = '1px solid gray';
            if (i > 0) {
                commentDiv.style.borderTop = 'none';
            }
    
            commentDiv.appendChild(document.createTextNode(comments[i].getText())); // Add the comment text to the comment DOM element.
            conversationDiv.appendChild(commentDiv); // Add the comment DOM element to the conversation DOM element.
        }
    
        return conversationDiv; // Return the conversation DOM element.
     };
    
    viewerControl.setConversationDOMFactory(conversationFactoryFunction);
    
    

    Parameters:

    Name Type Description
    factoryFunction function

    This function returns a DOM element that is injected in the viewer control UI, which should show information about the conversation. The viewer control will use this function to obtain a new conversation DOM element whenever:

    If this function returns a falsy value, then the conversation will not be shown in the viewer control UI. If this function returns a value that is not a DOM element and not falsy, then the viewer control will throw an exception when attempting to create a conversation DOM element.

    This function has three parameters, in this order:

    • conversation {PCCViewer.Conversation} - The Conversation in which to generate a DOM element.
    • state {Object} - An object that indicates the state of the conversation. This object has an isSelected boolean property.
    • existingDOM {HTMLElement | undefined} - The DOM Element returned from the last call to this factory for the given conversation. It is acceptable to return this same element from the factory function if the DOM does not need to be replaced (for example, if it only needs modification or does not require any modification). This parameter may have a value of undefined if the factory function has never been called for this conversation or the previous call did not return a DOM element.
    See:

    Throws:

    If the factoryFunction parameter is not a Function.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setCurrentMouseTool(name) → {PCCViewer.ViewerControl}

    Sets the current mouse tool of the viewer by name.

    See the help section titled "Custom Mouse Tools" for a list of the existing default mouse tools in the viewer.

    Parameters:

    Name Type Description
    name string

    The name used when creating the mouse tool. This value is case-insensitive.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setGamma(gammaFactor) → {PCCViewer.ViewerControl}

    Sets the gamma factor for the document. Values from 1 to 10 will darken the document. Values from 0 to 1 will effectively lighten it. Note: This setting only affects viewing and is not persisted when printing or burning.

    Example

    viewerControl.setGamma(5); // Darkens content by a factor of 5
    viewerControl.setGamma(0.5) // Lightens content by a factor of 0.5
    
    

    Parameters:

    Name Type Description
    gammaFactor number

    The gamma factor to set the Gamma for the document to.

    Throws:

    If the gamma factor is not a valid number between 0 and 10 inclusive.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setMarkHandleMode(markHandleMode) → {PCCViewer.ViewerControl}

    Sets the mark handle mode.

    Example

    viewerControl.setMarkHandleMode(PCCViewer.MarkHandleMode.HideCornerHandlesWhenClose);
    
    

    Parameters:

    Name Type Description
    markHandleMode PCCViewer.MarkHandleMode

    Display mark handles using this mode.

    See:

    Throws:

    If the value of markHandleMode is unknown.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setPageLayout(pageLayout) → {PCCViewer.ViewerControl}

    Sets the layout of the pages.

    This property defines the placement or arrangement of the pages in the viewer. The default page layout is "Vertical", in which the pages are displayed as a single vertical column and a vertical scroll bar is displayed to bring into view the pages that are not in view. The "Horizontal" option displays the pages as a single horizontal row and has a horizontal scroll bar to bring into view the pages that are not in the view.

    Comments are only supported when using vertical page layout. If the comments panel is open, setting the page layout to horizontal will close the comments panel.

    Example

    viewerControl.setPageLayout(PCCViewer.PageLayout.Horizontal);
    
    

    Parameters:

    Name Type Description
    pageLayout PCCViewer.PageLayout

    Display pages using this layout.

    See:

    Throws:

    If the pageLayout value is unknown.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setPageNumber(pageNumber) → {PCCViewer.ViewerControl}

    Sets the current page of the viewer to the specified page number.

    Example

    // first create the pccViewer : Note: if the viewer object has already been created, do not re-create it.
    var viewerControl = $("#viewer").pccViewer(viewerOptions).viewerControl;
    
    var pageNumberSet = 2;
    function pageChangedHandler(event) {
        var pageNumber = viewer.getPageNumber();
        if(pageNumber === pageNumberSet) {
            //now unsubscribe the event Note: do not unsubscribe if future notifications are required.
            viewerControl.off("PageChanged", pageChangedHandler);
            alert("Viewer was navigated to the desired page successfully");
        }
    }
    // Subscribe to PageChanged event exposed by the API
    viewerControl.on("PageChanged", pageChangedHandler);
    viewerControl.setPageNumber(pageNumberSet);
    
    

    Parameters:

    Name Type Description
    pageNumber number | string

    The 1-based page number of the page. A string representation of a valid number is also accepted as a parameter.

    Throws:

    • If the parameter pageNumber is less than 1 or greater than the value returned by PCCViewer.ViewerControl#getPageCount.

      Type
      Error
    • If the parameter pageNumber is not a number or a string representation of a number.

      Type
      Error
    • If the parameter pageNumber is not an integer page number.

      Type
      Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setRedactionViewMode(redactionViewMode) → {PCCViewer.ViewerControl}

    Sets the redaction view mode.

    When set to "Draft" mode, this property will make visible the document content text underneath for the rectangle redaction and the text selection marks. In this mode, the redaction reasons will not be visible.

    Setting the view mode to "Normal" will make the redaction rectangle marks and the text selection redactions opaque. In this mode, if the marks contain the redaction reasons then they will be visible.

    Example

    // show all the redaction rectangles and redaction text selection marks showing underlying document text content.
    viewerControl.setRedactionViewMode(PCCViewer.RedactionViewMode.Draft);
    
    

    Parameters:

    Name Type Description
    redactionViewMode PCCViewer.RedactionViewMode

    Displays redaction marks showing/hiding underneath document content text.

    See:

    Throws:

    If the redactionViewMode value is not one of the supported values. See PCCViewer.ViewerControl~ViewerControlOptions for mode details on the redactionViewMode initialization parameter.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setScaleFactor(scaleFactor) → {PCCViewer.ViewerControl}

    Sets the scale factor of the viewer.

    Note: The viewer has minimum and maximum scale limits. The limits depend on the size of the pages. check PCCViewer.ViewerControl#getMinScaleFactor and PCCViewer.ViewerControl#getMaxScaleFactor to determine the minimum and maximum scale.

    Example

    viewerControl.setScaleFactor(.5); // Zoom the document to 50% of its actual size.
    
    

    Parameters:

    Name Type Description
    scaleFactor number

    A value indicating the scale factor to use in the viewer, with 1 being 100% zoom.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setSelectedConversation(conversation) → {PCCViewer.ViewerControl}

    Sets the selected conversation.

    Example

    // get the first selected Mark object
    var theFirstMark = viewerControl.getSelectedMarks()[0];
    
    // select the conversation of the Mark
    viewerControl.setSelectedConversation(theFirstMark.getConversation());
    
    

    Parameters:

    Name Type Description
    conversation PCCViewer.Conversation

    The conversation to select.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setSelectedPiiEntity(piiEntity, scrollToopt) → {PCCViewer.ViewerControl}

    Selects the specified PII entity and optionally navigates to the page of the PII entity.

    If a value of null is passed in for the piiEntity parameter, then any currently selected result will be cleared/deselected.

    Example

    var piiDetectionRequest = viewerControl.detectPii();
    
    // add events to the PII detection request
    piiDetectionRequest.on("PiiDetectionCompleted", function(){
        // get the PII entities
        results = piiDetectionRequest.getPiiEntities();
    
        // set the result to the first
        viewerControl.setSelectedPiiEntity(results[0], true);
    });
    
    

    Parameters:

    Name Type Attributes Default Description
    piiEntity PCCViewer.PiiEntity | null

    The PII entity object from the entities object. If a value of null is passed, then no PII entities will be selected.

    scrollTo boolean <optional>
    false

    If true, the viewer will navigate to the page with the PII entity. If the value of piiEntity is null, then this argument is ignored.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setSelectedSearchResult(searchResult, scrollToopt) → {PCCViewer.ViewerControl}

    Selects the specified search result and optionally navigates to the page of the search result.

    If a value of null is passed in for the searchResult parameter, then any currently selected result will be cleared/deselected.

    Example

    var searchRequest = viewerControl.search('Accusoft');
    
    // add events to the search request
    searchRequest.on("SearchCompleted", function(){
        // get the search results
        results = searchRequest.getResults();
    
        // set the result to the first
        viewerControl.setSelectedSearchResult(results[0], true);
    });
    
    

    Parameters:

    Name Type Attributes Default Description
    searchResult PCCViewer.SearchResult | null

    The search result object from the results object. If a value of null is passed, then no search results will be selected.

    scrollTo boolean <optional>
    false

    If true, the viewer will navigate to the page with the search result. If the value of searchResult is null, then this argument is ignored.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setSharpening(sharpeningFactor) → {PCCViewer.ViewerControl}

    Sets the sharpening factor for the document. Note: This setting only affects viewing and is not persisted when printing or burning.

    Example

    viewerControl.setSharpening(60);
    
    

    Parameters:

    Name Type Description
    sharpeningFactor number

    The sharpening factor to set the Sharpening for the document to.

    Throws:

    If the sharpening factor is not a valid integer between 0 and 100 inclusive.

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setSvgLineWidthMultiplier(lineWidthMultiplier) → {PCCViewer.ViewerControl}

    Numeric value which all SVG line width values should be multipled by. Must be greater than 0 and must not be greater than 100. To make lines twice as thick as they originally were, use a value of 2. To make lines half as thick as they originally were, use a value of 0.5, etc. To reset lines to their original thickness, use a value of 1. Note: This setting only affects viewing and is not persisted when printing or burning.

    Example

    viewerControl.setSvgLineWidthMultiplier(50);
    
    

    Parameters:

    Name Type Description
    lineWidthMultiplier number

    The line width multiplier for svg lines to set for the document.

    Throws:

    If amount is not greater than zero or is greater than 100

    Type
    Error

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    setViewMode(viewMode) → {PCCViewer.ViewerControl}

    Sets the view mode.

    When set to "Document" or "EqualFitPages", this property only has an effect on documents with different sized pages. Setting the view mode to "Document" maintains the relative size of each page when displaying a document. For example, if page 2 is smaller than page 1, it will appear smaller. Setting the view mode to "EqualFitPages" scales each page so that their width is the same. For example, if page 2 is smaller than page 1, it will be scaled larger so that its width is equal to the width of page 1.

    Setting the view mode to "SinglePage" structures the viewer so that only a single page is shown at a time. Each page is scaled to fit within a view box, which is the initial size of the viewer and increases in size when zooming in (and decreases in size when zooming out). After the viewer initializes, the view mode may not be changed to or from SinglePage view mode (or an exception will occur).

    Example

    viewerControl.setViewMode(PCCViewer.ViewMode.EqualFitPages);   // Scale each page so that their width is the same.
    
    

    Parameters:

    Name Type Description
    viewMode PCCViewer.ViewMode

    Display pages using this mode.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    showMarks(marks) → {PCCViewer.ViewerControl}

    Shows the specified marks.

    Example

    // shows all selected marks
    viewerControl.showMarks(viewer.getSelectedMarks());
    
    

    Parameters:

    Name Type Description
    marks Array.<PCCViewer.Mark>

    An Array of objects of type PCCViewer.Mark.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    validatePrintRange(range) → {boolean}

    Determines whether the range string is a valid page range to be used in PCCViewer.ViewerControl#print.

    Example

    viewerControl.validatePrintRange("1, 3-5"); // Returns true if there are at least 5 pages in the document.
    
    

    Parameters:

    Name Type Description
    range string

    A string containing page numbers or ranges. See PCCViewer.ViewerControl#print.

    Returns:

    A value indicating whether the specified print range is valid.

    Type
    boolean

    validateSearch(searchQuery) → {Object}

    Validates each of the search terms in the searchQuery object. The validation process checks for valid custom regular expressions. This method is used by the default UI to filter out 'bad' pre-defined search terms.

    Example

    var searchQuery = {
        searchTerms: [
            {
                searchTerm: '(?<=(category=))[a-z-]+', // invalid regex
                contextPadding: 25,
                highlightColor: '#B22222',
                matchingOptions: {
                    beginsWith: false,
                    endsWith: false,
                    exactPhrase: false,
                    matchCase: true,
                    matchWholeWord: false,
                    wildcard: false
                }
            }
        ]
    }
    
    viewerControl.validateSearch(searchQuery)
    
    // returns
    {
        errorsExist: true,
        searchTerms: [
            {
                isValid: false,
                message: "Search term must be a string containing either plain text or a valid regular expression."
            }
        ]
    }
    
    

    Parameters:

    Name Type Description
    searchQuery string | PCCViewer.ViewerControl~SearchQuery

    A string or a SearchQuery object that requires validation. See PCCViewer.ViewerControl#search.

    Returns:

    Returns an object with two summary properties and an array of objects that indicate whether each search term is valid. The array will be the same length as the array searchQuery.searchTerms. Objects contain the following properties:

    • errorsExist {boolean} True if any validation errors exist. False if not.
    • summaryMsg {string} (optional) A catch all message for cases where the search terms could not be reached for validation. This might occur if the searchQuery object is badly formed with improper key names or the viewer sends in an invalid object type (say boolean)
    • array of objects:
      • isValid {boolean} Indicates if the search term of the matching index was valid.
      • message {string} Provides a human readable message indicating the reason the search term was invalid.
    Type
    Object

    zoomIn(zoomFactor) → {PCCViewer.ViewerControl}

    Zoom in on the document by the specified zoomFactor.

    Note: The viewer has minimum and maximum scale limits. zoomIn will only change the viewer's scale up to, but not past, the maximum scale limit. zoomIn does not give an indication if the actual scale change was less than the requested zoom factor because the limit was reached. Instead, check PCCViewer.ViewerControl#atMaxScale to determine if the viewer is at max scale.

    Example

    viewerControl.zoomIn(1.5);   // Zoom in by 1.5x, or to the maximum scale.
    viewerControl.zoomIn(5);     // Zoom in by 5x, or to the maximum scale.
    
    viewerControl.zoomIn(100);   // Throws!
    viewerControl.zoomIn(1);     // Throws!
    
    

    Parameters:

    Name Type Description
    zoomFactor number

    Zoom in by this factor. Valid values are between 1.01 and 20

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    zoomOut(zoomFactor) → {PCCViewer.ViewerControl}

    Zoom out on the document by the specified zoomFactor.

    Note: The viewer has minimum and maximum scale limits. zoomOut will only change the viewer's scale down to, but not past, the minimum scale limit. zoomOut does not give an indication if the actual scale change was less than the requested zoom factor because the limit was reached. Instead, check PCCViewer.ViewerControl#atMinScale to determine if the viewer is at minimum scale.

    Example

    viewerControl.zoomOut(1.5);   // Zoom out by 1.5x, or to the minimum scale.
    viewerControl.zoomOut(5);     // Zoom out by 5x, or to the minimum scale.
    
    viewerControl.zoomOut(100);   // Throws!
    viewerControl.zoomOut(1);     // Throws!
    
    

    Parameters:

    Name Type Description
    zoomFactor number

    Zoom out by this factor. Valid values are between 1.01 and 20.

    See:

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    zoomToPoint(scaleFactor, point) → {PCCViewer.ViewerControl}

    Sets the scale factor of the viewer around a specific point, of which will become the new center.

    Note: The viewer has minimum and maximum scale limits. The limits depend on the size of the pages. Check PCCViewer.ViewerControl#getMinScaleFactor and PCCViewer.ViewerControl#getMaxScaleFactor to determine the minimum and maximum scale.

    Example

    // If you know exactly where you would like the scale to be set around
    ViewerControl.zoomToPoint(5, {x: 600, y: 900})
    
    // Otherwise you can use it more dynamically like so
    ViewerControl.zoomToPoint(5, {x: e.x, y: e.y})
    
    

    Parameters:

    Name Type Description
    scaleFactor number

    A value indicating the scale factor to use in the viewer, with 1 being 100% zoom.

    point object

    An object indicating the coordinates of which the new scale should be centered around.

    Throws:

    Returns:

    The ViewerControl object on which this method was called.

    Type
    PCCViewer.ViewerControl

    Type Definitions

    ProximitySearchTerm

    Proximity search finds all occurrences of multiple search terms which are near each other (within the specified distance, which must be an integer) and on the same page. This class will hold all the necessary details to perform a proximity search. It will be used in the PCCViewer.ViewerControl~SearchQuery object that is passed to the PCCViewer.ViewerControl#search method.

    Example

     // An example proximity search term object. Notice how you can specify any number of search terms with their own individual options.
     var proximitySearchTerm = {
         type: "proximity",
         distance: 3,
         highlightColor: "#f73131",
         contextPadding: 30,
         terms: [{
             searchTerm: "influenza"
         },{
             searchTerm: "infection",
             matchingOptions: {
                 matchWholeWord: true
             }
         },{
             searchTerm: "group",
             matchingOptions: {
                 matchCase: false
             }
         }]
    };
    // The proximity search term is used in a search query object.
    searchRequest.on('SearchCompleted', function(){
         console.log();
    });
    // The proximity search term is used in a search query object.
    // There can be many search term objects and proximity search term objects in a search query object.
    var searchQuery = {
         searchTerms: [proximitySearchTerm]
    };
    // Execute the search
    var searchRequest = viewerControl.search(searchQuery);
    
    

    Type:

    • Object

    Properties:

    Name Attributes Description
    type : string

    This property is used by the API in order to determine that this search term is a proximity search term. The user will have to set the value to proximity in order for the term to be used by the proximity search algorithm.

    distance : number

    Number of intermediate words between the search terms.

    terms : Array.<PCCViewer.ViewerControl~SearchTerm>

    An array of search terms.

    contextPadding : number <optional>
    Default: 25

    The maximum number of leading and trailing character in the context string (PCCViewer.SearchResult#getContext) that is given for a search result.

    highlightColor : string <optional>

    The highlight color of the search results matching this search term (PCCViewer.SearchResult#getHighlightColor).

    If not defined, then a random color will be chosen.

    SaveMarkupOptions

    The PCCViewer.saveMarkup API method takes a second optional parameter. This parameter is in the form of an object and provides options for saving marks to the server.

    Type:

    • Object

    Properties:

    Name Attributes Description
    includeAnnotations : boolean <optional>
    Default: true

    Indicates whether annotation mark types should be saved.

    includeSignatures : boolean <optional>
    Default: false

    Indicates whether signature mark types should be saved.

    includeRedactions : boolean <optional>
    Default: true

    Indicates whether redaction mark types should be saved.

    SearchMatchingOptions

    This object is used to specify search options. It will be used in a PCCViewer.ViewerControl~SearchTerm object.

    Example

    // A simple matching options object
    var myMatchingOptions = {
        beginsWith: true,
    };
    
    // The matching options object is used in a search term object
    var searchTerm = {
        searchTerm: "sub",
        contextPadding: 25,
        highlightColor: '#B22222',
        matchingOptions: myMatchingOptions
    };
    
    // The search term object is used in the search query object
    var searchQuery = {
        searchTerms: [searchTerm]
    };
    
    

    Type:

    • Object

    Properties:

    Name Attributes Description
    endsWith : boolean <optional>
    Default: false

    Match a phrase that ends with the search term. The matched phrase will be the shortest phrase that starts on a word boundary and ends with the matched phrase.

    When looking for word boundaries, PrizmDoc treats underscore, decimals and letters as word characters and everything else as non word characters. Note: When searching, PrizmDoc treats any contiguous group of Asian characters as a word, even though the group may actually comprise multiple words.

    beginsWith : boolean <optional>
    Default: false

    Match a phrase that starts with the search term. The matched phrase will be the shortest phrase that starts with the matched phrase and ends on a word boundary.

    When looking for word boundaries, PrizmDoc treats underscore, decimals and letters as word characters and everything else as non word characters. Note: When searching, PrizmDoc treats any contiguous group of Asian characters as a word, even though the group may actually comprise multiple words.

    If this value is true, then the following options are ignored:

    • endsWith
    exactPhrase : boolean <optional>
    Default: true

    Indicates whether the entire searchTerm is treated as a single phrase or if it is split on white space and individual words are matched based on the search options.

    If this value is true, then the following option is not supported:

    • wildcard
    matchCase : boolean <optional>
    Default: false

    Indicates whether matching is case sensitive.

    matchWholeWord : boolean <optional>
    Default: false

    Match a phrase that starts and ends on word boundaries.

    When looking for word boundaries, PrizmDoc treats underscore, decimals and letters as word characters and everything else as non word characters. Note: When searching, PrizmDoc treats any contiguous group of Asian characters as a word, even though the group may actually comprise multiple words.

    If this value is true, then the following options are ignored:

    • wildcard
    • endsWith
    • beginsWith
    wildcard : boolean <optional>
    Default: false

    A value that indicates whether the search term includes wild cards.

    Supported wildcard characters, which may not be escaped, are:

    • '*' - match zero or more non-whitespace characters
    • '?' - match one character

    If this value is true, then the following options are ignored:

    • endsWith
    • beginsWith

    SearchQuery

    This object is used to specify one or more search terms and options for the PCCViewer.ViewerControl#search method.

    Example

    // An example search query object with one search term
    var searchQuery = {
        searchTerms: [{
            searchTerm: "sub",
            contextPadding: 25,
            highlightColor: '#B22222',
            matchingOptions: {
                beginsWith: true,
            }
        }]
    };
    
    

    Type:

    • Object

    Properties:

    Name Description
    searchTerms : Array.<(PCCViewer.ViewerControl~SearchTerm|PCCViewer.ViewerControl~ProximitySearchTerm)>

    An array of search terms.

    SearchTerm

    This object is used to specify one search term and its options. It will be used in the PCCViewer.ViewerControl~SearchQuery object that is passed to the PCCViewer.ViewerControl#search method.

    Example

    // An example search term object
    var searchTerm = {
        searchTerm: "sub",
        contextPadding: 25,
        highlightColor: '#B22222',
        matchingOptions: {
            beginsWith: true,
        }
    };
    
    // The search term is used in a search query object.
    // There can be many search term objects in a search query object.
    var searchQuery = {
        searchTerms: [searchTerm]
    };
    
    

    Type:

    • Object

    Properties:

    Name Attributes Description
    searchTerm : string

    A string value to match against. This may be treated as a string literal, a string with wild cards, or a regular expression. See searchTermIsRegex and PCCViewer.ViewerControl~SearchMatchingOptions.

    contextPadding : number <optional>
    Default: 25

    The maximum number of leading and trailing character in the context string (PCCViewer.SearchResult#getContext) that is given for a search result.

    highlightColor : string <optional>

    The highlight color of the search results matching this search term (PCCViewer.SearchResult#getHighlightColor).

    If not defined, then a color will be chosen. A different color will be chosen for each search term, and if matchingOptions.exactPhrase === false, then a different color will be chosen for each word in the search term.

    matchingOptions : PCCViewer.ViewerControl~SearchMatchingOptions <optional>

    Options that specify how the search term will be matched.

    searchTermIsRegex : boolean <optional>
    Default: false

    Indicates if the search term is treated as a regular expression.

    If this value is true, then the following matching options can be used:

    • matchingOptions.matchCase

    Note that it is invalid to set the other matching options for a regular expression search. Doing so may make search behave in unexpected ways.

    ViewerControlOptions

    These options are available and processed directly by the ViewerControl. When using the jQuery Plugin, external:jQuery.fn#pccViewer, these options can be passed in along with external:jQuery.fn~Options, and they will be passed into ViewerControl.

    Type:

    • Object

    Properties:

    Name Attributes Description
    documentID : string

    REQUIRED The ID of the document to load.

    imageHandlerUrl : string

    REQUIRED The end point of the web tier services that support the viewer.

    language : Object <optional>

    Specifies the language to use for the text in the ViewerControl.

    The options here are a subset of the external:jQuery.fn~LanguageOptions object. These values are used directly by the ViewerControl, and are passed in by the jQuery Plugin, external:jQuery.fn#pccViewer. When creating a custom UI using ViewerControl directly, these options will need to be passed in during initialization. If they language element is not present with the following properties, ViewerControl will use the English language defaults.

    Properties
    • pageLoadFailed : string <optional>
      Default: "Page Load Failed"

      Text to use for "Page Load Failed"

    • pageLoadFailedRetry : string <optional>
      Default: "Retry"

      Text to use for "Retry"

    viewMode : string <optional>
    Default: "Document"

    The mode used to view documents containing different sized pages. See the PCCViewer.ViewMode enumeration for details on each view mode.

    pageLayout : string <optional>
    Default: "Vertical"

    The layout used to arrange pages in the viewer. See the PCCViewer.PageLayout enumeration for details on each page layout.

    pageRotation : number <optional>
    Default: 0

    The amount in degrees clockwise to rotate each page. Valid values are multiples of 90: ..., -270, -180, -90, 0, 90, 180, 270, ...

    resourcePath : string <optional>
    Default: "img"

    The location of the images within the viewer. This is the folder that holds the ArtMarkHandles.png and EditTextMark.png files. This path should be relative to the page that the viewer is embedded on.

    printTemplate : string <optional>
    Default: ""

    A text representation of a full web page used for printing purposes. It is recommended that this value be set to the content of the file "printTemplate.html". If this value is set to an empty string (default), then printing will be unavailable.

    template.print : string <optional>
    Default: ""

    This is an alias for printTemplate. If printTemplate is not available in the options object, the control will look for this property instead. This property matches the value as it is used in the jQuery plugin options (external:jQuery.fn~Options).

    encryption : boolean <optional>
    Default: false

    Specifies whether the viewer should use encryption. See the help topic "Enabling Content Encryption" for more details.

    serviceResponseTimeout : number <optional>
    Default: 60000

    Indicates the response timeout interval for all services to the server. A value of zero indicates the default browser value will be used.

    debug : boolean <optional>
    Default: false

    Indicates whether the viewer should log its actions.

    RedactionViewMode : string <optional>
    Default: "Normal"

    The redaction view mode can be used to view document content text underneath the opaque rectangle redaction marks and the text selection redaction marks. See the PCCViewer.RedactionViewMode enumeration for details on redaction view modes.

    markHandleMode : string <optional>
    Default: "HideSideHandlesWhenClose"

    The mark handle mode. See the PCCViewer.MarkHandleMode enumeration for details on each mark handle mode.

    enableMultipleRedactionReasons : boolean <optional>
    Default: false

    Specifies whether multiple redaction reasons are enabled. Set this property value to true in order to use PCCViewer.Mark#reasons API.

    discardOutOfViewText : boolean <optional>
    Default: false

    Specifies whether text on pages that are not displayed is discarded from memory. Note that it is necessary to use the PCCViewer.ViewerControl#requestPageText method to request a text page before using any API that requires the text of a page that is not currently displayed.

    searchMethodType : string <optional>
    Default: "auto"

    The type of search that will be used by the PCCViewer.ViewerControl#search method. Note that client search will be used if server search is unavailable (this is the case when using viewing packages). Possible values are:

    searchMethodPageCountThreshold : number <optional>
    Default: 80

    The maximum number of pages a document can have for client-side search. This value is used when searchMethodType is set to "auto". Must be greater than 1.

    viewerAssetsPath : number <optional>
    Default: "viewer-assets"

    The path to the viewer-assets folder, which is used in the print template. The text {{viewerAssetsPath}} in your print template will be replaced by the value specified for this option.


    Documentation generated by JSDoc 3.6.10 on Thu Oct 31 2024 15:05:55 GMT+0000 (Coordinated Universal Time)