Class CoreControls.AnnotationManager

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

Class Summary
Constructor Attributes	Constructor Name and Description
	CoreControls.AnnotationManager(docViewer) Creates a new instance of AnnotationManager.

Field Summary
Field Attributes	Field Name and Description
	controlPointHitBoxScale The scale of the hit box of the annotation control points.
	controlPointSize The size of annotation control points.

Method Summary
Method Attributes	Method Name and Description
	addAnnotation(annotation, imported) Adds the specified annotation to the managed list of annotations
	addAnnotations(annotations, imported) Adds the specified annotations to the managed list of annotations
	canModify(annotation) Whether or not the current user can modify the annotation.
	createAnnotationReply(annotation, initialText) Creates an annotation that replies to the passed in annotation.
	deleteAnnotation(annotation, imported, force) Deletes the specified annotation in the managed list of annotations.
	deleteAnnotations(annotation, imported, force) Deletes the specified annotations in the managed list of annotations.
	deregisterAnnotationType(elementName, annotationClass) Deregisters an annotation class.
	deselectAllAnnotations() Deselects all annotations.
	deselectAnnotation(annotation) Deselects the specified annotation.
	disableDefaultStickyNotes() Disables the use of the default sticky notes so that a custom visualization can be used.
	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.
	drawAnnotationsFromList(annotationList) Draws all the pages associated with the annotations in the list as long the page is visible.
	exportAnnotations(options) Exports all annotations as an XFDF (XML) string
	filterAnnotations(filterStr) Causes annotations to be filtered based on a filter string on author.
	getAnnotationById(id, annotationList) Gets an annotation object by the annotation's ID.
	getAnnotationByMouseEvent(event) Gets the annotation by a DOM mouse event.
	getAnnotationCopy(annotation) Returns a deep copy of the annotation
	getAnnotationFromPopup(popup) Gets the annotation associated with the popup object.
	getAnnotationsList() Gets the list of all annotations managed by the AnnotationManager.
	getAnnotCommand() Gets an XML string specifying the added, modified and deleted annotations.
	getCurrentUser() Returns the user name of the current user
	getFieldManager() Gets the associated field manager.
	getIsAdminUser() Returns whether the current user has admin privileges
	getMarkupOff() Returns whether the viewer currently has annotations toggled off
	getReadOnly() Returns whether the viewer is currently in read-only mode
	getRegisteredAnnotationTypes() Gets a map of registered annotations.
	getRootAnnotation(annotation) Gets the root annotation that this annotation is replying to.
	getSelectedAnnotations() Returns the list of selected annotations.
	getUseFilter() Returns whether the viewer is using a filter on annotations to be displayed
	hasAnnotation(annotation) Determines if the specified annotation exists in the managed list of annotations
	hideAnnotation(annot) Hides the specified annotation.
	hideAnnotations(annots) Hides all of the annotations in the list
	importAnnotations(xfdfString) Loads XFDF (XML) annotations into the viewer synchronously.
	importAnnotationsAsync(xfdfString, callback) Loads XFDF annotations into the viewer asynchronously.
	importAnnotCommand(xfdfString) Updates the viewer with the xfdf changes (add/modify/delete) in the xml string
	isAnnotationSelected(annotation) Returns whether an annotation is currently selected
	jumpToAnnotation(annotation) Jumps to the page of the annotation and if it isn't visible then centers it in the window.
	pasteCopiedAnnotations() Pastes the currently copied annotations.
	redrawAnnotation(annotation) Redraws the specified annotation.
	registerAnnotationType(elementName, annotationClass) Registers an annotation class.
	selectAnnotation(annotation) Selects the specified annotation.
	selectAnnotations(annotation) Selects the specified annotations.
	setCurrentUser(user) sets the current user of the viewer
	setIsAdminUser(isAdminUser) Sets whether the current user is an admin user
	setMarkupOff(markupOff) Sets whether annotations are toggled off
	setNoteContents(annotation, text) Sets the value of the note for the specified annotation.
	setPermissionCheckCallback(callback) Sets the function that should be used to determine if the annotation can be modified or not.
	setReadOnly(readOnly) Sets whether the viewer is currently in read-only mode
	setSubmitFormActionCallback(callback) Sets the function to be called when a submit form action is triggered.
	setUseFilter(useFilter) Sets whether annotations are to be filtered based on author
	showAnnotation(annot) Shows the annotation
	showAnnotations(annots) Shows all of the annotations in the list
	toggleAnnotations() Toggles annotations on/off.
	updateAnnotation(annotation) /* * Redraws the annotations on the same page as the specified annotation if the annotation has been added.
	updateCopiedAnnotations() Copies the currently selected annotations.

Event Summary
Event Attributes	Event Name and Description
	addReply(evt, annotation, parent, root) Triggered when a reply has been added to an annotation
	annotationChanged(evt, annotations, action) Triggered when an annotation or annotations have been changed (added, deleted, modified).
	annotationDoubleClicked(evt, annotation) Triggered after an annotation has been double clicked
	annotationFiltered(evt, annotationList) Triggered after the annotations have been filtered.
	annotationHidden(evt, annotationList, hidden) Triggered after annotations have been hidden/shown.
	annotationPopupCreated(evt, annotation, popup, comment) Triggered after an annotation's popup has been created.
	annotationPopupDeleted(evt, annotation, popup, comment) Triggered after an annotation's popup has been deleted.
	annotationPopupStateChanged(evt, annotation, popup, isOpen) Triggered after an annotation's popup has been opened or closed.
	annotationSelected(evt, annotationList, action) Triggered after annotation selection has been changed.
	annotationToggled(evt, markupOff, annotationList, useFilter) Triggered after annotations have been toggled on/off.
	deleteReply(evt, annotation, root) Triggered when a reply has been deleted from an annotation
	fieldChanged(evt, field, value) Triggered when a field's value has been changed.
	notify(evt, type) Triggered when there is a notification related to annotations.
	setNoteText(evt, annotation, root) Triggered when the text should be set on a note

Class Detail

CoreControls.AnnotationManager(docViewer)

Creates a new instance of AnnotationManager.

Parameters:
{CoreControls.DocumentViewer} docViewer

Field Detail

{number} controlPointHitBoxScale

The scale of the hit box of the annotation control points. Increase to increase the selectable area.

{number} controlPointSize

The size of annotation control points.

Method Detail

addAnnotation(annotation, imported)

Adds the specified annotation to the managed list of annotations

Parameters:
{Annotations.Annotation} annotation: An instance of Annotation.
{boolean} imported: Whether the annotation was imported from another source or not

addAnnotations(annotations, imported)

Adds the specified annotations to the managed list of annotations

Parameters:
{array} annotations: An array of annotations.
{boolean} imported: Whether the annotations were imported from another source or not

canModify(annotation)

Whether or not the current user can modify the annotation.

Parameters:
{object} annotation: The annotation to check permissions on.

{Annotations.StickyAnnotation} createAnnotationReply(annotation, initialText)

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

Parameters:
{Annotations.Annotation} annotation: The annotation to add a reply to
{string} initialText: The initialText for the annotation, defaults to the empty string

Returns:: {Annotations.StickyAnnotation} The created annotation reply

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:
{Annotations.Annotation} annotation: An instance of Annotation.
{boolean} imported: Whether the annotation was imported from another source or not
{boolean} force 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:
{array} annotation: An array of annotations
{boolean} imported: Whether the annotations were imported from another source or not
{boolean} force Optional: If true then the annotations will be deleted regardless of the user's current permissions

{Boolean} deregisterAnnotationType(elementName, annotationClass)

Deregisters an annotation class.

Parameters:
{string} elementName: the string representing the xml element name of the annotation
{Annotations.Annotation} annotationClass: the class (constructor) of the annotation

Returns:: {Boolean} true if deregistration was successful

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:
{Annotations.Annotation} annotation: An instance of Annotation.

disableDefaultStickyNotes()

Disables the use of the default sticky notes so that a custom visualization can be used.

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:
{number} pageNumber: The page number for the page to draw.
{object} overrideCanvas Optional: Optionally draw directly to this canvas
{bool} majorRedraw Optional: signify that this is a major redraw, so widget-like annotations must be re-rendered as well
overrideContainer

drawAnnotationsFromList(annotationList)

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

Parameters:
{array} annotationList: List of annotations

{string} exportAnnotations(options)

Exports all annotations as an XFDF (XML) string

Parameters:
{object} options: Options for the export. Set options.widgets or options.links to false to disable exporting of them. Set options.annotList to an array of annotations to only export the XFDF for those particular annotations.

Returns:: {string} The XFDF (XML) annotations as a string

filterAnnotations(filterStr)

Causes annotations to be filtered based on a filter string on author. Only annotations by the specified author will get displayed on the document. Note that filtered annotations are not deleted, they are just not visible.

Parameters:
{string} filterStr: an author name

{Annotations.Annotation} getAnnotationById(id, annotationList)

Gets an annotation object by the annotation's ID.

Parameters:
{string} id: The ID of the annotation.
{Array} annotationList: Optionally pass your own array of annotations to search in

Returns:: {Annotations.Annotation} An annotation object.

{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:
{type} event: A DOM mouse event.

Returns:: {Annotations.Annotation} An annotation object.

{Annotations.Annotation} getAnnotationCopy(annotation)

Returns a deep copy of the annotation

Parameters:
{Annotations.Annotation} annotation: An instance of Annotation to be copied.

Returns:: {Annotations.Annotation} a copy of the annotation, null if annotation cannot be copied

{Annotations.Annotation} getAnnotationFromPopup(popup)

Gets the annotation associated with the popup object.

Parameters:
{object} popup: The popup object associated with an annotation

Returns:: {Annotations.Annotation} The annotation that the popup belongs to

{Annotations.Annotation[]} getAnnotationsList()

Gets the list of all annotations managed by the AnnotationManager.

Returns:: {Annotations.Annotation[]} An array of Annotations.

{string} 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:: {string} The command string

{string} getCurrentUser()

Returns the user name of the current user

Returns:: {string} the user name of the current user

{Annotations.Forms.FieldManager} getFieldManager()

Gets the associated field manager.

Returns:: {Annotations.Forms.FieldManager}

{boolean} getIsAdminUser()

Returns whether the current user has admin privileges

Returns:: {boolean} true if the current user is an admin, false otherwise

{boolean} getMarkupOff()

Returns whether the viewer currently has annotations toggled off

Returns:: {boolean} true if annots are currently toggled off, false otherwise

{boolean} getReadOnly()

Returns whether the viewer is currently in read-only mode

Returns:: {boolean} true if the current viewer is in read-only mode, false otherwise

{object} getRegisteredAnnotationTypes()

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

Returns:: {object} 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.

{Annotations.Annotation} 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:
{Annotations.Annotation} annotation: The annotation from which to find the root annotation in the reply chain

Returns:: {Annotations.Annotation} The root annotation

{Annotations.Annotation[]} getSelectedAnnotations()

Returns the list of selected annotations.

Returns:: {Annotations.Annotation[]} An array of selected annotations.

{boolean} getUseFilter()

Returns whether the viewer is using a filter on annotations to be displayed

Returns:: {boolean} true if annots are currently filtered, false otherwise

hasAnnotation(annotation)

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

Parameters:
{Annotations.Annotation} annotation: An instance of Annotation.

hideAnnotation(annot)

Hides the specified annotation.

Parameters:
{Annotations.Annotation} annot: The annotation to hide

hideAnnotations(annots)

Hides all of the annotations in the list

Parameters:
{array} annots: Array of annotations to hide

importAnnotations(xfdfString)

Loads XFDF (XML) annotations into the viewer synchronously.

Parameters:
{string} xfdfString: The XFDF (XML) annotations as a string

importAnnotationsAsync(xfdfString, callback)

Loads XFDF annotations into the viewer asynchronously.

Parameters:
{string} xfdfString: The XFDF annotations as a string
{function} callback: The function that is called when the annotations have been imported. the list of annotations that were added is passed to the callback

{array} importAnnotCommand(xfdfString)

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

Parameters:
{string} xfdfString: The XML annotation updates as a string

Returns:: {array} The list of annotations that were updated

{boolean} isAnnotationSelected(annotation)

Returns whether an annotation is currently selected

Parameters:
{Annotations.Annotation} annotation: An instance of Annotation.

Returns:: {boolean} true if annotation is selected, false otherwise

jumpToAnnotation(annotation)

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

Parameters:
{Annotations.Annotation} 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:
{Annotations.Annotation} annotation: The annotation to be redrawn.

{Boolean} registerAnnotationType(elementName, annotationClass)

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

Parameters:
{string} elementName: the string representing the xml element name of the annotation
{Annotations.Annotation} annotationClass: the class (constructor) of the annotation

Returns:: {Boolean} true if registration was successful

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:
{Annotations.Annotation} 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:
{Annotations.Annotation[]} annotation: An array of Annotations.

setCurrentUser(user)

sets the current user of the viewer

Parameters:
{string} user: the user name of the current user

setIsAdminUser(isAdminUser)

Sets whether the current user is an admin user

Parameters:
{boolean} isAdminUser: true if the current user is an admin, false otherwise

setMarkupOff(markupOff)

Sets whether annotations are toggled off

Parameters:
{boolean} markupOff: true if the annotations are toggled off, false otherwise

setNoteContents(annotation, text)

Sets the value of the note for the specified annotation.

Parameters:
{Annotations.Annotation} annotation: The annotation that will have its note updated
{string} text: 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:
{function} callback: The function that should be called. Should return true or false.

setReadOnly(readOnly)

Sets whether the viewer is currently in read-only mode

Parameters:
{boolean} readOnly: true if the viewer is in read-only mode, false otherwise

setSubmitFormActionCallback(callback)

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

Parameters:
{function} callback: The function that should be called. Will be passed the form data.

setUseFilter(useFilter)

Sets whether annotations are to be filtered based on author

Parameters:
{boolean} useFilter: true if the annotations are to be filtered, false otherwise

showAnnotation(annot)

Shows the annotation

Parameters:
{Annotations.Annotation} annot: The annotation to show

showAnnotations(annots)

Shows all of the annotations in the list

Parameters:
{array} annots: Array of annotations to show

toggleAnnotations()

Toggles annotations on/off. i.e. Show all annotations or hide all annotations.

updateAnnotation(annotation)

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

Parameters:
{Annotations.Annotation} annotation: An instance of Annotation.

updateCopiedAnnotations()

Copies the currently selected annotations.

Event Detail

addReply(evt, annotation, parent, root)

Triggered when a reply has been added to an annotation

Parameters:
{object} evt: Event object
{object} annotation: The annotation that was added
{object} parent: The annotation that is the direct parent of the first annotation
{object} root: The annotation that is the root parent of the first annotation (may be the same as parent)

annotationChanged(evt, annotations, action)

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

Parameters:
{object} evt: 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
{array} annotations: The annotations that were changed
{string} action: The action that occurred (add, delete, modify)

annotationDoubleClicked(evt, annotation)

Triggered after an annotation has been double clicked

Parameters:
{object} evt: Event object
{object} annotation: The annotation that has been double clicked

annotationFiltered(evt, annotationList)

Triggered after the annotations have been filtered.

Parameters:
{object} evt: Event object
{array} annotationList: List of all annotations

annotationHidden(evt, annotationList, hidden)

Triggered after annotations have been hidden/shown.

Parameters:
{object} evt: Event object
{array} annotationList: List of annotations that were hidden or shown
{boolean} hidden: Whether the annotations have been hidden or shown

annotationPopupCreated(evt, annotation, popup, comment)

Triggered after an annotation's popup has been created.

Parameters:
{object} evt: Event object
{object} annotation: The annotation that the popup belongs to
{object} popup: The popup element
{object} comment: The comment textarea

annotationPopupDeleted(evt, annotation, popup, comment)

Triggered after an annotation's popup has been deleted.

Parameters:
{object} evt: Event object
{object} annotation: The annotation that the popup belongs to
{object} popup: The popup element
{object} comment: The comment textarea

annotationPopupStateChanged(evt, annotation, popup, isOpen)

Triggered after an annotation's popup has been opened or closed.

Parameters:
{object} evt: Event object
{object} annotation: The annotation that the popup belongs to
{object} popup: The popup element
{boolean} isOpen: Whether the popup is open or not

annotationSelected(evt, annotationList, action)

Triggered after annotation selection has been changed.

Parameters:
{object} evt: Event object
{array} annotationList: List of annotations that have selected or deselected
{string} action: Either 'selected' or 'deselected'

annotationToggled(evt, markupOff, annotationList, useFilter)

Triggered after annotations have been toggled on/off.

Parameters:
{object} evt: Event object
{boolean} markupOff: Whether the annotations are visible or not
{array} annotationList: List of all annotations
{boolean} useFilter: Whether a filter is being used or not

deleteReply(evt, annotation, root)

Triggered when a reply has been deleted from an annotation

Parameters:
{object} evt: Event object
{object} annotation: The annotation that was deleted
{object} root: The annotation that is the root parent of the first annotation

fieldChanged(evt, field, value)

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

Parameters:
{object} evt: Event object
{object} field: The field that was changed
{string} value: The field's new value

notify(evt, type)

Triggered when there is a notification related to annotations.

Parameters:
{object} evt: Event object
{string} type: The type of notification that has occurred

setNoteText(evt, annotation, root)

Triggered when the text should be set on a note

Parameters:
{object} evt: Event object
{object} annotation: The annotation that needs to have its note text updated
{object} root: The annotation that is the root parent of the first annotation

WebViewer HTML5 API Reference v2.2.1.49322

Classes

Class CoreControls.AnnotationManager