Class: VirtualViewer

VirtualViewer

The VirtualViewer class is the home of all VirtualViewer API. It is a singleton class, so should never be manually created. All API documented below can be called on the global instance virtualViewer.
Version:
  • 5.0

Methods

addBookmark(content, page) → {boolean}

Add a bookmark to the document.
Parameters:
Name Type Description
content string The message that displays in the bookmark.
page number A 0-indexed page number. This is the page that the viewer will jump to when the bookmark is clicked. It will be updated when page manipulations occur.
Returns:
False if there was an error or adding the bookmark was otherwise unsuccessful.
Type
boolean

addDocumentViewedIndicator(documentId)

This method will add a blue checkmark to the specified document thumbnail.
Parameters:
Name Type Description
documentId String The document ID of the thumbnail you want marked.

addDocumentViewedIndicatorBatch(documentIdArray)

This method takes in an array of document IDs and add blue checkmarks to their thumbnails.
Parameters:
Name Type Description
documentIdArray Array.<String> An array of strings of all the DocumentIds

addOverlayToPage(page, overlayDocumentIdopt)

Add an overlay image to the given page. If there's an overlay image already loaded, this will simply make sure that image is displayed on the given page. If there's no overlay image already loaded and overlayDocumentId is specified, this will call virtualViewer.getOverlayImage for just the given page.
Parameters:
Name Type Attributes Default Description
page number The page that should have the overlay image applied to it.
overlayDocumentId string <optional>
 The current overlay image, if one exists This is an optional parameter; if you are using this API to load the overlay image as well as display it, provide the overlay ID.
See:

addPageToSelection(pageNumber)

Add the specified page to the current selection. This will highlight the page thumbnail, and allow certain API like copySelection to act on the page.
Parameters:
Name Type Description
pageNumber number The page number (0-indexed) to select.

adjustBrightnessForSelectedPages(pageNumberArray, adjustValue)

Increase or decrease the brightness of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
adjustValue number positive or negative whole numbers, positive to increase the brightness, negative to decrease the brightness

adjustContrastForSelectedPages(pageNumberArray, adjustValue)

Increase or decrease the contrast of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
adjustValue number positive or negative whole numbers, positive to increase the contrast, negative to decrease the contrast

adjustGammaForSelectedPages(pageNumberArray, adjustValue)

Increase of decrease the gamma of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
adjustValue number positive or negative whole numbers, positive to increase the gamma, negative to decrease the gamma

cancelCurrentSearch()

Stops the current search, leaving whatever results have been returned in place. Use virtualViewer.clearSearchResults() to remove these.
See:

clearImageStamps()

Remove all the stamp options from the Image Rubber Stamp dropdown list in the toolbar.

clearSearchResults()

Clear all traces of the current search (highlights, thumbnails, etc). This may act oddly if there is a search in progress, so make sure to cancel the current search before calling this.
See:

closeTab(tabId)

Closes tab corresponding to tabNumber. Removes tab from the UI. Switches view to a different tab in its place.
Parameters:
Name Type Description
tabId number | string This parameter can take either the 0-indexed index of the tab, or the document ID that the tab refers to.

collapseAllStickyNotes(collapsed, repaintopt)

Expand or collapses all sticky notes on the current page.
Parameters:
Name Type Attributes Description
collapsed boolean If true, force all sticky notes to collapse
repaint boolean <optional>
 If true, annotations will be repainted before exit. Otherwise, the user will see the results on the next action that requires a repaint, like scrolling or clicking on an annotation.

compareDocuments(firstDocumentID, secondDocumentID, optionsopt)

Public API to compare two documents. Provided two document IDs, this function will launch the viewer into a split screen mode and compare the text of the two documents. The "first" document will display on the left and be considered the "original" document--in the diff, modifications to this document will appear as deletions. The "second" document is the "modified" document, and modifications in the diff will appear as additions. This function call will also launch the document compare thumbnail pane. The diff acts on the entire text of a page at a time. This may cause changes that flow between pages to be split up into different items.
Parameters:
Name Type Attributes Description
firstDocumentID string The ID of the "original" document. This document will display on the left.
secondDocumentID string The ID of the "modified" document. This document will display on the right.
options object <optional>
 Additional settings for document compare.
Properties
Name Type Attributes Default Description
splitScreenDirection string <optional>
 "horizontal" The split panes of the viewer can either display one on top of each other ("vertical") or side-by-side ("horizontal"). Pass in "vertical" for the former and "horizontal" for the latter. The default is "horizontal".
skipOcrPrompt boolean <optional>
 If OCR is set up, and one of the documents being compared is a format without readable text (an image rather than a pdf, for instance), the viewer will display a dialog to ensure the user wants to run OCR. Setting this option to true will skip that prompt and always run OCR if one of the documents does not have readable text. It is not necessary to set this parameter if OCR is not set up.

consolidateAnnotationLayers()

Create a new layer, and copy all annotations from other layers to that new layer. Only one consolidated master layer can exist at a time.

copyAllText()

This function selects all the text on the current page and copies it to the clipboard preview panel. The user can then copy with ctrl+C.

copySelection(showAlertopt, callbackopt) → {boolean}

Copies the currently selected pages to the VV "clipboard". Selected pages will appear with a gray or blue border in the page thumbnail panel. Users can select pages by clicking, shift + clicking, or ctrl + clicking. The VV clipboard is not the system clipboard, but a cache of document data that can transfer between tabs or windows of the viewer.
Parameters:
Name Type Attributes Default Description
showAlert boolean <optional>
 false Show an alert dialog if page manipulations are disabled. If page manipulations are disabled this action will not be performed; this parameter controls whether the user is notified.
callback function <optional>
 A function that will be called once the clipboard object is actually stored by localforage.
Returns:
True if there were pages selected, false otherwise
Type
boolean

copyToNewDocument(deleteCopiedPagesopt)

If there are currently selected pages, create a new document from those pages. The selected pages will be left in place or not depending on the parameter deleteCopiedPages. Selected pages will have their thumbnails highlighted by a gray or blue border in the page thumbnail pane. Users can add pages to their selection by clicking, shift + clicking, or ctrl + clicking.
Parameters:
Name Type Attributes Default Description
deleteCopiedPages boolean <optional>
 false If true, delete the pages used to form the new document from the original document. If false, leave them in place. This parameter's value is truthy, so if not provided, it will be read as false.

countPagesForDocument(documentId, clientInstanceId) → {number}

Count the number of pages in the specified document. This function is not performant for a document that's already open, since the viewer has already loaded document data in that case. This API should only be used when querying the page count of an unopened document.
Parameters:
Name Type Description
documentId string The ID of the document for the request.
clientInstanceId string The clientInstanceId for the request. This function will not use any clientInstanceId already set in the viewer.
Returns:
The number of pages in the document.
Type
number

createImageStamp(url, title, optionsopt)

Add a single image stamp to the Image Rubber Stamp dropdown on the toolbar.
Parameters:
Name Type Attributes Description
url string The URI of the stamp's image.
title string The displayed title of the stamp. This will appear in the list in the toolbar.
options object <optional>
 Optional settings for the stamp.
Properties
Name Type Description
width number The width of the stamp image.
height number The height of the stamp image.
annotationId String An optional string that will be preserved in the annotation's annId property.

createImageStampArray(stampList)

Add a whole array of Image Rubber Stamps to the viewer. The provided stamps will append to the existing list of stamps. A stamp object has mandatory URL and title properties, and optional width and height properties.
Parameters:
Name Type Description
stampList Array.<ImageStamp> An array of stamp objects, that require "url" and "title" properties to be valid.

createImageStampArrayFromFunction(fn)

Initialize the viewer's list of Image Rubber Stamps. This takes a callback function as a parameter, and calls that function to get the actual list of Image Rubber Stamps that will be used in the viewer. The parameter function is called with no parameters, and should return an array containing stamp objects. A stamp object has mandatory URL and title properties, and optional width and height properties. See createImageStampArray for a full description of a stamp array.
Parameters:
Name Type Description
fn function A function that returns an array of objects with the properties defined in ImageStamp.
See:

cropPageButton()

If crop is enabled, the user may drag a rectangle across the image to crop it. This function puts the viewer in crop mode, so that the user can start dragging a rectangle. An error will pop up if crop is not enabled in config.js.

cropPageClient(top, left, bottom, right, page) → {boolean}

Performs the crop action on the current document. If all dimension parameters and a page number are provided, the given page will crop to those dimensions. If the "top" parameter is not given, this function will perform the crop action for an existing rectangle that the user has drawn.
Parameters:
Name Type Description
top number The top position of the crop rectangle. Dimensions are unscaled and in pixels. The top left corner of the page is the origin point for these coordinates.
left number The left position of the crop rectangle. Dimensions are unscaled and in pixels. The top left corner of the page is the origin point for these coordinates.
bottom number The bottom position of the crop rectangle. Dimensions are unscaled and in pixels. The top left corner of the page is the origin point for these coordinates.
right number The right position of the crop rectangle. Dimensions are unscaled and in pixels. The top left corner of the page is the origin point for these coordinates.
page number The 0-indexed page number of the page that should be cropped. This is mandatory if dimensions are provided as arguments, but is optional if the user-entered rectangle will be used.
Returns:
True on success and false on failure or error.
Type
boolean

cutSelection(delPages, showAlertopt, callbackopt) → {boolean}

Cuts the currently selected pages to the VV "clipboard". Selected pages appear with a blue or gray border around their thumbnails in the page thumbnail panel. The VV clipboard is a cache of page data that can be pasted into other viewer tabs or windows, and does not affect the system clipboard. If delPages is true the pages are simply deleted and not placed on the clipboard.
Parameters:
Name Type Attributes Default Description
delPages boolean If true, the pages will be deleted and the clipboard will remain unmodified. In this case, the function operates as a page deletor and no pages will be available to paste.
showAlert boolean <optional>
 false Show an alert dialog if page manipulations are disabled. If page manipulations are disabled, the function will not execute and users will not be able to move pages around, whether this parameter is true or not. This parameter controls whether the user sees an error message.
callback function <optional>
 A function that will be called once the clipboard object is stored by localforage.
Returns:
True if there were pages selected, false if there were no pages selected or the function did not execute.
Type
boolean

decreaseBrightnessForSelectedPages(pageNumberArray, value)

Decrease the brightness of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

decreaseContrastForSelectedPages(pageNumberArray, value)

Decrease the contrast of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

decreaseGammaForSelectedPages(pageNumberArray, value)

Decrease the gamma of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

deleteBookmark(page) → {boolean}

Delete the bookmark pointing to the given page of the currently open document.
Parameters:
Name Type Description
page number The 0-indexed number of the page that should no longer be bookmarked.
Returns:
True on success and false on failure.
Type
boolean

deselectAllText()

Deselects all the text on the current page and removes any text highlight.

despeckleImage()

Despeckles the current page of the current document. Cannot be applied repeatedly without saving in between. If this operation is performed, the image will be converted to a bitmap.

editBookmark(page) → {boolean}

Launch a dialog so the user may edit the bookmark pointing to the given page.
Parameters:
Name Type Description
page number The 0-indexed page number that the bookmark points to.
Returns:
True on success, false otherwise.
Type
boolean

emailDocument(options) → {boolean}

Email the current document as a PDF, a TIFF, or as the original format.
Parameters:
Name Type Description
options object An options object to hold arguments.
Properties
Name Type Attributes Default Description
format string Either "Original", "PDF" or "TIFF". The document must be emailed as a .pdf or .tif file if annotations, redactions, watermarks, or document notes are included, and if pageRangeType is any value other than "all".
includeTextAnnotations boolean <optional>
 false Whether or not to include text annotations.
includeNonTextAnnotations boolean <optional>
 false Whether or not to include non-text annotations.
burnRedactions boolean <optional>
 false Whether or not to burn in redactions. If redactions are burned, the redaction becomes part of the image and any underlying text is removed. It is not reversible.
includeRedactionTags boolean <optional>
 false Whether or not to include redaction tags.
includeDocumentNotes boolean <optional>
 false Set this to true to append document notes as text pages at the end of the document.
includeWatermarks boolean <optional>
 Set this to true if watermarks should appear on the emailed document.
pageRangeType string <optional>
 "all" Either "all", "complex" or "current". "all" will email all pages; "current" will email just the current page; but "complex" requires the parameter pageRangeValue to be set as well.
pageRangeValue string <optional>
 A range of pages numbers to export. This may look like: "1-2,3,6,7-10". VirtualViewer allows commas and dash-separated ranges.
fromAddress string <optional>
 vvConfig.emailDefaults The sender's email address. The default can be changed in config.js.
toAddresses string <optional>
 vvConfig.emailDefaults A comma-separated list of recipient email addresses. For instance, "myemail@email.com,youremail@email.com". The default can be changed in config.js.
ccAddresses string <optional>
 vvConfig.emailDefaults A comma-separated list of email addresses to CC. For instance, "myemail@email.com,youremail@email.com". The default can be changed in config.js.
bccAddresses string <optional>
 vvConfig.emailDefaults A comma-separated list of email addresses to BCC. For instance, "myemail@email.com,youremail@email.com". The default can be changed in config.js.
subject string <optional>
 The subject line (title) of the email.
emailBody string <optional>
 The message (body) of the email.
Returns:
True if the email request is sent off successfully, and a falsey value if not.
Type
boolean

emailDocumentDialog()

Launches the Email Document dialog.

enableCaptions(captionIdopt)

Turn on captions for the currently-open video or audio player, if available. Can be called without arguments
Parameters:
Name Type Attributes Description
captionId number | string <optional>
 Specify which captions to play, either by its index (i.e. order in the list of captions, starting with 0), or by its label. If left blank, this will default to the first set of captions in the list).

enterGuideMode()

Puts the viewer in "Guide" mode. In guide mode, the viewer displays a horizontal line and a vertical line that can be moved around with the mouse over the document. These guides can be locked into position or moved. While guide mode is active, mouse actions on the document will be interpreted as guide actions.

enterOverlayDragMode()

Turn on Overlay Mode. This viewer mode allows the overlay image to be dragged around. When this is on, the user may use the mouse to drag the overlay image around the document. The mode may be exited by the user right-clicking, or by the user taking some other action on the viewer like activating the magnifier or drawing an annotation.
See:

enterPanMode()

Enter "Pan" mode. Mouse movements will be interpreted as panning or annotation selection actions. This is the standard viewer mode when a document without text is opened.

enterSelectTextMode()

Enter "Select Text" mode, allowing the user to highlight text on the page. Mouse movements will be interpreted as text selection actions. This is the standard viewer mode when a document with text is opened, but cannot be used if the open document has no text.

exitOverlayDragMode()

Turn off the viewer mode that allows the template overlay image to be dragged around. Once this is off, the viewer will act normally, and the user may interact with annotations, select text, as normal. The API function enterOverlayDragMode must be called to allow overlay dragging again; there is no automatic UI to re-enter the overlay drag mode.
See:

exportDocument(options) → {boolean}

Export the current document as a PDF, a TIFF, or the original format, and locally download the resulting file.
Parameters:
Name Type Description
options object An argument object.
Properties
Name Type Description
exportFormat string Either "Original", "PDF" or "TIFF". Note that "Original" may only be used when exporting a document without including annotations, redactions, watermarks, or document notes. Additionally, to export as the original format, pageRangeType must be "all".
fileExtension string This is based on the exportFormat parameter. If exportFormat is "Original", then the extension must be the current file extension of the document. If "PDF", the extension should be "pdf". If "TIFF", then "tif". Importantly, the extension can only be tif, pdf, or the original extension. VV will not convert a document to any format other than PDF, TIFF, or the document's original format.
includeTextAnnotations boolean Whether or not to include text annotations.
includeNonTextAnnotations boolean Whether or not to include non-text annotations.
burnRedactions boolean Whether or not to burn in redactions. If redactions are burned, the redaction becomes part of the image and any underlying text is removed. It is not reversible.
includeRedactionTags boolean Whether or not to include redaction tags.
includeDocumentNotes boolean Set this to true to append document notes as text pages at the end of the document.
includeWatermarks boolean Set this to include watermarks in the exported document.
pageRangeType string Either "all", "complex" or "current". "all" will export all pages; "current" will export just the current page; but "complex" requires the parameter pageRangeValue to be set as well.
pageRangeValue string A range of pages numbers to export. This may look like: "1-2,3,6,7-10". VV allows commas and dash-separated ranges.
Returns:
Returns true if the export request has successfully been fired off, and a falsey value if not.
Type
boolean

exportDocumentDialog()

Displays the export document dialog box.

exportMultipleDocuments(documentIds, optionsopt)

Exports a document assembled from the document ID array passed in. The new exported document will be each requested document in the order it appears in the document ID array. The documents do not need to be open in the viewer. If a document is indeed open in the viewer, and has page modifications such as crop, image adjustment, or page manipulations, those modifications will appear in the final exported document. If a document is not open, no unsaved modifications will appear. The document will not be exported with any redactions, annotations, watermarks, document notes, or bookmarks. The final document may only be a pdf or a tiff. To set the exported document's preferred file name, see VirtualViewer#setExportDocumentNameGenerator.
Parameters:
Name Type Attributes Description
documentIds array The array of document IDs to print. The documents do not need to be open in the viewer. If none are provided, ie if the parameter is falsey, and options.exportDocumentList is set to true, the function will assemble all the documents in the viewer's document list.
options object <optional>
Properties
Name Type Attributes Default Description
exportDocumentList boolean <optional>
 false If this is true, and the documentIds parameter is not provided, the function will use the document list as its documentIds array, and assemble every document in the list together.
exportFormat string <optional>
 "pdf" Either "pdf" or "tiff"--the format that the final exported document should use.
Returns:
undefined

firstPage()

Switches the current document to its first page.

fitHeight()

Zooms the the current page so its height fits exactly within the height of the viewing area.

fitWidth()

Zoom the the current page so its width fits exactly within the the width of the viewing area.

fitWindow()

Zooms the current page so it fits exactly within the viewing area.

flipX()

Flip the the current page along the X axis.

flipY()

Flip the current page along the Y axis.

getActiveTab() → {number}

Retrieve the 0-based index of the active, or currently selected, document tab.
Returns:
The zero-based index of the active tab.
Type
number

getBrightness() → {number}

Get the brightness value of the current page. If the brightness has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Returns:
The brightness value of the current image.
Type
number

getBrightnessForPage(pageNumber) → {number}

Get the brightness value of a specified page. If the brightness has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Parameters:
Name Type Description
pageNumber number the page number the user wants the brightness of
Returns:
The brightness value of the current image.
Type
number

getClientInstanceId() → {string}

Returns the clientInstanceId. This value is extremely helpful for passing custom data from the client down to the content handler.
Returns:
The clientInstanceId for the current document.
Type
string

getContrast() → {number}

Get the contrast value of the current page. If the contrast has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Returns:
The contrast value of the current image.
Type
number

getContrastForPage(pageNumber) → {number}

Get the contrast value of a specified page. If the contrast has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Parameters:
Name Type Description
pageNumber number the page number the user wants the contrast of
Returns:
The contrast value of the current image.
Type
number

getDisplayName() → {string}

Get the current document's display name. This may or may not be different from the document ID.
Returns:
Current display name
Type
string

getDocumentId(paneIndexopt) → {string}

Get the ID of a currently-open document.
Parameters:
Name Type Attributes Description
paneIndex number <optional>
 If the viewer is in split screen mode, this optional parameter allows retrieving the ID of either open document. If not passed in, the function will return the ID of the document in the active pane (indicated by a blue border).
Returns:
Current document's ID.
Type
string

getGamma() → {number}

Get the gamma value of the current page. If the gamma has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Returns:
The gamma value of the current image.
Type
number

getGammaForPage(pageNumber) → {number}

Get the gamma value of a specified page. If the gamma has been modified, this API will return the modified value. However, if the document has been saved after the modification, this API will return the default value: if a modified page has been saved, the pixels have been changed and it has a new normal.
Parameters:
Name Type Description
pageNumber number the page number the user wants the gamma of
Returns:
The gamma value of the current image.
Type
number

getMediaPlayer() → {object}

Retrieve the player for the media currently playing. Returns null if no media is onscreen.
Returns:
The HTML5 video tag currently onscreen.
Type
object

getOriginalPageDimensions() → {object}

Get the dimensions of the current page of the current document. These dimensions are in pixels, and are the baseline width and height that the viewer uses for scaling, drawing, and display.
Returns:
This object has two properties, width and height. If there is no document open, both the width and height will be undefined.
Type
object

getOverlayImage(overlayDocumentId, options)

Overlay a separate text document/image on the current document. As an example, this can be used to overlay form inputs over a base document's form template. This function will load the given image and display it over the base document. White sections of the overlay will be made transparent, through which the base document can be seen. The overlay can be dragged around to align it with the document underneath. The same overlay image will appear on each page. By default, each page's overlay will be dragged around together; an option parameter will allow them to move independently. The overlay image appears by default on every page. An array in the options object can define which pages should display the overlay image, right off the bat. If called multiple times with the same overlayDocumentId value, a new image will not be requested, but the given pages array will override the current pages that the overlay displays on-- for instance if an overlay is displaying on pages 2 and 5, calling this function with {pages: undefined} will show the overlay on all pages.
Parameters:
Name Type Description
overlayDocumentId string The ID of the document that should overlay the current document.
options object Startup options for the overlay image.
Properties
Name Type Description
pages array A selection of pages to apply the image to. If undefined, the overlay will apply to all pages
lockOverlayMovement boolean If true, overlays on all pages will move simultaneously when dragged. If unspecified when first loading an overlay, this will default to true.

getPageCount() → {number}

Get the total number of pages in the current document.
Returns:
The page count of the currently-open document. Will be undefined if no document is open.
Type
number

getPageNumber() → {number}

Get the current page number of the active document. The current page is also highlighted visually in the page thumbnails.
Returns:
zero-based page index
Type
number

getPageProperties() → {Array.<object>}

Returns an array of objects that represents the entire set of properties for the current page. These properties are also used in the image info dialog in the viewer. Each object in the array corresponds to a "field" or single property item, like the document's ID. The properties of a "field" object are: the field ID ("fieldId"), the readable caption or title of the field ("fieldCaption") and the value ("fieldValue").
Returns:
An array of property objects.
Type
Array.<object>

getPagePropertyByCaption(fieldCaption) → {number|string}

Retrieves a page property based on the caption of the field. Page properties are displayed to the user in the image info dialog; this function's argument, the caption, is the readable title of a field. Captions can be configured in config.js, in the vvConfig.imageInfoFields property. Note that field IDs should not be changed.
Parameters:
Name Type Description
fieldCaption string The caption to search for in the image info fields.
Returns:
The value of the given field.
Type
number | string

getPagePropertyByFieldId(fieldId) → {string|number}

Retrieve the page property value for the given fieldId. Page properties are displayed to the user in the image info dialog: for example, the document's display name by default is labeled "Document Name". While the order of info fields and their captions can be configured in config.js, field IDs should not be modified. Valid fieldIds are "pageCount", "documentDisplayName", "documentByteSize", "documentId", "dpi", "compressionType", "bitDepth", "pageNumber", "documentFormat", "imageSizePixels", "imageSizeInches" and "tiffTag";
Parameters:
Name Type Description
fieldId string The ID of the page property. Valid fieldIds are "pageCount", "documentDisplayName", "documentByteSize", "documentId", "dpi", "compressionType", "bitDepth", "pageNumber", "documentFormat", "imageSizePixels", "imageSizeInches" and "tiffTag"
Returns:
The value in the requested info field.
Type
string | number

getProperty(propertyKey) → {string}

The document model may store properties to pass to and from the content handler. This function is a passthrough to retrieve an arbitrary value from the content handler.
Parameters:
Name Type Description
propertyKey string The string key of the property to retrieve.
Returns:
The value of the custom property.
Type
string

getUsername() → {string}

Retrieve the current username. The viewer stores a current username in localforage, editable in User Preferences. The viewer does not handle changing the username based on session.
Returns:
The current username.
Type
string

getZoomPercent() → {number}

Retrieve the current page's zoom value. This returns a ratio, floating point value, not a whole number out-of-one-hundred percentage. The ratio is the page's current, drawn, height in pixels divided by its original pixel height. Please note that this is different from the whole percentage (50 for 50% zoom) that VirtualViewer#setZoomPercent expects as a parameter.
Returns:
The zoom ratio. For instance, 0.5 for a 50% zoom.
Type
number

goToNextPageWithAnn()

Navigate the viewer to the next page that contains an annotation.

goToPrevPageWithAnn()

Navigate the viewer to the previous page that contains an annotation.

hideImageInfo()

Hide the Image Info dialog box.

increaseBrightnessForSelectedPages(pageNumberArray, value)

Increase the brightness of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

increaseContrastForSelectedPages(pageNumberArray, value)

Increase the contrast of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

increaseGammaForSelectedPages(pageNumberArray, value)

Increase the gamma of a list of pages
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number a whole number

init(openDoc)

Initialize the viewer. Without arguments the viewer is initialized without an open document. If the 'openDoc' parameter is true, and the viewer has a document's ID set already, it will attempt to open that document. This should only be called once, and is unnecessary to call if initSpecifiedDocuments() or initViaURL() has been called. In most normal cases, the viewer will handle its own initialization. To replace the default initialization, define a function called beforeVirtualViewerInit and perform initilization there. VirtualViewer will detect that initialization has occurred. Define functions beforeVirtualViewerInit or afterVirtualViewerInit to inject custom code before or after initialization.
Parameters:
Name Type Description
openDoc boolean Whether or not to open a tab immediately after initialization.
See:

initSpecifiedDocuments(documentIdAndNames)

Initialize the viewer with a list of document IDs and display names, and open all of those documents immediately as tabs. This should only be called once, and is unnecessary to call if init() or initViaURL() has been called. To open a set of documents without worrying about initialization code, call openSpecifiedDocuments. In most normal cases, the viewer will handle its own initialization. To replace the default initialization, define a function called beforeVirtualViewerInit and perform initilization there. Return false to prevent the viewer from performing its own initialization. Define functions beforeVirtualViewerInit or afterVirtualViewerInit to inject custom code before or after initialization.
Parameters:
Name Type Description
documentIdAndNames Array.<object> | Array.<string> An array of objects, each containing a document ID and its display name. The properties of each object are below. This parameter can also simply be an array of strings--an array of the IDs of the documents to initialize.
documentIdAndName[].documentId string The ID of the document. For instance, "6-Pages.tif".
documentIdAndName[].displayName string A display name for the document. By default, this is the same as the ID, but it can be changed from the content handler.
See:

initViaURL()

Initialize the viewer based on parameters passed in via the URL query (i.e. &documentId=foo&clientInstanceId=bar) This should only be called once, and is unnecessary to call if initSpecifiedDocuments() or init() has been called. In most normal cases, the viewer will handle its own initialization. To replace the default initialization, define a function called beforeVirtualViewerInit and perform initialization there, by calling a VirtualViewer initialization API. Define functions beforeVirtualViewerInit or afterVirtualViewerInit to inject custom code before or after initialization.

invertImage()

Invert the colors of the current page. If this operation is performed, the image will be converted to a bitmap.

isDocumentSearchable() → {boolean}

Determine if the current document is searchable (if it has computer-readable text).
Returns:
True if the document is searchable, false otherwise.
Type
boolean

isInitialized()

Check if this instance of VirtualViewer has been initialized.

lastPage()

Navigate the viewer to the last page of the current document.

loggingOverride(loggingOverrideopt) → {boolean}

Get/set logging override flag. This is meant for debugging purposes - if set to true all server logs will be made to the highest priority (i.e. ERROR) for requests made this session while the flag is active.
Parameters:
Name Type Attributes Description
loggingOverride boolean <optional>
 Set the override value. This is an optional parameter. If it is not passed in, then this function will return the current logging override value. The logging override will never be set to undefined.
Returns:
The current override level
Type
boolean

moveOverlayImagesTogether(turnOn)

Overlay template images have a setting that will cause them to be moved together on all pages, or independently for each page.
Parameters:
Name Type Description
turnOn boolean If this parameter is true or undefined, the overlay images on each page will have their movement locked together. Setting this to false will allow independent movement of the images on each page.
See:

nextPage()

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

nextSearchResult()

Highlight the next search result on the document text, switching pages if necessary. This function will work for both annotation and normal text searching, even though they have different calls to launch the search.
See:

openDocumentsInTabs(documentList, tabNumber)

Given a list of document IDs, create a new tab for each document and load it. Then, set the focus on a specific document.
Parameters:
Name Type Description
documentList string List of document IDs to open in a new tab
tabNumber number The index of the document from the list, which will have focus

openInTab(id)

Given a document's ID, create a new tab for that document and load it. This is the function called when clicking on a document thumbnail.
Parameters:
Name Type Description
id string The ID of the document to open.

openSpecifiedDocuments(documentIdAndNameopt)

Open each specified document in a tab. This can be called with a list of document IDs, or called without a parameter to open each document in the viewer's current document list. It will not attempt to open any documents past the viewer's defined maximum number of tabs. This function should be called only after VirtualViewer has been initialized.
Parameters:
Name Type Attributes Description
documentIdAndName Array.<Object> | Array.<string> <optional>
 An array of Objects, each containing a document's ID and display name. The properties of a single documentIdAndName object is below. This parameter can also be simply a string array, holding the IDs of the documents that should be opened.
Properties
Name Type Description
documentId string The ID of the given document.
displayName string The display name of the given document.

pageContainsAnnotations(pageNumber) → {boolean}

Returns true if the specified page is annotated.
Parameters:
Name Type Description
pageNumber number The zero-based page number to inspect.
Returns:
True if the page is annotated
Type
boolean

pageHasText() → {boolean}

Returns whether or not the current page contains user-selectable text. This value may change as more data is loaded from the server.
Returns:
True if the page has selectable text.
Type
boolean

pagesWithAnnotations() → {Array.<number>}

This method returns an array of all the page numbers of annotated pages.
Returns:
An array of page numbers. Each page on the list will contain at least one annotation.
Type
Array.<number>

pasteSelection(beforePageNumopt, newDocumentopt, showAlertopt)

Paste the pages currently stored in the viewer's clipboard into the document. The document will update all bookmarks, watermarks, and other page-dependent information.
Parameters:
Name Type Attributes Default Description
beforePageNum number <optional>
 0 A zero-based page index specifying where to insert the new pages. Pages will be pasted into the document before this page number.
newDocument boolean <optional>
 false Used internally when creating a new document from the pages of an existing document.
showAlert boolean <optional>
 false Show an alert dialog if page manipulations are disabled. If page manipulations are disabled, pasting will always be blocked; this parameter controls the alert given as feedback.

playAudio() → {boolean}

Start Audio playback.
Returns:
If the action is not allowed, return false; otherwise, true.
Type
boolean

playMedia() → {boolean}

Start Media playback.
Returns:
If the action is not allowed, return false; otherwise, true.
Type
boolean

playVideo() → {boolean}

Start Video playback.
Returns:
If the action is not allowed, return false; otherwise, true.
Type
boolean

previousPage()

Navigate the viewer to the previous page in the current document.

previousSearchResult()

Highlight the previous search result on the document text, switching pages if necessary. This function will work for both annotation and normal text searching, even though they have different calls to launch the search.
See:

printDocument(options)

Print a document, using the browser's print dialog.
Parameters:
Name Type Description
options object An arguments object.
Properties
Name Type Attributes Default Description
documentId string <optional>
 The active document's ID The ID of a document to print. This document must be open in the viewer.
printToPDF boolean <optional>
 false If true, a PDF version of the document will be exported to a file. The user will be presented with a save dialog.
includeAnnotations boolean <optional>
 false Whether to include annotations on the printed document.
includeRedactions boolean <optional>
 false Whether or not to fully redact the printed document.
includeRedactionTags boolean <optional>
 false Whether or not to include redaction tags (only used when redactions are applied to the document).
includeWatermarks boolean <optional>
 false Whether or not to print with any of the VirtualViewer-generated watermarks currently on the document.
includeDocumentNotes boolean <optional>
 false Set this to true to append document notes as text pages at the end of the document.
fitToPage boolean <optional>
 false Whether to force raster PDFs to letter-sized pages with the image centered on the page.
pageRangeType string <optional>
 "all" Options are "all", "complex" or "current". If "complex", the parameter pageRangeVal must be included; otherwise it will be ignored.
pageRangeValue string <optional>
 A range of pages numbers to print (only used for "complex" pageRangeType). Commas and dashes may be used. For instance, "2-4,7,10-11" would print only pages 2, 3, 4, 7, 10 and 11.

printDocumentDialog(pages)

Initialize and display the print document dialog.
Parameters:
Name Type Description
pages Array.<number> An array of 0-based page indices. The print dialog will initialize with these pages already in the page range text box.

printMultipleDocuments(documentIds, optionsopt)

Prints a document assembled from the document ID array passed in. The new printed document will be each requested document in the order it appears in the document ID array. The documents do not need to be open in the viewer. If a document is indeed open in the viewer, and has page modifications such as crop, image adjustment, or page manipulations, those modifications will appear in the final printed document. If a document is not open, no unsaved modifications will appear. The document will not be printed with any redactions, annotations, watermarks, document notes, or bookmarks.
Parameters:
Name Type Attributes Description
documentIds array The array of document IDs to print. The documents do not need to be open in the viewer. If none are provided, ie if the parameter is falsey, and options.printDocumentList is set to true, the function will assemble all the documents in the viewer's document list.
options object <optional>
Properties
Name Type Attributes Default Description
printDocumentList boolean <optional>
 false If this is true, and the documentIds parameter is not provided, the function will use the document list as its documentIds array, and assemble every document in the list together.
fitToPage boolean <optional>
 false Whether to force raster PDFs to letter-sized pages with the image centered on the page.
Returns:
undefined

redoAnnotation()

The reciprocal redo for an undo operation. Undo/redo is only supported for annotations. There is currently no limit imposed on the undo stack.
See:

reloadAnnotations(documentIdopt, documentPaneIndexopt)

This API is intended to reload the annotations on the document from their server state.
Parameters:
Name Type Attributes Default Description
documentId string <optional>
 Pass in a document ID to specify a document model to reload. Otherwise, this will reload the current document.
documentPaneIndex number <optional>
 The index of the currently active pane, visually marked by a blue border Pass in a zero-indexed number to specify a document pane. This is only necessary if a user has identical documents open in document compare.

reloadDocument(documentIdopt, documentPaneIndexopt, passthroughCallbackopt)

Reloads a document from the server, reversing unsaved crop, image manipulation, flip, rotation, and annotation modifications. This includes crop, image manipulation, flips, and rotations.
Parameters:
Name Type Attributes Default Description
documentId string <optional>
 Pass in a document ID to specify a document model to reload. Otherwise, this will reload the current document.
documentPaneIndex number <optional>
 The index of the currently active pane, visually marked by a blue border Pass in a zero-indexed number to specify a document pane. This is only necessary if a user has identical documents open in document compare.
passthroughCallback function <optional>
 Pass in a function to be called when the document model has successfully loaded.

reloadDocumentModel(documentIdopt, documentPaneIndexopt, callbackopt)

Reload the document model from the server, discarding any current modifications (rotation/flip/invert as well as page manipulations). NOTE: This does not currently effect annotations.
Parameters:
Name Type Attributes Default Description
documentId string <optional>
 Pass in a document ID to specify a document model to reload. Otherwise, this will reload the current document.
documentPaneIndex number <optional>
 The index of the currently active pane, visually marked by a blue border Pass in a zero-indexed number to specify a document pane. This is only necessary if a user has identical documents open in document compare.
callback function <optional>
 Pass in a function to be called when the document model has successfully loaded.

removeAllAnnotationIndicators()

This method removes all annotation indicators on the page thumbnails. This feature can be toggled in config.js, by setting showAnnIndicators to true or false.

removeAllCrop()

Remove the crop preview on the entire document. Crop in VirtualViewer has two stages. While the document is not saved, crop is in "preview," and the viewer is drawing a section of the full image. When the document is saved, the page is re-rendered as the cropped version, and the viewer is now painting the "whole" cropped image instead of a preview. This function will only remove unsaved crops. Cropping can be enabled or disabled in config.js by setting "enableCrop" to true or false.

removeAllDocumentViewedIndicator()

This method will just hard remove every marker on the document thumbs.

removeAnnotationIndicators(pageNum)

This method removes an annotation indicator from a specific page's thumbnail.
Parameters:
Name Type Description
pageNum number The 0-based page index whose annotation indicator should be removed.
See:

removeCallback(callbackString, removeVirtualViewerHandlersopt) → {boolean}

Remove handler functions from a callback. This is similar to the "off" function of jquery events--it removes all event subscribers.
Parameters:
Name Type Attributes Default Description
callbackString string The name of the callback. For instance, "onDocumentLoad".
removeVirtualViewerHandlers boolean <optional>
 false Clear VirtualViewer default callbacks. This is not recommended unless intentionally replacing default behavior, as with some uses of the saveAsDocument callback.
See:
Returns:
True if the callback name exists and the callback was successfully cleared.
Type
boolean

removeCropOnPage(page)

Remove the crop preview on the given page of the current document. This function will only remove an unsaved crop; after saving, the crop is complete and no longer a preview.
Parameters:
Name Type Description
page number The 0-based page index to remove crop from.
See:

removeDocumentArrayFromCache(documentIdArray, clientInstanceId)

Tell the server to remove documents completely from its cache. If the document is accessed again, its content will be retrieved from the content handler.
Parameters:
Name Type Description
documentIdArray Array.<string> The ID array of the documents to be removed from the cache.
clientInstanceId string If omitted (i.e. undefined), the current clientInstanceId of VV will be used.

removeDocumentFromCache(documentId, clientInstanceId)

Tell the server to remove a document completely from its cache. If the document is accessed again, its content will be retrieved from the content handler.
Parameters:
Name Type Description
documentId string The ID of the document to be removed from the cache.
clientInstanceId string If omitted (i.e. undefined), the current clientInstanceId of VV will be used.

removeDocumentViewedIndicator(documentId)

This method removes the blue checkmark from a specified document.
Parameters:
Name Type Description
documentId String The document ID of the thumbnail you want unmarked.

removeOverlayFromPage(page) → {number}

Remove an overlay template image from the given page.
Parameters:
Name Type Description
page number The page to remove the image from.
See:
Returns:
The page affected, or undefined if no page was affected.
Type
number

removePageFromSelection(pageNumber)

Remove the specified pages number from the current selection.
Parameters:
Name Type Description
pageNumber number The 0-based page index to unselect.

resetSVGSupport(valueopt)

Reset SVG status for the current document. If no argument is passed, the value of vvConfig.enableSVGSupport will be used. SVG support determines whether the viewer attempts to load an image as an SVG or as a bitmap. Note: If vvConfig.enableSVGSupport is false, that value will take precedence and the pages will continue to be rendered as bitmaps.
Parameters:
Name Type Attributes Default Description
value boolean <optional>
 The value for resetSVGSupport in config.js The value to set for each page's "enable SVG" property.

rotateAllPagesBy(degrees)

Rotate all of the document's pages 0, 90, 180 or 270 (positive or negative) degrees from its current state.
Parameters:
Name Type Description
degrees number A value of 0, 90, 180 or 270

rotateClock()

Rotate the current page of the current document by 90 degrees clockwise.

rotateCounter()

Rotate the current page of the current document by 90 degrees counterclockwise.

rotateImageBy(degrees)

Rotate the current page 0, 90, 180 or 270 (positive or negative) degrees from its current state.
Parameters:
Name Type Description
degrees number A value of 0, 90, 180 or 270.

rotateImageTo(degrees)

Rotate the current page of the current document to 0, 90, 180 or 270 degrees, from its original (saved) state. This will reset any previous rotation.
Parameters:
Name Type Description
degrees number A value 0, 90, 180 or 270. Negative values are accepted.

rotatePageBy(page, degrees) → {boolean}

Rotate the given page 0, 90, 180 or 270 (positive or negative) degrees from its current state.
Parameters:
Name Type Description
page number The 0-based index of the page to rotate.
degrees number A value 0, 90, 180 or 270.
Returns:
True if the rotation was successful.
Type
boolean

rotatePageTo(page, degrees) → {boolean}

Rotate the given page 0, 90, 180 or 270 degrees from its original (saved) state of 0 degrees rotation. This will reset previous rotation.
Parameters:
Name Type Description
page number The 0-based index of the page to be rotated.
degrees number A value of 0, 90, 180 or 270. Negative values are accepted.
Returns:
True if the rotation was successful.
Type
boolean

rotateSelectedPagesBy(pages, degrees)

Rotates specified pagees of the document by 0, 90, 180 or 270 degrees from its current state.
Parameters:
Name Type Description
pages Array.<number> An array of the 0-based page indices that should be rotated
degrees number A value of 0, 90, 180 or 270. These values may be negative

saveDocument(docIdopt, optionsopt)

Save the current document, including annotations and any image manipulations. The most basic call of this function is simply virtualViewer.saveDocument(), which saves the current document as it is. Passing in additional parameters can save documents other than the current (pass in a docId); can save a document as (pass in options.newDocumentId); and in Save As can include or exclude annotations, redactions, pages, and many more aspects of a VirtualViewer document.
Parameters:
Name Type Attributes Default Description
docId string <optional>
 The current document The ID of the document to save. This document should be currently open (though it may not be currently displayed, it should at least be open in a VirtualViewer tab). If not set, the current document will be saved.
options object <optional>
 An object storing optional parameters.
Properties
Name Type Attributes Default Description
newDocumentId string <optional>
 Set this parameter to save the current document as a new document in the system. If set, this function operates as "save as". The original document will remain unchanged, and VirtualViewer will ask the content handler to save a new document with a new ID. Several of the following parameters are designed to only affect Save As.
newDisplayname string <optional>
 newDocumentId Set the display name of the new document. This will only be respected if newDocumentId is set.
burnRedactions boolean <optional>
 false Set to true to permanently burn redactions into the new document. If redactions are burned in, the underlying image is converted to the redaction's black box, and underlying text is removed. This is not reversible.
includeRedactionTags boolean <optional>
 Whether or not to include redaction tags. This is only respected if burnRedactions is true.
includeTextAnnotations boolean <optional>
 false Used to permanently burn text annotations into the new document.
includeNonTextAnnotations boolean <optional>
 false Used to permanently burn non-text annotations into the new document.
copyAnnotations boolean <optional>
 false Used to copy annotation layers (including redactions) into the new document.
includeWatermarks boolean <optional>
 false Whether to permanently burn watermarks into the new document. If true, copyWatermarks setting is ignored and watermarks are not copied.
pageRangeType string <optional>
 Either "all", "complex" or "current". This parameter is only respected in Save As.
pageRangeValue string <optional>
 A range of pages numbers to export. Dashes and commas can be used: for instance, "2-4,7,10". This will only be respected if pageRangeType is set to "complex". This parameter is only respected in Save As.
copyWatermarks string <optional>
 true Whether to save/copy watermarks alongside the document. Watermarks saved with this parameter will be editable in the future.
saveAsFormat string <optional>
 This can be "Original", "PDF" or "TIFF". Note that "Original" may only be used when exporting a document without including annotations, redactions, watermarks, or document notes. Additionally, to export as the original format, pageRangeType must be "all". This parameter is only respected in Save As.
skipOverwriteDialog boolean <optional>
 false If the current document will be overwritten by a save action, VirtualViewer alerts the user with a dialog. Provide true to this parameter to suppress that dialog.
documentPaneIndex number <optional>
 the currently active document or the provided document ID If document compare is open, provide an index to specify whether to save the first or second open document. Provide 0 for the left-hand document and 1 for the right-hand document. This may be helpful if the user has the same document open in both panes.

saveDocumentAsDialog()

Launch the Save As dialog.

searchAnnotationText(term)

Search for a term on the document's annotations. Available text to search includes: text and sticky note contents, annotation tags, and annotation notes. Processing for this search occurs on the client.
Parameters:
Name Type Description
term string The search term.

searchText(term, firstPageopt, lastPageopt, skipOcrPromptopt, ocrLanguageopt)

Searches for a term between the pages specified. This search is performed serverside. The viewer sends batches of pages to be searched, and receives lists of search results. Search settings like case sensitivity are controlled in config.js.
Parameters:
Name Type Attributes Default Description
term string The string to search for in the document text.
firstPage number <optional>
 The first page of the document The 0-based index of the first page of a range to search.
lastPage number <optional>
 The last page of the document The 0-based index of the last page, inclusive, of the range to search.
skipOcrPrompt boolean <optional>
 false If OCR is enabled, this parameter will disable the default dialog that asks the user if they want to OCR the document. The viewer will always ask about OCR before performing OCR. If the document has any text at all, it will not attempt OCR before searching. If OCR is disabled, the dialog will never show.
ocrLanguage string <optional>
 If OCR is enabled, this will allow overriding the default OCR language for this document. This parameter should be a three-letter ISO language code. If not specified, the language will be the default set in config.js.

selectAllText()

Select all the text on the current page of the current document. This highlights the text visually, and makes the text available to be copied or annotated by the right-click menu.

sendDocument(documentId)

"Send" the document to the content handler. Conceptually this is somewhere between Save and Export, with the final action decided by the content handler implementation. handler.
Parameters:
Name Type Description
documentId string The ID of the document to send.
Deprecated:
  • Export and Save As functionality is more robust, and recommended.

setAnnotationsEnabled(enabled) → {boolean}

Set whether or not annotations are enabled.
Parameters:
Name Type Description
enabled boolean If true, annotations will be enabled. If false, they will be disabled
Returns:
true if annotations are enabled, false otherwise
Type
boolean

setBrightness(value)

Set the brightness of the current page. Note that if a document is saved with an image manipulation like this, it will be converted to a bitmap image.
Parameters:
Name Type Description
value number Range is whole numbers from -125 to 125. Default is 0.

setBrightnessForSelectedPages(pageNumberArray, value)

Set the brightness of a list of pages.
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number Range is whole numbers from -125 to 125

setCallback(callbackString, fn) → {boolean}

Set a callback function.Callbacks are set by passing the name of the callback, and the handler function. All callback functions will take one parameter, an arguments object. Callback types are described in the Callbacks page. Supported callbacks are linked below.
Parameters:
Name Type Description
callbackString string The name of the callback. For instance, "onDocumentLoad".
fn function The handler function. For instance, a function with the signature onDocumentLoad.
Returns:
True if the callback string was found and the callback was successfully set.
Type
boolean

setClientInstanceId(id)

Set the current clientInstanceId. This item will be sent to the server with all requests, and will be passed all the way down to the content handler, so is a good way to pass additional parameters or authentication information to the content handler.
Parameters:
Name Type Description
id string The clientInstanceId

setContrast(value)

Set the contrast on the current page. Note that if a document is saved with an image manipulation like this, it will be converted to a bitmap image.
Parameters:
Name Type Description
value number Range is whole numbers from -125 to 125. Default is 0.

setContrastForSelectedPages(pageNumberArray, value)

Set the contrast of a list of pages.
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number Range is whole numbers from -125 to 125

setCurrentAnnotationId(annotationId) → {String}

Set the ID of the currently selected annotation. If the annotationId parameter is null, an ID will be generated and assigned to the currently selected annotation.
Parameters:
Name Type Description
annotationId String
Returns:
The annotation ID, whether passed-in or generated, that was set. Returns null if an ID could not be set.
Type
String

setDisplayName(newDisplayName, documentIdopt) → {string}

Set a document's display name. Provide the document's ID, or leave it out to set the display name on the current tab.
Parameters:
Name Type Attributes Description
newDisplayName string A string containing the new document display name.
documentId string <optional>
 The ID of the document whose display name should change. This is an optional parameter; if not given, the current tab will have its display name changed.
Returns:
The new display name, or null if the display name could not be set--if an appropriate document could not be found.
Type
string

setDocumentId(id)

Set a document to open immediately when the viewer opens. Alternately, instead of manually setting a document before the viewer initializes, call initSpecifiedDocuments or openSpecifiedDocuments. A good way to inject initialization calls like this is by defining a function called beforeVirtualViewerInit. This function will be called before full initialization and may replace default initialization by calling an initialization API function. VirtualViewer will detect that initialization has occurred. NOTE: This method is only supported before initialization. Once the viewer is initialized, use openInTab() to open a new document.
Parameters:
Name Type Description
id string The ID of the document to open.
See:

setDocumentIdGenerator(fn)

Set a callback function to be called when creating a new document. Instead of prompting the user to name the document, the passed function will be called.
Parameters:
Name Type Description
fn function The function to call when a document's ID needs to be generated.

setExportDocumentNameGenerator(fn)

Sets a callback function to be called when exporting a document. Instead of using the document's ID as the name of the downloaded file, the passed function will be called. The string it returns will be used as the filename.
Parameters:
Name Type Description
fn function The function to call when exporting. This takes one argument: the exported document's file extension. It should return a string.

setFitWidthPercentage(val, setFitWidth)

Function to set the amount of the screen fitToWidth sizes to. Allows users to set it to non-standard percentages
Parameters:
Name Type Description
val number number between 0.5 and 1 that is the percentage fitWidth will size to.
setFitWidth boolean If true, set the User Preferences option to fitWidth, and immediately fit all documents to the percentage width. If false or not set, the percentage will be saved in User Preferences but the current documents will not be re-zoomed.
Returns:
false if failed, true if set properly.

setGamma(value)

Set the gamma of the current page. Note that if a document is saved with an image manipulation like this, it will be converted to a bitmap image.
Parameters:
Name Type Description
value number Range is whole numbers from 0 to 400. Default is 100.

setGammaForSelectedPages(pageNumberArray, value)

Set the gamma of a list of pages.
Parameters:
Name Type Description
pageNumberArray array an array of the selected page numbers
value number Range is whole numbers from 0 to 400

setImageLoadCompletedHandler(fn)

Set a callback function to be called when the image has finished loading.
Parameters:
Name Type Description
fn imageLoadCompleted The function to call when the image has finished loading.
Deprecated:
  • Use virtualViewer.setCallback("imageLoadCompleted", foo) instead.
See:

setImageLoadRequestedHandler(fn)

Sets a callback function to be called when the image has been requested.
Parameters:
Name Type Description
fn imageLoadRequested The function to call when the image has been requested.
Deprecated:
  • Use virtualViewer.setCallback("imageLoadRequested", foo) instead.
See:

setMagnifierPosition(x, y)

Set the position of the magnifier. This position is based on the coordinates of the image canvas. The magnifier will jump to the new position and paint the portion of the image under it.
Parameters:
Name Type Description
x number The X position of the magnifier.
y number The Y position of the magnifier.
See:

setPage()

Set the current page for the current document. This will cause the viewer to immediately jump to the new page.

setPageChangeCompletedHandler(fn)

Set a callback function to be called when a page has been changed.
Parameters:
Name Type Description
fn pageChange The function to call when the page changes. The function will be passed an object containing the property "page".
Deprecated:
  • Use virtualViewer.setCallback("pageChange", foo) instead.
See:

setPageDisplayNames(displayNames)

If vvConfig.displayThumbFooters is set to true, page thumbnails may display a text name instead of the page number.
Parameters:
Name Type Description
displayNames Array.<string> An array of display names to set. VirtualViewer will override every page's display name with this array.

setProperty(propertyKey, propertyValue)

Set an arbitrary key/value pair in the document model. This pair will be passed to the content handler.
Parameters:
Name Type Description
propertyKey string The string key of the property.
propertyValue string A value to store in the property.

setRedactionsEnabled(enabled) → {boolean}

Set whether or not redactions are enabled.
Parameters:
Name Type Description
enabled boolean If true, redactions will be enabled. If false, they will be disabled.
Returns:
True if redactions are enabled, false otherwise.
Type
boolean

setRotationCompletedHandler(fn)

Set a callback function to be called when a page has been rotated. The function will be passed an object containing a page variable and a rotation variable.
Parameters:
Name Type Description
fn rotation The function to call when the page rotates.
Deprecated:
  • Use virtualViewer.setCallback("rotation", foo) instead.
See:

setSaveAsDocumentCompletedHandler(fn)

Set a callback function to be called when a copy of a document has been saved. Function recieves an object with documentID, clientInstanceId, and documentToReload variables.
Parameters:
Name Type Description
fn saveAsDocument The function to call when document has been saved
Deprecated:
  • Use virtualViewer.setCallback("saveAsDocument", foo) instead.
See:

setSaveAsDocumentNameGenerator(fn)

Sets a callback function to be called when saving a copy of a document. Instead of using the "Copy-[documentId].[ext]" as the documentId, the passed function will be called and the string it returns will be used as the new document's display name and initial ID. Your function will be passed three string parameters: - the document ID of the original document - the display name of the original document (may be null/undefined) - the file extension of the output format (either "pdf" or "tif")
Parameters:
Name Type Description
fn function The function to call when saving a copy of a document. This function should accept three parameters (document ID, display name, and file extension) and return the new document's display name.
Returns:
undefined

setSaveDocumentCompletedHandler(fn)

Set a callback function to be called when a document has been saved. The handler function receives an object with documentID, clientInstanceId, and documentToReload variables.
Parameters:
Name Type Description
fn saveDocument The function to call when document has been saved.
Deprecated:
  • Use virtualViewer.setCallback("saveDocument", foo) instead.
See:

setSendDocumentCompletedHandler(fn)

Set a callback function to be called when a document has been sent.
Parameters:
Name Type Description
fn sendDocument The function to call when document has been sent.
Deprecated:
  • Use virtualViewer.setCallback("sendDocument", foo) instead.
See:

setUploadDocumentCompletedHandler(fn)

Set a callback function to be called when a new document has been uploaded. The handler function takes an object with docToReload and clientInstanceId variables.
Parameters:
Name Type Description
fn uploadDocument The function to call when document has been saved.
Deprecated:
  • Use virtualViewer.setCallback("uploadDocument", foo) instead.
See:

setZoomLock((boolean))

API method to toggle zooming both panes vs zooming them individually.
Parameters:
Name Type Description
(boolean) lock Pass true to lock zoom when document compare is open, and false to be able to zoom the document compare panes individually.

setZoomPercent(percentLevel)

Zoom to specified percentage level on the current document, e.g. 50 for 50% zoom. The viewer will tops zooming in when maximum zoom percent is reached, and will stop zooming out when the minimum zoom percent is reached. Zooming can be finely configured in config.js. Please note that this percentage zoom value is different from the ratio (0.5 for 50% zoom) that VirtualViewer#getZoomPercent returns.
Parameters:
Name Type Description
percentLevel number The target zoom value. For 100% zoom, pass in 100.

showAboutDialog()

Display the About dialog box.

showAllAnnotationIndicators()

This method adds small red checkmark indicators to all the page thumbnails that have annotations. To function, the configuration variable showAnnIndicators must be set to true.

showAnnotationIndicator(pageNum)

This function adds an annotation indicator to the thumbnail of the specified page. The configuration variable showAnnIndicators must be set to true in config.js for this function to run.
Parameters:
Name Type Description
pageNum number The 0-based index of the page that should display an indicator.

showAnnotationNaviPanel(showopt)

Toggle the visibility of the annotation navigation panel. This panel appears at the top of the page thumbnail pane, and allows navigation through the current document's annotations.
Parameters:
Name Type Attributes Description
show boolean <optional>
 This will perform the toggle. If false, the panel will hide. If true or undefined, the panel will show.

showImageInfo()

Display the Image Info dialog box.

showPictureControlsDialog()

Launch the Picture Controls dialog. This dialog allows users to modify the image's brightness, contrast, and gamma values.

showTagAllRedactionsDialog()

Show the Redaction Tags dialog. With this dialog, the uesr can apply tags to all redactions. This is generally for use with search, for instance if a user has searched for and redacted all phone numbers, and now wants to tag them as such. Configure available redaction tags in the config.js variable "annotationTags".

showUploadLocalFileDialog()

Display the dialog that allows the user to upload a file. Uploading can be disabled fully in the web.xml/web.config file, or the button can simply be toggled with User Preferences.

showUserPreferencesDialog()

Display the User Preferences dialog box. User Preferences can be disabled with the config.js variable "disableUserPreferences".

showWatermarksManager()

Toggle the display of the Watermarks dialog. This dialog allows users to add or edit watermarks on the current document.

splitScreen(id, splitDirectionopt)

Split the VirtualViewer main image pane into two, so two documents can be visible at once. This is the same functionality as Document Compare, but does not immediately launch into document comparison.
Parameters:
Name Type Attributes Default Description
id string The ID of the document to open in the second pane.
splitDirection string <optional>
 "horizontal" Either "horizontal" or "vertical". "horizontal" is default, and places the two documents side-by-side.
See:

thumbsWithAnnotations() → {Array.<object>}

Retrieve a list of page thumbnails that contain annotations.
Returns:
A list of jQuery objects representing thumbnails.
Type
Array.<object>

toggleAnnotationVisibility(visibleopt)

With one function call, show or hide all annotations on the current document.
Parameters:
Name Type Attributes Default Description
visible boolean <optional>
 Toggles to the reverse of the current state True to show all annotations, and false to hide.

toggleBothGuidesVisibility()

Toggle the visibility of the both the vertical and horizontal guides. Guide Mode is a viewer mode where two lines appear on the document. These guides can be moved or locked in place to guide the eye to specific locations on the document. To toggle Guide Mode, call toggleCrosshairGuide; this function only controls visibility, not functional viewer mode.
See:

toggleCrosshairGuide()

Toggle Guide Mode. Guide Mode is a viewer mode where two lines appear on the document. These guides can be moved or locked in place to guide the eye to specific locations on the document. Call this function to turn the mode on and off.

toggleHGuide()

Toggle the guides so that only the horizontal guide is active. If the horizontal guide is active, toggle the horizontal guide's visibility.
See:

toggleHGuideVisibility()

Toggle the visibility of only the horizontal guide.
See:

toggleImageInfo()

Toggle the display of the Image Info dialog.

toggleLayerManager()

Toggle the display of the Layer Manager dialog. Annotations are stored on layer objects, and the Layer Manager allows some manipulation of those layers. The dialog also displays information and visibility of .DWG image layers if a .DWG document is open.

toggleMagnifier()

Toggle the magnifier on and off. The magnifier is a small object that overlays the document and magnifies a portion of the image underneath it.

toggleSelectTextMode()

Toggle the viewer between Select Text and Pan mode. These modes are very similar but Select Text mode can only be used when there is real text underlying the document. If there is, Select Text mode allows the user to select text by clicking and dragging.

toggleSpeechControls()

Launch the Speech Controls bar. This bar allows the user to hear the text of the current document out loud

toggleThumbnailPanel(showopt)

Toggle the display of the thumbnail panel.
Parameters:
Name Type Attributes Description
show boolean <optional>
 If true, show the thumbnail panel. If false, hide the thumbnail panel. If undefined, toggle the thumbnail panel.

toggleVGuide()

Toggle the guides so that only the vertical guide is active. If the vertical guide is active, toggle the vertical guide's visibility.
See:

toggleVGuideVisibility()

Toggle the visibility of the vertical guide.
See:

toggleZoomLock()

API method to toggle zooming both panes vs zooming them individually.

undoAnnotation()

Undo the most recent annotation modification. Creation of annotations and modification to annations will be on the undo stack. Currently, the viewer does not limit the size of the undo stack.
See:

undoSplitScreen()

If the viewer is split into two panes, close the document in the second pane and return to single-screen viewing mode. This will also close Document Compare.

zoomIn(zoomPercentopt)

Zoom in to the next level on the current document. The viewer will not zoom past the maximum zoom percent. Zoom levels can be configured in the config.js variable zoomLevels.
Parameters:
Name Type Attributes Description
zoomPercent number <optional>
 It is optional to provide a specific percentage value for the zoom (eg, 70 for 70% zoom).

zoomOut(zoomPercentopt)

Zoom out to the next level on the current document. Zoom levels can be configured in the config.js variable zoomLevels.
Parameters:
Name Type Attributes Description
zoomPercent number <optional>
 It is optional to provide a specific percentage value for the zoom (eg, 70 for 70% zoom).

zoomRubberband()

Activate zoom rubberband mode, allowing the user to draw a rectangle on the current image. The viewer will zoom in and focus on the rectangle when the user finishes drawing.

zoomToLocation(zoom, x, y)

Zoom to the specified percentage level, and scroll the current document to a specific location.
Parameters:
Name Type Description
zoom number The new zoom percentage, in absolute terms. For instance, 150 for a 150% zoom.
x number The new x position, in the zoomed coordinate space. For instance, if the first page is normally 100px x 100px, after performing a 150% zoom, pass "50" rather than "33" to scroll 1/3 of the way across the page.
y number The new y position, in the zoomed coordinate space as described above.