Namespace: Callbacks

Callbacks

Supported callbacks are defined here. Callbacks should be set through VirtualViewer#setCallback, by passing the name of the callback and a handler function that will take the arguments described below.

Members

(static) onFinishedMarkingDocumentThumbnail

This callback function is called when addDocumentViewedIndicator has successfully marked a document.

(static) onFinishedRemoveMarkingDocumentThumbnail

This callback function is called when addDocumentViewedIndicator has successfully removed the mark on a document.

(static) onSplitScreenComplete

This callback function is called when screen split is complete.

(static) onWindowResize

This callback function is called when the window of the viewer is resized.

Type Definitions

afterTabClosed(args)

This callback function is called after a tab closes successfully. It will not fire if there is an error while closing the tab, or if the user initiates closing the tab and cancels.
Parameters:
Name Type Description
args object
Properties
Name Type Description
closedDocumentId string The ID of the document whose tab has just been closed.

annotationChanged(args)

This callback function is called whenever the user modifies an annotation; this will fire whenever VirtualViewer itself judges that an annotation has been changed and the asterisk appears in the tab name. Note that this callback will be called quite often.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document, whose annotations have been modified.
annotationLayerId string The ID of the layer that holds the modified annotation.
annotationId string The ID of the modified annotation.
type string The type of the annotation that has been changed.
modifyDate string A timestamp recording when the annotation was changed.

annotationCreation(args)

This callback function is called when the user creates an annotation.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of the annotation that was created. For instance, "Line" or "Arrow".
documentId string The ID of the document where the annotation was created.
annotationLayerId string The name of the annotation's layer.
annotationId string The current ID of the newly-created annotation.
createDate string A string representation of when the annotation was created.

annotationDeletion(args)

This callback function is called when the user deletes an annotation.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of annotation that was deleted. For instance, "Line" or "Arrow".
documentId string The ID of the document whose annotation was deleted.
annotationLayerId string The name of the annotation's layer.
annotationId string The current ID of the deleted annotation.

annotationLoadCompleted(args)

This callback function is called when the annotations for a document have been successfully loaded.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose annotations have just been loaded.
paneIndex string The current pane index for the document.

annotationLoadError(args)

This callback function is called when the annotations for a document have failed to load, with an error.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose annotations failed to load.
paneIndex string The current pane index for the document.
statusText string The status text from the annotation request.
exceptionMessage string An exception message or reason for the error, as given by the server.

annotationSelection(args)

This callback function is called when the user selects an annotation.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document, whose annotation has been selected.
annotationLayerId string The ID of the layer that holds the selected annotation.
annotationId string The ID of the selected annotation.
type string The type of the selected annotation.

brightnessAdjustBegin(args)

This callback function is called when the brightness of a page is set. The completion of this action is noted by the callback imageManipulation. Note that this callback may be called multiple times as a user adjusts a slider in Picture Controls, and again if the user cancels out of Picture Controls, to reverse the adjustments back to default.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose page will be adjusted.
page number The page number of the adjusted page.
currentBrightness number The current brightness value of the page.
requestedBrightness number The requested brightness value.

canPlay(args)

This callback function is called when media is ready to stream its content. This will be fired by the canplay event, which is called when the browser thinks that the video can play.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
event object The event object that is passed to the canplay media event.
documentId string The ID of the document whose image is loading.

canPlayThrough(args)

This callback function is called when media is ready to stream its content. This will be fired by the canplaythrough event, which is called when the browser thinks that the video can play uninturruped to the end.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
event object The event object that is passed to the canplaythrough media event.
documentId string The ID of the document whose image is loading.

contrastAdjustBegin(args)

This callback function is called when the contrast of a page is set. The completion of this action is noted by the callback imageManipulation. Note that this callback may be called multiple times as a user adjusts a slider in Picture Controls, and again if the user cancels out of Picture Controls, to reverse the adjustments back to default.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose page will be adjusted.
page number The page number of the adjusted page.
currentContrast number The current contrast value of the page.
requestedContrast number The requested contrast value.

cropDocument(args)

This callback function is called when a user crops a page successfully.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document.
page number The 0-based index of the page to be cropped.

cropDocumentBegin(args)

This callback function is called when a user begins drawing a crop rectangle on the document.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document.
page number The 0-based index of the page to be cropped.

cropDocumentError(args)

This callback function is called if the crop document action encounters an error.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document.
page number The 0-based index of the page to be cropped.
exceptionMessage string A brief description of the error.

disablePageManipulationContextMenuOptions(args) → {boolean}

This is one of the few VirtualViewer callbacks that can return a value and affect viewer operation. It is called just before the select text context menu shows, and may disable that menu. This menu may contain options to cut, copy or paste pages; it also contains shortcuts to select pages and perform other operations on selected pages. This menu will not appear if the config.js value pageManipulations is set to false. Note that this callback does not allow multiple handlers; while other callbacks allow multiple handlers to be set and called, only one handler may be set to this callback.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document whose thumbnails the menu would appear over.
Returns:
A truthy value to disable the menu, and a falsey value to allow the menu to show.
Type
boolean

disableTextContextMenu(args) → {boolean}

This is one of the few VirtualViewer callbacks that can return a value and affect viewer operation. It is called just before the select text context menu shows, and may disable that menu. This menu may contain options to copy or redact text, to perform OCR, or to add highlight annotations. Note that this callback does not allow multiple handlers; while other callbacks allow multiple handlers to be set and called, only one handler may be set to this callback.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document that the menu would appear over.
Returns:
A truthy value to disable the menu, and a falsey value to allow the menu to show.
Type
boolean

emailDocument(args)

This callback function is called when the server has returned successfully from the email document process.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the emailed document.
format string The format that the document was emailed as. This will be "PDF", "TIFF", or "Original".
includeAnnotations string Whether annotations were included in (burned into) the emailed document.
includeRedactions string Whether redactions were included in (burned into) the emailed document.
includeRedactionTags boolean If redactions were included, whether text tags were placed on the redactions.
includeDocumentNotes boolean Whether document notes were included as pages at the end of the document.
includeWatermarks boolean Whether the exported document included watermarks.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages were emailed. Values are "all", "current", and "complex".
pageRangeValue string The pages emailed. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
clientInstanceId string The clientInstanceId sent to the server.
fromAddress string The email address in the 'from' field of the email.
toAddresses string A comma-delimited list of email addresses in the 'to' field of the email.
ccAddresses string A comma-delimited list of email addresses in the 'CC' field of the email.
bccAddresses string A comma-delimited list of email addresses in the 'BCC' field of the email.
subject string The subject line of the email.
emailBody string The body text of the email, if any.

emailDocumentBegin(args)

This callback function is called when the Email Document process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be emailed.
format string The format that the document will be emailed as. This will be "PDF", "TIFF", or "Original".
includeAnnotations string Whether annotations will be included in (burned into) the emailed document.
includeRedactions string Whether redactions will be included in (burned into) the emailed document.
includeRedactionTags boolean If redactions are included, whether text tags will be placed on the redactions.
includeDocumentNotes boolean Whether document notes will be included as pages at the end of the document.
includeWatermarks boolean Whether the exported document will include watermarks.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages will be emailed. Values are "all", "current", and "complex".
pageRangeValue string The pages to email. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
clientInstanceId string The clientInstanceId to be sent to the server.
fromAddress string The email address in the 'from' field of the email.
toAddresses string A comma-delimited list of email addresses in the 'to' field of the email.
ccAddresses string A comma-delimited list of email addresses in the 'CC' field of the email.
bccAddresses string A comma-delimited list of email addresses in the 'BCC' field of the email.
subject string The subject line of the email.
emailBody string The body text of the email, if any.

emailDocumentError(args)

This callback function is called when the server has encountered an error in the email document process.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the emailed document.
format string The format that the document was emailed as. This will be "PDF", "TIFF", or "Original".
includeAnnotations string Whether annotations were included in (burned into) the emailed document.
includeRedactions string Whether redactions were included in (burned into) the emailed document.
includeRedactionTags boolean If redactions were included, whether text tags were placed on the redactions.
includeDocumentNotes boolean Whether document notes were included as pages at the end of the document.
includeWatermarks boolean Whether the exported document included watermarks.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages were emailed. Values are "all", "current", and "complex".
pageRangeValue string The pages emailed. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
clientInstanceId string The clientInstanceId sent to the server.
fromAddress string The email address in the 'from' field of the email.
toAddresses string A comma-delimited list of email addresses in the 'to' field of the email.
ccAddresses string A comma-delimited list of email addresses in the 'CC' field of the email.
bccAddresses string A comma-delimited list of email addresses in the 'BCC' field of the email.
subject string The subject line of the email.
emailBody string The body text of the email, if any.
exceptionMessage string An error message provided by the VirtualViewer server.
statusText string Status text from the response to the email request.

exportDocumentBegin(args)

This callback function is called when the Export Document process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be exported.
format string The format that the document will be exported as. This will be "PDF", "TIFF", or "Original".
includeAnnotations string Whether annotations will be included in (burned into) the exported document.
includeRedactions string Whether redactions will be included in (burned into) the exported document.
includeRedactionTags boolean If redactions are included, whether text tags will be placed on the redactions.
includeDocumentNotes boolean Whether document notes will be included as pages at the end of the document.
includeWatermarks boolean Whether the exported document will include watermarks.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages will be exported. Values are "all", "current", and "complex".
pageRangeValue string The pages to export. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
filename string The preferred filename for the exported document.
clientInstanceId string The clientInstanceId to be sent to the server.

exportDocumentError(args)

This callback function is called when the Export Document process has failed. Note that VirtualViewer sends the exported to the browser as an attachment, and browsers do not fire any events when an attachment is successfully loaded--so VirtualViewer cannot provide an exportDocument success callback.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be exported.
format string The format that the document was exported as. This will be "PDF", "TIFF", or "Original".
includeAnnotations string Whether annotations were included in (burned into) the exported document.
includeRedactions string Whether redactions were included in (burned into) the exported document.
includeRedactionTags boolean If redactions were included, whether text tags were placed on the redactions.
includeDocumentNotes boolean Whether document notes were included as pages at the end of the document.
includeWatermarks boolean Whether the exported document included watermarks.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages were exported. Values are "all", "current", and "complex".
pageRangeValue string The pages to export. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
filename string The preferred filename for the exported document.
clientInstanceId string The clientInstanceId sent to the server.
exceptionMessage string An exception message, either one returned from the server or one noting a JSON parse error.

exportMultipleDocumentsBegin(args)

This callback function is called when VirtualViewer has compiled a document from an array to be exported--this is called when the process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be exported.
format string The format that the document will be exported as. This will be "PDF", "TIFF".
filename string The preferred filename for the exported document.
clientInstanceId string The clientInstanceId to be sent to the server.

exportMultipleDocumentsError(args)

This callback function is called when the multiple-document export process has failed. Note that VirtualViewer sends the exported to the browser as an attachment, and browsers do not fire any events when an attachment is successfully loaded--so VirtualViewer cannot provide a success callback.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentIds array The IDs of all the documents to be compiled together and exported.
format string The format that the documents were exported as. This will be "PDF", "TIFF", or "Original".
filename string The preferred filename for the exported document.
clientInstanceId string The clientInstanceId sent to the server.
exceptionMessage string An exception message, either one returned from the server or one noting a JSON parse error.

fitDocument(args)

This callback function is called when a Fit To action (Fit to Width, Fit to Height, or Fit to Window) is complete. This may be called before the document repaints and the user sees the results. It may be called twice, once for each document, if the viewer is in Document Compare mode and zoom is locked between the two documents.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.

fitDocumentBegin(args)

This callback function is called when a Fit To action is initiated and validated--Fit to Width, Fit to Height, or Fit to Window.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.
newFitMode vvDefines.zoomModes The requested fit mode. This value is an enum, vvDefines.zoomModes
See:

gammaAdjustBegin(args)

This callback function is called when the gamma value of a page is set. The completion of this action is noted by the callback imageManipulation. Note that this callback may be called multiple times as a user adjusts a slider in Picture Controls, and again if the user cancels out of Picture Controls, to reverse the adjustments back to default.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose page will be adjusted.
page number The page number of the adjusted page.
currentGamma number The current gamma value of the page.
requestedGamma number The requested gamma value.

imageLoadCompleted(args)

This callback function is called when an image has completed loading. Loading in VirtualViewer can be a complicated process with several fallbacks for faulty images. This callback is called at the end of the process, when an image is completely loaded and is ready to draw.
Parameters:
Name Type Description
args object
Properties
Name Type Description
val boolean Whether the image was loaded.
documentId string The ID of the document whose image is loading.
page number The 0-based index of the page that was loaded.

imageLoadRequested(args)

This callback function is called when a request for an image fires off to the server. VirtualViewer uses a buffering system to preload images.
Parameters:
Name Type Description
args object
Properties
Name Type Description
val boolean Whether the image was requested.
documentId string The ID of the document whose image is loading.
page number The 0-based index of the page that is being requested. Generally VirtualViewer document will refer to pages and images interchangeably.

imageManipulation(args)

This callback function is called when image manipulation is complete. Image manipulation includes adjustment of brightness, gamma, and contrast values in Picture Controls, and setting image inversion through the invertImage API. This callback covers completion of all of these actions.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose page has been manipulated.
page number The page number of the manipulated page.
gamma number The gamma value of the image.
brightness number The brightness value of the image.
contrast number The contrast value of the image.
invert boolean Whether the image is inverted.

invertImageBegin(args)

This callback function is called when the invertImage action begins. The completion of this action is noted by the callback imageManipulation.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document whose page will be inverted.
page number The page number of the inverted page.
currentImageInverted boolean The current image inversion status. A value of true indicates that the image is inverted.
invertImage boolean The requested image inversion status.

magnifier(args)

This callback function is called when the magnifier is toggled.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the currently active document.
currentPage number The current page of the document.
magnifierActive boolean Whether the magnifier is currently active.

magnifierBegin(args)

This callback function is called before the magnifier is toggled.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the currently active document.
currentPage number The current page of the document.
magnifierActive boolean Whether the magnifier is currently active.

mediaEnded(args)

This callback function is called when media playback has ended due to reaching the end of the data.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
event object The event object that is passed to the ended media event.
documentId string The ID of the document whose image is loading.

mediaError(args)

This callback function is called when media runs into an error.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
error object The error object that is passed to the error media event.
documentId string The ID of the document whose image is loading.

mediaPause(args)

This callback function is called when media is paused.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
event object The event object that is passed to the pause media event.
documentId string The ID of the document whose image is loading.

mediaPlay(args)

This callback function is called when media is played.
Parameters:
Name Type Description
args object
Properties
Name Type Description
type string The type of media that's being loaded, either "video" or "audio"
event object The event object that is passed to the play media event.
documentId string The ID of the document whose image is loading.

onDocumentLoad(args)

This callback function is called when a document has finished loading. VirtualViewer opens a document in a few stages. First, the document model is loaded from the server, and then images and page information is loaded. This callback will be called after the first step, when the document's basic information has been loaded.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document that has completed loading.
paneIndex string The 0-based index of the pane displaying the loaded document.

onLoadUsername(args)

This callback function is called when User Preferences code has finished loading a username from localforage, or has found that there is no username to be loaded.
Parameters:
Name Type Description
args object
Properties
Name Type Description
loadedUsername string The username that has just been retrieved from localforage. This may not be set if no username was found.
previousUsername string The username that was previously set in the viewer.

onPageLoadAndRendered(args)

This callback is called when a page has been succesfully rendered on the canvas
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document
pageNumber string the page number of the page

onShowSelectTextContextMenu(args)

This callback function is called from the show event of the menu that appears when right-clicking the document. This menu may contain options to copy or redact text, to perform OCR, or to add highlight annotations.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document that the menu appears over.

onThumbLoadAndRendered(args)

This callback is called when a thumbnail image is loaded and rendered.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document
pageNumber string the page number of the thumbnail that has been loaded

overlayImageLoadCompleted(args)

This callback function is called when an image has completed loading for use as a template overlay.
Parameters:
Name Type Description
args object
Properties
Name Type Description
val boolean Whether the image was loaded.
documentId string The ID of the current base document.
overlayDocumentID string The ID of the document that is made transparent and displayed over the base document.
See:

pageChange(args)

This callback function is called when the current page of an open document changes.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document's ID.
page number The new current page.

pageChangeBegin(args)

This callback function is called immediately before the current page of an open document changes.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document's ID.
currentPage number The current page of the document.
newPage number The new page that the viewer is attempting to change to.

pageChangeError(args)

This callback function is called if the viewer encounters an error while attempting to change a document's page.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The current document's ID.
currentPage number The current page of the document.
newPage number The new page that the viewer is attempting to change to.
exceptionMessage string A brief description of the error.

pageCopied(args)

This callback function is called when one or more document pages are copied or cut to the VirtualViewer clipboard. The viewer clipboard is an object stored in browser memory and in localforage, in order to transfer pages between viewer tabs or browser windows. This will be called when the user drag-and-drops pages in a document as well as when they use the right-click menu to copy and paste pages.
Parameters:
Name Type Description
args object
Properties
Name Type Description
pages Array.<number> The 0-based page numbers that were copied.
documentId string The ID of the document whose pages were copied.

pageCountUpdated(args)

With SnowDoc formats, we may load pages before the document is fully loaded; if we do, and therefore if we don't have the correct page count yet, we update the page count as pages are loaded. The loaded page will tell us if there's a next page, and the page count will be updated accordingly.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The document that is currently loading.
paneIndex number The 0-based index of the pane displaying the loading document.
oldPageCount number The page count before the update.
newPageCount number The current page count, after the update.

pageDeleted(args)

This callback function is called when one or more document pages are removed from a document. This could be from manual deletion, from dragging pages around, or from cut and paste.
Parameters:
Name Type Description
args object
Properties
Name Type Description
pages Array.<number> The 0-based page numbers that were deleted from the current document.

pageLoadError(args)

This callback function is called if a page load fails. A page load is the initial server call that retrieves both the image info and image for the page. VirtualViewer will retry the page load call once, so this callback will be called twice if a page completely errors out.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document whose page was loaded.
paneIndex number The 0-based index of the pane displaying the loaded document.
pageNumber number The 0-indexed number of the failed page.
finalTry boolean This will be true if the page failed on the second and final attempt to load.

pageLoaded(args)

This callback function is called whenever a page loads. A page load is the initial server call that retrieves both the image info and image for the page. After the page is loaded, the image may fall out of the internal buffer if the user scrolls past it; if the page image has to be reloaded, only the image will be retrieved, and this callback will not be called. ("imageLoadCompleted" will be called.)
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document whose page was loaded.
displayName string If a new display name was sent with the page, this argument will store it. It will not yet be set in the viewer.
paneIndex number The 0-based index of the pane displaying the loaded document.
loadedPageNumber number The 0-indexed number of the loaded page.
searchableStatusBeforeLoad boolean The document's searchable status--whether the document has machine-parsable text--may change on page load. This sends old value.

pagePasted(args)

This callback function is called when one or more document pages are pasted into a document from the VirtualViewer clipboard. The viewer clipboard is an object stored in browser memory and in localforage, in order to transfer pages between viewer tabs or browser windows. This will be called when the user drag-and-drops pages in a document as well as when they use the right-click menu to cut/copy and paste pages.
Parameters:
Name Type Description
args object
Properties
Name Type Description
pages Array.<number> The 0-based page numbers that were pasted into the current document.

printDocument(args)

This callback function is called when a document prints successfully. Essentially, VirtualViewer's role is to publish the document so the browser can handle printing from that point forward. This callback is called when VirtualViewer's role is complete and the viewer sees the system print dialog.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the printed document.
totalPages number The total pages printed, if available.

printDocumentBegin(args)

This callback function is called when the Print Document process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be printed.
includeAnnotations string Whether annotations will be included in (burned into) the printed document.
includeRedactions string Whether redactions will be included in (burned into) the printed document.
includeRedactionTags boolean If redactions are included, whether text tags will be placed on the redactions.
includeDocumentNotes boolean Whether document notes will be included as pages at the end of the document.
includeWatermarks boolean Whether the printed document will include watermarks.
fitToPage boolean Whether to force image PDFs to letter-sized pages with the image centered.
pageRangeType string A string that, when paired with the param pageRangeValue, represents what pages will be printed. Values are "all", "current", and "complex".
pageRangeValue string The pages to print. For pageRangeType "all", this will be undefined. For "current" and "complex" this will hold a page number or string representing a set of page numbers.
clientInstanceId string The clientInstanceId to be sent to the server.

printDocumentError(args)

This callback function is called when a document encounters an error while printing.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the printed document.
exceptionMessage number A brief description of the error.

printMultipleDocuments(args)

This callback function is called when VirtualViewer has compiled a document from an array to be printed. Essentially, VirtualViewer's role is to publish the document so the browser can handle printing from that point forward. This callback is called when VirtualViewer's role is complete and the viewer sees the system print dialog.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentIds string The set of IDs compiled into the printed document.

printMultipleDocumentsBegin(args)

This callback function is called when VirtualViewer has compiled a document from an array to be printed--this is called when the process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentIds string The set of IDs to be compiled into the printed document.
fitToPage boolean Whether to force image PDFs to letter-sized pages with the image centered.
clientInstanceId string The clientInstanceId to be sent to the server.

printMultipleDocumentsError(args)

This callback function is called when the multiple-document print process has failed.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentIds array The IDs of all the documents to be compiled together and printed.
clientInstanceId string The clientInstanceId sent to the server.
exceptionMessage string An exception message, either one returned from the server or one noting a JSON parse error.

printMultipleDocumentsError(args)

This callback function is called when VirtualViewer has compiled a document from an array to be printed, and the document encounters an error while printing.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentIds string The set of IDs compiled into the printed document.
exceptionMessage number A brief description of the error.

requestDocumentModelError(args)

This callback function is called if an error occurs while loading the document model. This is a very significant error: the viewer's operations depend on having a document model.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document that was attempting to load.
paneIndex number The 0-based index of the pane displaying the errored document.
exceptionMessage string An error message provided by the VirtualViewer server.
statusText string Status text from the response to the document model request.

rotation(args)

This callback function is called when a page is rotated. Pages can be rotated to 0, 90, 180, and 270 degrees. When freshly loaded from the server, a page always starts at 0 degrees rotation, even if it was rotated in a previous VirtualViewer session.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document whose page was rotated.
page number The 0-based index of the page that was rotated.
rotatedTo number The angle, in degrees, that the page was rotated to, compared to its original zero position.
rotatedBy number The angle, in degrees, that the page was rotated by, from its position before rotation.
degrees number The angle of rotation. This angle will match either rotatedTo or rotatedBy.

rotationBegin(args)

This callback function is called before a page is rotated. Pages can be rotated to 0, 90, 180, and 270 degrees. When freshly loaded from the server, a page always starts at 0 degrees rotation, even if it was rotated in a previous VirtualViewer session.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document.
page number The 0-based index of the page to be rotated.
rotationAngle number The current angle, in degrees, of the page to be rotated. If the document is freshly loaded from the server, the angle will be 0, even if the page appears rotated.

rotationError(args)

This callback function is called if page rotation encounters an error.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document.
page number The 0-based index of the page to be rotated.
rotationAngle number The current angle, in degrees, of the page to be rotated. If the document is freshly loaded from the server, the angle will be 0, even if the page appears rotated.
exceptionMessage string A brief description of the error.

saveAnnotationPreferences(args)

This callback function is called when annotation preferences are saved from the User Preferences dialog.
Parameters:
Name Type Description
args object
Properties
Name Type Description
annotationPropertyArray Array.<annotationProperties> The new annotation defaults. This object has keys for each annotation type, and values of annotation defaults.

saveAnnotations(args)

This callback function is called when annotations are saved to the server. It is called identically to the saveDocument callback.
Parameters:
Name Type Description
args object
Properties
Name Type Attributes Description
documentId string The original ID of the document that was saved.
clientInstanceId string The clientInstanceId passed to the server in the save document call.
documentIdToReload string <optional>
 If the content handler has modified the ID of the saved document, it may pass back a "documentIdToReload", and the viewer will reload the saved document with the new ID. Note that for the document to reload, the config.js configuration item reloadDocumentOnSave must be set to true. values of annotation defaults.

saveAnnotationsError(args)

This callback function is called when there is an error while annotations are saved to the server.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document that was saved.
clientInstanceId string The clientInstanceId passed to the server in the save document call.
exceptionMessage string One of the avenues for an error message. A message may be provided here if the server caught the problem during save.
statusText string The other avenue for the error message. This may be HTTP status information, most helpful if the viewer did not catch the problem during save.

saveAsDocument(args)

This callback function is called when a document has finished saving as: specifically, when the server returns a success message from the Save As call. By default, the viewer's Save As callback opens the newly-created document.
Parameters:
Name Type Description
args object
Properties
Name Type Description
oldDocumentId string The original ID of the document that was saved.
newDocumentId string The ID of the new document generated by Save As.
clientInstanceId string The clientInstanceId passed to the server in the Save As call.
See:

saveAsDocumentBegin(args)

This callback function is called when a document when the viewer has validated and initiated the Save As process. It is called before any server calls are made.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The original ID of the document to be saved.
newDocumentId string The ID of the new document to be generated by Save As.
clientInstanceId string The clientInstanceId that will be passed to the server in the Save As call.
See:

saveAsDocumentError(args)

This callback function is called if an error occurs while saving a document, as a way to retrieve more detailed error information than is displayed to the user.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the current document. This is the document that was attempting to Save As.
saveAsDocumentId string The ID of the new document that was supposed to be generated by Save As is provided here.
exceptionMessage string One of the avenues for an error message. A message may be provided here if the server caught the problem during save.
statusText string The other avenue for the error message. This may be HTTP status information, most helpful if the viewer did not catch the problem during save.

saveAudioPreferences(args)

This callback function is called when audio preferences are saved from the User Preferences dialog. These preferences are available in the media tab in the userPreferences dialog.
Parameters:
Name Type Description
args object
Properties
Name Type Description
audioPreferences object A small object containing audio preferences, which are background playback and controls display.

saveCustomStamps(args)

This callback function is called when custom stamp preferences are saved from the User Preferences dialog. These text stamps display in a menu under the annotation button that looks like a "T", and are quick defaults for text annotations. For image stamps, see the method VirtualViewer#createImageStampArray.
Parameters:
Name Type Description
args object
Properties
Name Type Description
stampsPreferences object The list of custom stamps being saved.

saveDocument(args)

This callback function is called when a document has finished saving: specifically, when the server returns a success message from the call to save a document.
Parameters:
Name Type Description
args object
Properties
Name Type Attributes Description
documentId string The original ID of the document that was saved.
clientInstanceId string The clientInstanceId passed to the server in the save document call.
documentIdToReload string <optional>
 If the content handler has modified the ID of the saved document, it may pass back a "documentIdToReload", and the viewer will reload the saved document with the new ID. Note that for the document to reload, the config.js configuration item reloadDocumentOnSave must be set to true.

saveDocumentBegin(args)

This callback function is called when the viewer has validated and initiated the saving process. It is called before any server calls are made.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document to be saved.
clientInstanceId string The clientInstanceId that will be passed to the server in the save document call.

saveDocumentError(args)

This callback function is called if an error occurs while saving a document, as a way to retrieve more detailed error information than is displayed to the user.
Parameters:
Name Type Description
args object
Properties
Name Type Attributes Description
documentId string The ID of the current document. This is the document that was attempting to save.
saveAsDocumentId string <optional>
 If a new document ID was provided, as in a Save As action, that ID is provided here.
exceptionMessage string One of the avenues for an error message. A message may be provided here if the server caught the problem during save.
statusText string The other avenue for the error message. This may be HTTP status information, most helpful if the viewer did not catch the problem during save.

saveNoteTemplates(args)

This callback function is called when document note templates are saved from the User Preferences dialog. These templates are quick options accessible from the Document Notes tab in the thumbnail pane.
Parameters:
Name Type Description
args object
Properties
Name Type Description
notesTemplate Array.<object> The list of note templates being saved.

saveTabPreferences(args)

This callback function is called when tab preferences are saved from the User Preferences dialog. The tab preference sets which thumbnail-pane tab is opened by default.
Parameters:
Name Type Description
args object
Properties
Name Type Description
defaultTab number The new default thumbnail tab. Thumbnail tab enumeration is described in vvDefines.js.

saveToolbarPreferences(args)

This callback function is called when toolbar preferences are saved from the User Preferences dialog. Toolbar preferences describe which buttons are visible to the user. If a toolbar button is hidden, it is still present. To fully remove a toolbar button, remove its entry from toolbar-config.js or disable its associated feature.
Parameters:
Name Type Description
args object
Properties
Name Type Description
imageControlToolbar Array.<object> An array of toolbar options, containing the button's name and whether it is visible. This array is for the top toolbar.
annotationToolbar Array.<object> An array of toolbar options, containing the button's name and whether it is visible. This array is for the toolbar on the left of the screen.

saveUserPreferences(args)

This callback function is called when all of the user preferences are saved. This includes the save button, and it passes along the JSON blob to this so people can take that data and use it however they desire.
Parameters:
Name Type Description
args object
Properties
Name Type Description
userPreferences object The JSON blob that is made from exportUserPreferences.

saveUsername(args)

This callback function is called when a username is saved. The username may be modified in the User Preferences dialog. VirtualViewer saves the username, like all user preferences, locally in the browser's storage via localforage.
Parameters:
Name Type Description
args object
Properties
Name Type Description
username string The username being saved.

saveVideoPreferences(args)

This callback function is called when video preferences are saved from the User Preferences dialog. These preferences are available in the media tab in the userPreferences dialog.
Parameters:
Name Type Description
args object
Properties
Name Type Description
videoPreferences object A small object containing video preferences, like autoplay, whether the video should start muted, whether controls should show, and whether the video should stretch or keep its natural size.

saveZoomPreferences(args)

This callback function is called when zoom preferences are saved from the User Preferences dialog. Zoom preferences describe how much a document will be zoomed when it is first opened.
Parameters:
Name Type Description
args object
Properties
Name Type Description
zoomPreferences object A small object containing zoom preferences.

sendDocument()

This callback function is called when the server has successfully sent a document.
See:

switchBetweenTabs(args)

This callback function is called when the user switches tabs. It is more specific than the callback "switchToTab", as this is called when there is both a "to" and a "from" tab.
Parameters:
Name Type Description
args object
Properties
Name Type Description
currentTabDocumentId string This is the ID of the "to" document. The user has switched to the tab containing this document.
previousTabDocumentId string This is the ID of the document that was previously open in a tab.

switchToTab(args)

This callback function is called when the viewer displays a new tab. This could be upon opening a new document, switching between document tabs, or closing a document. The callback "switchBetweenTabs" is called more specifically for switching between document tabs.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the document currently being displayed.

textSelect(args)

This callback function is called when the user has just finished selecting text by clicking and dragging a highlight on the image. This is only possible with document formats that have underlying, computer-readable text, like many PDFs and Office formats.
Parameters:
Name Type Description
args object
Properties
Name Type Description
text string The text that the user has selected, as a string without positional information.

uploadDocument(args)

This callback function is called when the server has successfully uploaded a document.
Parameters:
Name Type Description
args object
Properties
Name Type Description
uploadedDocumentId string The ID of the document that has completed upload.
clientInstanceId string The clientInstanceId passed to the server in the upload call.

uploadDocumentBegin(args)

This callback function is called when the Upload Document process has been validated and initiated on the client. This will be called before any server calls.
Parameters:
Name Type Description
args object
Properties
Name Type Description
filename string The file name of the document that will be uploaded.
clientInstanceId string The clientInstanceId that will be passed to the server in the upload call.

uploadDocumentError(args)

This callback function is called when the server has encountered an error while attempting to upload a document.
Parameters:
Name Type Description
args object
Properties
Name Type Description
filename string The file name of the document that failed to upload.
clientInstanceId string The clientInstanceId passed to the server in the upload call.
exceptionMessage string An error message provided by the VirtualViewer server.
statusText string Status text from the response to the upload request.

zoomDocument(args)

This callback function is called when a zoom action is completed.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.

zoomDocumentBegin(args)

This callback function is called when a zoom action is initiated and validated.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.'
newZoom number The proposed new percent zoom of the document.

zoomRubberband(args)

This callback function is called when a user finishes drawing the box for Rubberband Zoom, and the document is correctly zoomed and scrolled.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.

zoomRubberbandBegin(args)

This callback function is called when a user begins drawing a rubberband zoom box on the document.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.

zoomRubberbandError(args)

This callback function is called when Rubberband Zoom encounters an error.
Parameters:
Name Type Description
args object
Properties
Name Type Description
documentId string The ID of the zoomed document.
currentZoom number The current percent zoom of the document--eg 50 for a 50% zoom.
exceptionMessage string A brief description of the error.