# 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

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

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

#### 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']);

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

#### Search results