PDFJS Express WebViewer

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(docViewer)

Creates a new instance of AnnotationManager.
Parameters:
Name Type Description
docViewer CoreControls.DocumentViewer
Properties:
Name Type Description
controlPointSize number The size of annotation control points.
controlPointHitBoxScale number The scale of the hit box of the annotation control points. Increase to increase the selectable area.

Extends

  • 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] [, isUndoRedo])

Adds the specified annotations to the managed list of annotations
Parameters:
Name Type Argument Description
annotations Array.<Annotations.Annotation> An array of annotations.
imported boolean <optional>
 Whether the annotations were imported from another source or not
isUndoRedo boolean <optional>
 Whether the annotation change was caused by undo/redo 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:
Returns a promise that resolves with an array of redaction info when the redactions have been applied. If using WebViewer server, the promise will resolve with a URL to the redacted document.
Type
Promise.<(Array.<CoreControls.AnnotationManager.RedactionInfo>|string)>

canModify(annotation)

Whether or not the current user can modify the annotation.
Parameters:
Name Type Description
annotation object The annotation to check permissions on.
Returns:
Whether the annotation can be modified or not.
Type
boolean

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.
Returns:
Whether the annotation's contents can be modified or not.
Type
boolean

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] [, isUndoRedo])

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 <optional>
 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
isUndoRedo boolean <optional>
 Whether the annotation change was caused by undo/redo or not

deleteAnnotations(annotation, imported [, force] [, isUndoRedo])

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.<Annotations.Annotation> 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
isUndoRedo boolean <optional>
 Whether the annotation change was caused by undo/redo or not

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.

drawAnnotation(annotation, annotCanvasContext [, pageMatrix] [, options])

Draw an annotation onto a page
Parameters:
Name Type Argument Description
annotation Annotations.Annotation The annotation to draw.
annotCanvasContext CanvasRenderingContext2D Annotation canvas context to draw on
pageMatrix object <optional>
 The page matrix for the page that the annotation is on. When this is null, it'll default to the normal page canvas pageMatrix
options object <optional>
 an options object
Properties
Name Type Argument Description
overridePageCanvas HTMLElement <optional>
 The page canvas that the annotation is being draw on top of
overridePageRotation CoreControls.PageRotation <optional>
 The rotation of the overridePageCanvas being being used. Valid values are CoreControls.PageRotation.e_0, CoreControls.PageRotation.e_90, CoreControls.PageRotation.e_180, CoreControls.PageRotation.e_270.

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

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.<Annotations.Annotation> List of annotations
Returns:
Returns a promise that resolves when all the annotations in the annotationList have been drawn
Type
Promise.<any>

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 Argument Description
options object <optional>
 Options for the export. Set options.widgets or options.links or options.fields to false to disable exporting of them.
Properties
Name Type Argument Description
annotList Array.<Annotations.Annotation> <optional>
 An array of annotations to only export the XFDF for those particular annotations.
widgets boolean <optional>
 Whether to export widget information
links boolean <optional>
 Whether to export links information
fields boolean <optional>
 Whether to export fields information
Returns:
Returns a promise that resolves with the XFDF (XML) annotations as a string
Type
Promise.<string>

exportAnnotCommand()

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:
Returns a promise that resolves to an XFDF command string
Type
Promise.<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 top-most annotation using a DOM mouse event. This method can be used to test if a mouse point will hit any annotations on pages.
Parameters:
Name Type Description
event MouseEvent 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

getAnnotationsByMouseEvent(event)

Gets the annotations underneath the cursor using a DOM mouse event. This method can be used to test if a mouse point will hit annotations on pages.
Parameters:
Name Type Description
event MouseEvent A DOM mouse event.
Returns:
An array of annotation objects.
Type
Array.<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.
Deprecated:
  • in favor of exportAnnotCommand
Returns:
Returns a promise that resolves to an XFDF command string
Type
Promise.<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.<Annotations.Annotation>

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.<Annotations.Annotation> 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.<Annotations.Annotation> Array of annotations to hide

importAnnotations(xfdfString [, options])

Loads XFDF annotations into the viewer
Parameters:
Name Type Argument Description
xfdfString string The XFDF annotations as a string
options object <optional>
 The options for importing
Properties
Name Type Argument Description
batchSize number <optional>
 The number of annotations to import in each batch (default 100)
batchDelay number <optional>
 The amount of time in milliseconds to delay between importing each batch (default 0)
replace Annotations.Annotation | Array.<Annotations.Annotation> <optional>
 The type of existing annotations that will be removed before import starts (default [])
Returns:
Returns a promise that resolves with the annotations have been imported
Type
Promise.<any>

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:
A promise that resolves to the list of annotations that were updated
Type
Promise.<Array.<Annotations.Annotation>>

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.

setAnnotationCanvasTransform(annotCanvasContext, zoom, rotation)

Set the page transform of an annotation canvas
Parameters:
Name Type Description
annotCanvasContext CanvasRenderingContext2D Annotation canvas context to draw on
zoom number The zoom or the scaling of the page canvas
rotation CoreControls.PageRotation The rotation of the page canvas

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. The function is passed the annotation object and should return the display name for the UI.
Example
annotManager.setAnnotationDisplayAuthorMap((annotation) => {
  if (annotation.Id === '1') {
    return 'John';
  } else {
    return 'Guest';
  }
});

setAnnotationStyles(annotation, newStyles)

Set the styles for the annotation
Parameters:
Name Type Description
annotation Annotations.Annotation an annotation of which the styles will be changed.
newStyles object | function if an object is used, it should contain properties of the new styles. If a function is used, the current styles will be passed as its argument and the function should return an object which contains properties of the new styles. Example of valid properties: StrokeColor, TextColor, FillColor, FontSize, Opacity, StrokeThickness, Precision, Scale, OverlayText, Style and Dashes.

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.

setOldStickyNoteRenderingDate(date)

Changes the sticky note rendering to the old implementation when the sticky note has been created before the specified date.
Parameters:
Name Type Description
date number The date timestamp to use

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 number 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.<Annotations.Annotation> Array of annotations to show

ungroupAnnotations(annotations)

Ungroups an array of annotations
Parameters:
Name Type Description
annotations Array.<Annotations.Annotation> 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.

updateAnnotationState(annotation, state, stateModel, message)

Updates the annotation state. This is done by creating an annotation that replies to the passed in annotation.
Parameters:
Name Type Description
annotation Annotations.Annotation The annotation to add a reply to
state string Annotations may have an author-specific state associated with them. Valid states are for Review stateModel: Accepted, Rejected, Cancelled, Completed, None. Default is None. Valid states are for Marked stateModel: Marked and Unmarked. Default is Unmarked.
stateModel string Gets or sets the stateModel of the annotation. stateModel has two statemodels: Marked, Review. Default is Review.
message string Message to be set when the state is updated.
Returns:
The created annotation reply
Type
Annotations.StickyAnnotation

updateCopiedAnnotations()

Copies the currently selected annotations.

Type Definitions

RedactionInfo

Type:
  • object
Properties:
Name Type Description
pageNumber number The page number of the redaction
rect Annotations.Rect A rect containing the bounding box of the redaction

Events

addReply

Triggered when a reply has been added to an annotation
Parameters:
Name Type Description
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
annotations Array.<Annotations.Annotation> The annotations that were changed
action string The action that occurred (add, delete, modify)
options object An object that 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

annotationDoubleClicked

Triggered after an annotation has been double clicked
Parameters:
Name Type Description
annotation object The annotation that has been double clicked

annotationHidden

Triggered after annotations have been hidden/shown.
Parameters:
Name Type Description
annotationList Array.<Annotations.Annotation> List of annotations that were hidden or shown
hidden boolean Whether the annotations have been hidden or shown

annotationsDrawn

Triggered after annotations have been drawn for a page
Parameters:
Name Type Description
pageNumber object The page number of all the annotations that were just drawn

annotationSelected

Triggered after annotation selection has been changed.
Parameters:
Name Type Description
annotationList Array.<Annotations.Annotation> 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
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
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
type string The type of notification that has occurred

setNoteText

Triggered when the text should be set on a note
Parameters:
Name Type Description
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
annotation object <optional>
 The annotation that needs to have its permissions updated