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