Class: AnnotationManager

CoreControls. AnnotationManager

Represents an object that manages the Annotations that appear on a Document's pages when displayed in a DocumentViewer.


new AnnotationManager()

You must NOT instantiate this yourself. Access the annotation manager instance as follows:

Examples
// In your app
var viewer = new PDFTron.WebViewer({ ... }, viewerElement);
viewerElement.addEventListener('ready', function() {
  var instance = viewer.getInstance();
  var docViewer = instance.docViewer;
  var annotManager = docViewer.getAnnotationManager();
  // annotManager.someAPI();
});
// In a config file
$(document).on('viewerLoaded', function() {
  var instance = readerControl;
  var docViewer = instance.docViewer;
  var annotManager = docViewer.getAnnotationManager();
  // annotManager.someAPI();
});

Methods


addAnnotation(annotation, imported)

Adds the specified annotation to the managed list of annotations.

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.

imported boolean

Whether the annotation was imported from another source or not.


addAnnotations(annotations, imported)

Adds the specified annotations to the managed list of annotations

Parameters:
Name Type Description
annotations array

An array of annotations.

imported boolean

Whether the annotations were imported from another source or not


applyRedactions( [annotations])

Apply redaction annotations

Parameters:
Name Type Argument Description
annotations Annotations.Annotation | Array.<Annotations.Annotation> <optional>

An array of redaction annotations or a single redaction annotation. If nothing passed, apply all redactions. If the redaction annotations overlap with other annotations, it calls deleteAnnotations on the other annotations.

Returns:

Promise for when the redactions has been applied. When using WebViewer Server, this promise is resolved to an URL string of the redacted document

Type
promise

canModify(annotation)

Whether or not the current user can modify the annotation.

Parameters:
Name Type Description
annotation object

The annotation to check permissions on.


canModifyContents(annotation)

Whether or not the current user can modify the annotation's contents.

Parameters:
Name Type Description
annotation object

The annotation to check permissions on.


createAnnotationReply(annotation, initialText)

Creates an annotation that replies to the passed in annotation. Annotation replies are sticky note annotations.

Parameters:
Name Type Description
annotation Annotations.Annotation

The annotation to add a reply to

initialText string

The initialText for the annotation, defaults to the empty string

Returns:

The created annotation reply

Type
Annotations.StickyAnnotation

deleteAnnotation(annotation, imported [, force])

Deletes the specified annotation in the managed list of annotations. If an annotation is successfully deleted, the annotationChanged event will be fired with a "delete" action.

Parameters:
Name Type Argument Description
annotation Annotations.Annotation

An instance of Annotation.

imported boolean

Whether the annotation was imported from another source or not

force boolean <optional>

If true then the annotation will be deleted regardless of the user's current permissions


deleteAnnotations(annotation, imported [, force])

Deletes the specified annotations in the managed list of annotations. If an annotation is successfully deleted, the annotationChanged event will be fired with a "delete" action.

Parameters:
Name Type Argument Description
annotation array

An array of annotations

imported boolean

Whether the annotations were imported from another source or not

force boolean <optional>

If true then the annotations will be deleted regardless of the user's current permissions


deregisterAnnotationType(elementName, annotationClass)

Deregisters an annotation class.

Parameters:
Name Type Description
elementName string

the string representing the xml element name of the annotation

annotationClass Annotations.Annotation

the class (constructor) of the annotation

Returns:

true if deregistration was successful

Type
Boolean

deselectAllAnnotations()

Deselects all annotations. If an annotation is successfully deselected then the annotationSelected event will be trigger with a "deselected" action and a null value as the array of annotations parameter. Note: the annotationSelected event has two parameters: an array of annotations and a string value of either "selected" or "deselected"


deselectAnnotation(annotation)

Deselects the specified annotation. If an annotation is successfully selected then the annotationSelected event will be fired with a "selected" action. Note: the annotationSelected event has two parameters: an array of annotations and a string value of either "selected" or "deselected"

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.


disableFreeTextEditing()

Disables the editing of free text annotations directly on the annotation.


drawAnnotations(pageNumber [, overrideCanvas] [, majorRedraw] [, overrideContainer])

Draws all annotations associated with the given page number. Note that the entire annotation canvas for the page will be redrawn.

Parameters:
Name Type Argument Description
pageNumber number

The page number for the page to draw.

overrideCanvas object <optional>

Optionally draw directly to this canvas

majorRedraw bool <optional>

signify that this is a major redraw, so widget-like annotations must be re-rendered as well

overrideContainer <optional>
Returns:

Returns a promise that resolves when all the annotations on the page have been drawn

Type
Promise

drawAnnotationsFromList(annotationList)

Draws all the pages associated with the annotations in the list as long the page is visible.

Parameters:
Name Type Description
annotationList array

List of annotations

Returns:

Returns a promise that resolves when all the annotations in the annotationList have been drawn

Type
Promise

enableRedaction(isEnabled)

A switch for turning on and off redaction tools

Parameters:
Name Type Description
isEnabled boolean

A value for setting if redaction tools are enabled


exportAnnotations(options)

Exports all annotations as an XFDF (XML) string

Parameters:
Name Type Description
options object

Options for the export. Set options.widgets or options.links or options.fields to false to disable exporting of them.

Properties
Name Type Description
annotList array

An array of annotations to only export the XFDF for those particular annotations.

widgets boolean

Whether to export widget information

links boolean

Whether to export links information

fields boolean

Whether to export fields information

Returns:

The XFDF (XML) annotations as a string

Type
string

getAnnotationById(id, annotationList)

Gets an annotation object by the annotation's ID.

Parameters:
Name Type Description
id string

The ID of the annotation.

annotationList Array

Optionally pass your own array of annotations to search in

Returns:

An annotation object.

Type
Annotations.Annotation

getAnnotationByMouseEvent(event)

Gets the annotation by a DOM mouse event. This method can be used to test if a mouse point will hit any annotations on page.

Parameters:
Name Type Description
event type

A DOM mouse event.

Returns:

An annotation object.

Type
Annotations.Annotation

getAnnotationCopy(annotation)

Returns a deep copy of the annotation

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation to be copied.

Returns:

a copy of the annotation, null if annotation cannot be copied

Type
Annotations.Annotation

getAnnotationFromPopup(popup)

Gets the annotation associated with the popup object.

Parameters:
Name Type Description
popup object

The popup object associated with an annotation

Returns:

The annotation that the popup belongs to

Type
Annotations.Annotation

getAnnotationsList()

Gets the list of all annotations managed by the AnnotationManager.

Returns:

An array of Annotations.

Type
Array.<Annotations.Annotation>

getAnnotCommand()

Gets an XML string specifying the added, modified and deleted annotations. Added and modified annotations will have their XFDF representation included while deleted annotations will only include their id.

Returns:

The command string

Type
string

getCurrentUser()

Returns the user name of the current user.

Returns:

The user name of the current user.

Type
string

getDisplayAuthor(annotation)

Annotations may set the author to a unique id which isn't suitable for display in the UI. this function gets the author name of the annotation that should be displayed.

Parameters:
Name Type Description
annotation object

Annotation object

Returns:

The display author name

Type
string

getFieldManager()

Gets the associated field manager.

Returns:
Type
Annotations.Forms.FieldManager

getIsAdminUser()

Returns whether the current user has admin privileges.

Returns:

true if the current user is an admin, false otherwise.

Type
boolean

getReadOnly()

Returns whether the viewer is currently in read-only mode.

Returns:

true if the current viewer is in read-only mode, false otherwise.

Type
boolean

getRegisteredAnnotationTypes()

Gets a map of registered annotations. This can be modified directly, instead of using AnnotationManager#registerAnnotationType and AnnotationManager#deregisterAnnotationType.

Returns:

a JavaScript object containing a key-value map, where the key is the annotation element name and the value is an array of Annotation classes.

Type
object

getRootAnnotation(annotation)

Gets the root annotation that this annotation is replying to. If this annotation is not replying to anything then the root is itself.

Parameters:
Name Type Description
annotation Annotations.Annotation

The annotation from which to find the root annotation in the reply chain

Returns:

The root annotation

Type
Annotations.Annotation

getSelectedAnnotations()

Returns the list of selected annotations.

Returns:

An array of selected annotations.

Type
Array.<Annotations.Annotation>

hasAnnotation(annotation)

Determines if the specified annotation exists in the managed list of annotations.

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.


hideAnnotation(annot)

Hides the specified annotation.

Parameters:
Name Type Description
annot Annotations.Annotation

The annotation to hide


hideAnnotations(annots)

Hides all of the annotations in the list

Parameters:
Name Type Description
annots array

Array of annotations to hide


importAnnotations(xfdfString)

Loads XFDF (XML) annotations into the viewer synchronously.

Parameters:
Name Type Description
xfdfString string

The XFDF (XML) annotations as a string

Returns:

Returns an array of the annotation objects imported

Type
array

importAnnotationsAsync(xfdfString, callback, options)

Loads XFDF annotations into the viewer asynchronously.

Parameters:
Name Type Description
xfdfString string

The XFDF annotations as a string

callback function

The function that is called when the annotations have been imported. the list of annotations that were added is passed to the callback

options object

The options for importing

Properties
Name Type Description
batchSize number

The number of annotations to import in each batch (default 100)

batchDelay number

The amount of time in milliseconds to delay between importing each batch (default 0)


importAnnotCommand(xfdfString)

Updates the viewer with the xfdf changes (add/modify/delete) in the xml string

Parameters:
Name Type Description
xfdfString string

The XML annotation updates as a string

Returns:

The list of annotations that were updated

Type
array

isAnnotationRedactable(annotation)

Check if an annotation is redactable (is a redaction annotation the user can apply). When using Webviewer Server, single redaction aren't allowed, only redact all is allowed

Parameters:
Name Type Description
annotation Annotations.Annotation

An annotation to check if it redactable

Returns:

True if annotation can be redacted (WebViewer is set up correctly for applying), false otherwise

Type
boolean

isAnnotationSelected(annotation)

Returns whether an annotation is currently selected

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.

Returns:

true if annotation is selected, false otherwise

Type
boolean

isApplyRedactionEnabled()

Check if applying redaction is enabled

Returns:

True if applying redactions is enabled, false otherwise

Type
boolean

isCreateRedactionEnabled()

Check if creating redaction is enabled

Returns:

True if creating redactions is enabled, false otherwise

Type
boolean

jumpToAnnotation(annotation)

Jumps to the page of the annotation and if it isn't visible then centers it in the window.

Parameters:
Name Type Description
annotation Annotations.Annotation

The annotation to be jumped to.


pasteCopiedAnnotations()

Pastes the currently copied annotations.


redrawAnnotation(annotation)

Redraws the specified annotation. Note that the entire annotation canvas for the page will be redrawn.

Parameters:
Name Type Description
annotation Annotations.Annotation

The annotation to be redrawn.


registerAnnotationType(elementName, annotationClass)

Registers an annotation class. Annotations that are registered will be serialized and deserialized by the AnnotationManager.

Parameters:
Name Type Description
elementName string

the string representing the xml element name of the annotation

annotationClass Annotations.Annotation

the class (constructor) of the annotation

Returns:

true if registration was successful

Type
Boolean

selectAnnotation(annotation)

Selects the specified annotation. If an annotation is successfully selected then the annotationSelected event will be fired with a "selected" action. Note: the annotationSelected event has two parameters: an array of annotations and a string value of either "selected" or "deselected"

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.


selectAnnotations(annotation)

Selects the specified annotations. If an annotation is successfully selected then the annotationSelected event will be fired with a "selected" action. Note: the annotationSelected event has two parameters: an array of annotations and a string value of either "selected" or "deselected"

Parameters:
Name Type Description
annotation Array.<Annotations.Annotation>

An array of Annotations.


setAnnotationDisplayAuthorMap(mapFunction)

Sets the mapping function used to get the display name for annotation authors and is used when calling getDisplayAuthor.

Parameters:
Name Type Description
mapFunction function

The mapping function to use


setAnnotationStyles(callback)

Set the style for the annotation

Parameters:
Name Type Description
callback

callback function that returns new style object from old style object argument.


setCurrentUser(User)

sets the current user of the viewer.

Parameters:
Name Type Description
User string

the user name of the current user.


setIsAdminUser(isAdminUser)

Sets whether the current user is an admin user.

Parameters:
Name Type Description
isAdminUser boolean

true if the current user is an admin, false otherwise.


setNoteContents(annotation, text)

Sets the value of the note for the specified annotation.

Parameters:
Name Type Description
annotation Annotations.Annotation

The annotation that will have its note updated.

text string

The value to update the note text to.


setPermissionCheckCallback(callback)

Sets the function that should be used to determine if the annotation can be modified or not.

Parameters:
Name Type Description
callback function

The function that should be called. Should return true or false.


setReadOnly(readOnly)

Sets whether the viewer is currently in read-only mode.

Parameters:
Name Type Description
readOnly boolean

true if the viewer is in read-only mode, false otherwise.


setRedrawThrottle(value)

Sets the rate at which the redrawing of annotations is throttled. This can improve annotation rendering on lower quality devices and browsers.

Parameters:
Name Type Description
value int

The throttled rate at which annotations will be redrawn, in milliseconds


setSubmitFormActionCallback(callback)

Sets the function to be called when a submit form action is triggered.

Parameters:
Name Type Description
callback function

The function that should be called. Will be passed the form data.


showAnnotation(annot)

Shows the annotation

Parameters:
Name Type Description
annot Annotations.Annotation

The annotation to show


showAnnotations(annots)

Shows all of the annotations in the list

Parameters:
Name Type Description
annots array

Array of annotations to show


updateAnnotation(annotation)

Redraws the annotations on the same page as the specified annotation if the annotation has been added.

Parameters:
Name Type Description
annotation Annotations.Annotation

An instance of Annotation.


updateCopiedAnnotations()

Copies the currently selected annotations.

Events


addReply

Triggered when a reply has been added to an annotation

Parameters:
Name Type Description
evt object

Event object

annotation object

The annotation that was added

parent object

The annotation that is the direct parent of the first annotation

root object

The annotation that is the root parent of the first annotation (may be the same as parent)


annotationChanged

Triggered when an annotation or annotations have been changed (added, deleted, modified). Attach like annotManager.on('annotationChanged', callback)

Parameters:
Name Type Description
evt object

Event object, this has an imported property that will be true if the annotation change is the result of importing annotations using importAnnotations, importAnnotCommand or if the imported parameter is set to true when calling addAnnotations or deleteAnnotations

annotations array

The annotations that were changed

action string

The action that occurred (add, delete, modify)


annotationDoubleClicked

Triggered after an annotation has been double clicked

Parameters:
Name Type Description
evt object

Event object

annotation object

The annotation that has been double clicked


annotationHidden

Triggered after annotations have been hidden/shown.

Parameters:
Name Type Description
evt object

Event object

annotationList array

List of annotations that were hidden or shown

hidden boolean

Whether the annotations have been hidden or shown


annotationSelected

Triggered after annotation selection has been changed.

Parameters:
Name Type Description
evt object

Event object

annotationList array

List of annotations that have selected or deselected

action string

Either 'selected' or 'deselected'


deleteReply

Triggered when a reply has been deleted from an annotation

Parameters:
Name Type Description
evt object

Event object

annotation object

The annotation that was deleted

root object

The annotation that is the root parent of the first annotation


fieldChanged

Triggered when a field's value has been changed. Attach like annotManager.on('fieldChanged', callback)

Parameters:
Name Type Description
evt object

Event object

field object

The field that was changed

value string

The field's new value


notify

Triggered when there is a notification related to annotations.

Parameters:
Name Type Description
evt object

Event object

type string

The type of notification that has occurred


setNoteText

Triggered when the text should be set on a note

Parameters:
Name Type Description
evt object

Event object

annotation object

The annotation that needs to have its note text updated

root object

The annotation that is the root parent of the first annotation


updateAnnotationPermission

Triggered when permissions for annotations should be updated. This might be when the user changes or readonly is switched to. If no annotation is specified then every annotation should be updated.

Parameters:
Name Type Argument Description
evt object

Event object

annotation object <optional>

The annotation that needs to have its permissions updated