PDFTron WebViewer

Class: Annotation

Annotations. Annotation

Represents an annotation.

new Annotation()

The base class for all annotations
Properties:
Name Type Description
Author string The author of the annotation.
CustomData object Gets or sets custom data on the annotation.
DateModified Date Gets or sets the date that the annotation was last modified.
elementName string Gets or sets the name of the annotation element in XFDF.
selectionModel Annotations.SelectionModel Gets or sets a selection model for how an annotation gets selected
Height number Gets or sets the height of the annotation
Hidden boolean Gets or sets whether the annotation is hidden.
Invisible boolean Gets or sets whether the annotation is invisible, only if it is an unknown annotation type. Generally for hiding annotations you should use "Hidden"
Printable boolean Gets or sets whether the annotation should be displayed when printing the page.
ReadOnly boolean Gets or sets whether the annotation is readonly or not. If it's readonly it can't be edited or deleted.
Locked boolean Gets or sets whether the annotation is locked or not. If it's locked it can't be edited or deleted, but the note can be edited.
LockedContents boolean Gets or sets whether the annotation contents are locked or not. If the contents are locked then note can't be edited but the annotation can be edited or deleted.
Id string A unique identifier for the annotation. Corresponds to the name attribute in XFDF.
IsAdded boolean Gets or sets whether the annotation has been added since the last time the AnnotCommand was retrieved.
IsDeleted boolean Gets or sets whether the annotation has been deleted since the last time the AnnotCommand was retrieved.
IsModified boolean Gets or sets whether the annotation has been modified since the last time the AnnotCommand was retrieved.
Listable boolean Gets or sets whether the annotation should be listed in annotation lists. If set to true the annotation also will not be selectable.
NoMove boolean Gets or sets whether or not the annotation can be moved
NoResize boolean Gets or sets if this annotation can be resized by the user.
NoRotate boolean Gets or sets if this annotation can be rotated.
NoDelete boolean Gets or sets if this annotation can be deleted.
NoZoom boolean Gets or sets if this annotation scales with the page.
NoView boolean Gets or sets whether the annotation is visible on the screen. Differs from Hidden in that it can still be printed if the print flag is set.
ToggleNoView boolean Gets or sets whether the ToggleNoView flag is set on the annotation.
PageNumber number Gets or sets the page number of a document that the annotation appears on.
Subject string Represents the subject of the annotation. Default is the annotation's type.
Width number Gets or sets the width of the annotation
X number Gets or sets the annotation's x-axis position.
Y number Gets or sets the annotation's y-axis position.
Rotation number Gets or sets the annotation's clockwise rotation in degrees. Valid values are 0, 90, 180 and 270. Only applies to Stamp, FreeText and Caret annotations.
RotationControlEnabled boolean Enabled or disables the annotation's rotation control
MaintainAspectRatio boolean Gets or sets if the annotation maintains aspect ratio when being resized.
isClickableOutsideRect boolean Gets or sets whether any parts of the annotation drawn outside of the rect are clickable.
ToolName string The name of the tool that is used to create this annotation.

Methods

addCustomAppearance(doc [, options])

Adds a custom appearance to the annotation so that the annotation appears like the specified PDF page or object in the PDF page. This appearance will be used instead of the default WebViewer drawing of the annotation.
Parameters:
Name Type Argument Description
doc CoreControls.Document the PDF document object.
options object <optional>
 An object that can contain the following optional parameters.
Properties
Name Type Argument Default Description
pageNumber string <optional>
 1 Page number of source document to use for custom appearance.
objnum string <optional>
 The object number from the appearance document.
gennum string <optional>
 The generation number from the appearance document.
transparentBackground string <optional>
 Transparent background, default is true.

adjustRect()

Adjusts the annotation's bounding rectangle to take into account changes to the annotation e.g. stroke thickness, start/end points, etc
Associate a link with annotation. The associated links will be deleted with the annotation. You can associate multiple links with a single annotation.
Parameters:
Name Type Description
linkIds Array.<string> | string The link IDs to associate with the current annotation.

deleteCustomData(key)

Deletes custom data associated with the given key.
Parameters:
Name Type Description
key string The key for which to delete the associated data.

deserialize(element, pageMatrix)

Deserializes the xml element into the annotation
Parameters:
Name Type Description
element Element an xml element representing the annotation
pageMatrix object the page matrix used to convert PDF coordinates to XOD coordinates.

draw(ctx, pageMatrix)

Draws the annotation on the provide canvas context, relative to the page. The point (0,0) coresponds to the top left corner of the page.
Parameters:
Name Type Description
ctx CanvasRenderingContext2D The canvas context prepared to be drawn on.
pageMatrix object The page matrix for the page that the annotation is on. You can get this object by calling getPageMatrix on the document object.
Returns all associated links with the annotation.
Returns:
Link IDs associated with the annotation.
Type
Array.<string>

getBottom()

Gets the bottommost y position measured in page coordinates.
Deprecated:
  • Since 1.7
Returns:
Type
number

getContents()

Gets the text content for the annotation. Contents may be displayed in an annotation's popup or directly on the page (in the case of FreeTextAnnotation).
Returns:
the text content for the annotation.
Type
string

getCustomData(key)

Returns custom data associated with the given key.
Parameters:
Name Type Description
key string The key for which to retrieve the associated data.
Returns:
value The custom data. If no data is available an empty string is returned.
Type
*

getGroupedChildren()

Gets the list of group children to this annotation.
Returns:
The list of group children
Type
Array.<Annotations.Annotation>

getHeight()

Gets the height of the annotation.
Returns:
the height of the annotation.
Type
number

getInternal()

Returns true if annotation is part of the original document, false otherwise.
Returns:
Whether the annotation is internal to the document or not
Type
boolean

getLeft()

Gets the leftmost x position measured in page coordinates.
Deprecated:
  • Since 1.7
Returns:
Type
number

getPageNumber()

Gets the page number of the annotation. Note: page number starts from 1.
Returns:
The annotation's page number
Type
number

getRect()

Get annotation bounding rectangle
Returns:
Type
CoreControls.Math.Rect

getRectPadding()

Gets the padding that will be applied by default on the annotation's rectangle.
Returns:
The amount of padding
Type
number

getReplies()

Gets the list of replies to this annotation.
Returns:
The list of replies
Type
Array.<Annotations.Annotation>

getRichTextStyle()

Gets the rich text style of the annotation.
Returns:
the current rich text style
Type
Annotations.Annotation.RichTextStyle

getRight()

Gets the rightmost x position measured in page coordinates.
Deprecated:
  • Since 1.7
Returns:
Type
number

getStatus()

Gets the status of the annotation, and returns an empty string if no status set.
Returns:
The last status update.
Type
string

getTop()

Gets the topmost y position measured in page coordinates.
Deprecated:
  • Since 1.7
Returns:
Type
number

getWidth()

Gets the width of the annotation.
Returns:
the width of the annotation.
Type
number

getX()

Gets the x position measured in page coordinates of an annotation.
Returns:
the x position
Type
number

getY()

Gets the y position measured in page coordinates.
Returns:
Type
number

hasRotationControlEnabled()

Returns true if the rotation control is enabled for the annotation and false otherwise.
Returns:
Type
boolean

isGrouped()

Gets whether the annotation is a child of a group
Returns:
Returns true if the annotation is a child of a group, false otherwise.
Type
boolean

isPrintVisible()

Whether the annotation is visible on the document or not **when printed**. If Hidden or if the annotation is a reply to another annotation then it won't be visible.
Returns:
Whether the annotation is visible on the document or not when printed
Type
boolean

isReply()

Gets whether the annotation is a reply to another annotation.
Returns:
Returns true if it does reply to another annotation, false otherwise.
Type
boolean

isVisible()

Whether the annotation is visible on the document or not **when viewing**. If the Hidden or NoView flags are set, or if the annotation is a reply to another annotation then it won't be visible.
Returns:
Whether the annotation is visible on the document or not when viewing
Type
boolean

removeCustomAppearance()

Removes the custom appearance of the annotation.

resize(rect)

Resize the annotation based on a new given CoreControls.Math.Rect. Use this method instead of setRect when internal properties (other than x, y, width and height) need to be modified on move/resize.
Parameters:
Name Type Description
rect CoreControls.Math.Rect the new bounding rectangle

resourcesLoaded()

Resolves when all required resources have finished loading. Currently only applicable to stamp annotations that use images.
Returns:
A promise that resolves when the resources have finished loading
Type
Promise.<any>

serialize(element, pageMatrix)

Serialize the annotation to an xml element
Parameters:
Name Type Description
element Element an xml element representing the annotation
pageMatrix object the page matrix used to convert XOD coordinates to PDF coordinates.
Returns:
the resulting xml element representing the annotation
Type
Element

setContents(value)

Set the text content for the annotation. Note that this will not refresh the text in the UI.
Parameters:
Name Type Description
value string the text content to be set

setCustomData(key, value)

Sets the custom data associated with the specified key.
Parameters:
Name Type Description
key string The key under which to store this custom data. Data will automatically be saved in the exported XFDF and merged into the PDF when downloading.
value * The custom data to store

setHeight(value)

Sets the height of the annotation.
Parameters:
Name Type Description
value number the height of the annotation.

setModified( [keepAppearance])

Flags the annotation as modified if it has been before the last call to exportAnnotCommand Removes the annotation's appearance if no parameter is passed Should be called if changing a custom property on the annotation that is used for serialization Otherwise the annotation will serialize the original deserialized value
Parameters:
Name Type Argument Description
keepAppearance boolean <optional>
 If true then the annotation's appearance will be maintained

setPageNumber(value)

Sets the page number of the annotation. Note: page numbers start from 1.
Parameters:
Name Type Description
value number the page number to be set

setRect(rect)

Sets the size and location of the annotation's bounding rectangle. Use this method instead of resize when only the x, y, width and height needs to be modified. Beware: this method ignores coordinates if they are the wrong way around. (It hasn't been fixed for reasons of maintaining backward compatibility. use setRectWithNormalization instead if you want it to reverse the wrong-way-round coordinates instead of ignoring them.)
Parameters:
Name Type Description
rect CoreControls.Math.Rect the new bounding rectangle

setRectWithNormalization(rect)

Sets the size and location of the annotation's bounding rectangle. Use this method instead of resize when only the x, y, width and height needs to be modified. Use setRectWithNormalization instead of setRect if you want to reverse any wrong-way-round coordinates instead of ignoring them.
Parameters:
Name Type Description
rect CoreControls.Math.Rect the new bounding rectangle

setRichTextStyle(richTextStyle)

Sets the rich text style of the annotation.
Parameters:
Name Type Description
richTextStyle Annotations.Annotation.RichTextStyle The new rich text style of the annotation

setRotationControlEnabled(rotationControlEnabled)

Enables or disables the rotation control for the annotation
Parameters:
Name Type Description
rotationControlEnabled boolean true if the rotation control should be enabled

setWidth(value)

Sets the width of the annotation.
Parameters:
Name Type Description
value number the width of the annotation.

setX(value)

Sets the x position measured in page coordinates of an annotation.
Parameters:
Name Type Description
value number the x position

setY(value)

Sets the y position measured in page coordinates.
Parameters:
Name Type Description
value number the y position
Removes all associated links with the annotation. Doesn't remove the underlying links.

Type Definitions

RichTextCSSStyle

Type:
  • Object
Properties:
Name Type Argument Description
'font-style' 'normal' | 'italic' <optional>
'font-weight' 'normal' | 'bold' <optional>
'text-decoration' 'word' | 'line-through' | 'underline' | string <optional>
 text-decoration: 'word' is equivalent to text-decoration: 'underline'. Values of text-decorations can also be joined by a space. For example, text-decoration: 'word line-through'
color string <optional>
 color in RGB hex format

RichTextStyle

an object that maps between a text style location(character index) to css styles.
Type:
Example
{
  0: {
    'font-weight': 'bold',
    'color': '#ff0000',
  },
  10: {
    'font-style': 'italic'
    'font-weight': 'bold',
    'color': '#0000ff',
  },
  12: {
    'font-decoration': 'underline',
  }
}

this object means that the first 9 characters are bold and red, the following 2 characters are italic, bold, and blue, and the rest of characters have underline.