PDFTron WebViewer HTML5 Class: AnnotationManager

new AnnotationManager()

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

Examples

// 5.1 and after
WebViewer(...)
  .then(function(instance) {
    var annotManager = instance.annotManager;
    // annotManager.someAPI();
  });

// 4.0 ~ 5.0
var viewerElement = document.getElementById('viewer');
var viewer = new PDFTron.WebViewer(...);

viewerElement.addEventListener('ready', function() {
  var instance = viewer.getInstance();
  var docViewer = instance.docViewer;
  var annotManager = docViewer.getAnnotationManager();
  // annotManager.someAPI();
});

Extends

utils.eventHandler

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

getGroupAnnotations()

Gets all the annotations that are grouped with the passed in annotation, including said annotation.

Returns:

Gets all the annotations that are grouped with the passed in annotation, including said annotation.

Type: array

getIsAdminUser()

Returns whether the current user has admin privileges.

Returns:

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

Type: boolean

getNumberOfGroups()

Gets the number of annotations in the current selection

Returns:

The number of groups in the current selection. A loose annotation is a group of 1.

Type: number

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>

groupAnnotations(primaryAnnotation, annotations)

Groups an array of annotations

Parameters:

Name	Type	Description
`primaryAnnotation`	number	The primary annotation for this group.
`annotations`	array	The array of annotations to group.

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.

off(eventName [, handler])

Remove an event handler

Parameters:

Name	Type	Argument	Description
`eventName`	string		The name of the event to remove the handler for
`handler`	function	<optional>	The handler associated with this event to be removed

Inherited From:

utils.eventHandler#off

Returns:

Returns the object that 'off' is being called on.

Type: object

on(eventName, handler)

Add an event handler

Parameters:

Name	Type	Description
`eventName`	string	The name of the event to listen to
`handler`	function	The function to be called when the event is triggered

Inherited From:

utils.eventHandler#on

Returns:

Returns the object that 'on' is being called on.

Type: object

one(eventName, handler)

Add an event handler that will be removed automatically after being handled the first time

Parameters:

Name	Type	Description
`eventName`	string	The name of the event to listen to
`handler`	function	The function to be called when the event is triggered

Inherited From:

utils.eventHandler#one

Returns:

Returns the object that 'one' is being called on.

Type: object

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

trigger(eventName, eventParams)

Trigger an event

Parameters:

Name	Type	Description
`eventName`	string	The name of the event to trigger
`eventParams`	array	Parameters associated with the event

Inherited From:

utils.eventHandler#trigger

Returns:

Returns the object that 'trigger' is being called on.

Type: object

Example

annotManager.trigger('annotationChanged', [[annotation], 'modify']);

ungroupAnnotations(annotations)

Ungroups an array of annotations

Parameters:

Name	Type	Description
`annotations`	array	The array of annotations to ungroup.

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