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.

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.
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.

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".

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

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.

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.

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.

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
page number The new current page.

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.

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.

pageLoaded(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.

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.

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.

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.

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:

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.

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.

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 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
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.