Apryse WebViewer Class: Annotation

Class: Annotation

Core .Annotations. Annotation

Represents an annotation.

new Annotation( [initializer])

The base class for all annotations

Parameters:

Name	Type	Argument	Description
`initializer`	object	<optional>	A map of values to auto-initialize certain properties of the annotation. You can only initialize properties defined on the annotation under the Members section (unless specified otherwise).

Members

<static> MeasurementDisplayFormats

An object containing the different display formats for measurement annotations.

Properties:

Name	Type	Description
`DECIMAL`	string	Decimal format eg. 12.75
`FRACTION`	string	Decimal format eg. 12 3/4
`ROUND`	string	Decimal format eg. 12.8
`TRUNCATE`	string	Decimal format eg. 12.7

Example

const fractionMeasurementDisplayFormat = Annotations.Annotation.MeasurementDisplayFormats.FRACTION

<static> MeasurementSystems

An object containing the different measurement systems for measurement annotations.

Properties:

Name	Type	Description
`METRIC`	string	The Metric measurement system
`IMPERIAL`	string	The Imperial measurement system
`TYPOGRAPHIC`	string	The Typographic measurement system

Example

const metricMeasurementSystem = Annotations.Annotation.MeasurementSystems.METRIC

<static> MeasurementUnits

An object containing the different display measurement units for measurement annotations.

Properties:

Name	Type	Description
`MM`	string	Millimeter measurement unit
`CM`	string	Centimeter measurement unit
`M`	string	Meter measurement unit
`KM`	string	Kilometer measurement unit
`IN`	string	Inch measurement unit
`FT`	string	Foot measurement unit
`YD`	string	Yard measurement unit
`MI`	string	Mile measurement unit
`PT`	string	Point measurement unit
`DOUBLE_PRIME_IN`	string	Inch" measurement unit
`PRIME_FT`	string	Foot' measurement unit
`FT_IN`	string	Foot and Inch measurement unit

Example

const centimeterMeasurementUnit = Annotations.Annotation.MeasurementUnits.CM

Author

The author of the annotation.

BlendMode

Gets or sets the annotation blend mode.
THIS PROPERTY IS EXPERIMENTAL, NOT CURRENTLY PERSISTED AND ONLY WORKS WITHIN WEBVIEWER Blend mode will not be retained when dragging annotation across pages. You can call annotationManager.disableDraggingAcrossPages() to prevent movement between pages.

Color

Gets or sets the annotation's stroke color.

DateModified

Gets or sets the date that the annotation was last modified.

elementName

Gets or sets the name of the annotation element in XFDF.

This property cannot be initialized through the initializer.

Height

Gets or sets the height of the annotation.

Hidden

Gets or sets whether the annotation is hidden.

Id

A unique identifier for the annotation. Corresponds to the name attribute in XFDF.

InReplyTo

The Id of the annotation that this annotation is replying to or the parent annotation it is grouped with.

Invisible

Gets or sets whether the annotation is invisible, only if it is an unknown annotation type. Generally for hiding annotations you should use "Hidden".

IsAdded

Gets or sets whether the annotation has been added since the last time the AnnotCommand was retrieved.

IsClickableOutsideRect

Gets or sets whether any parts of the annotation drawn outside of the rect are clickable.

IsDeleted

Gets or sets whether the annotation has been deleted since the last time the AnnotCommand was retrieved.

IsModified

Gets or sets whether the annotation has been modified since the last time the AnnotCommand was retrieved.

Listable

Gets or sets whether the annotation should be listed in annotation lists. If set to false the annotation also will not be selectable.

Locked

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

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.

MaintainAspectRatio

Gets or sets if the annotation maintains aspect ratio when being resized.

NoDelete

Gets or sets if this annotation can be deleted.

NoMove

Gets or sets whether or not the annotation can be moved.

NoResize

Gets or sets if this annotation can be resized by the user.

NoRotate

Gets or sets if this annotation rotates with the page.

NoView

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.

NoZoom

Gets or sets if this annotation scales with the page.

PageNumber

Gets or sets the page number of a document that the annotation appears on.

Printable

Gets or sets whether the annotation should be displayed when printing the page.

ReadOnly

Gets or sets whether the annotation is readonly or not. If it's readonly it can't be edited or deleted.

ReplyType

The type of reply.

Rotation

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

Enables or disables the annotation's rotation control.

selectionModel

Gets or sets a selection model constructor for how an annotation gets selected.

Subject

Represents the subject of the annotation. Default is the annotation's type.

ToggleNoView

Gets or sets whether the ToggleNoView flag is set on the annotation.

ToolName

The name of the tool that is used to create this annotation.

Width

Gets or sets the width of the annotation.

X

Gets or sets the annotation's x-axis position.

Y

Gets or sets the annotation's y-axis position.

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 Core.Document the PDF document object.

options

object

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

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.

disableRotationControl()

Disables the rotation control for the annotation

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.

enableRotationControl()

Enables the rotation control for the annotation

getAssociatedNumber()

Gets the number associated with this annotation, if any.

See:

enableAnnotationNumbering

Returns:

The number associated with this annotation. If no number is associated then undefined is returned.

Type: number | undefined

getAttachments()

Gets the attachments of the annotation.

Returns:

Type: Array.<Core.Annotations.Annotation.AnnotationAttachment>

getContentEditAnnotationId()

Returns the Content Annotation Id associated with a FreeText annotation that is used for inline editing, if there is one.

Returns:

Type: string

getContentEditType()

Returns the content edit type, if there is one. Only applicable to content edit placeholder annotations.

Returns:

Type: string

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: string

getGroupedChildren()

Gets the list of group children to this annotation.

Returns:

The list of group children

Type: Array.<Core.Annotations.Annotation>

getHeight()

Gets the height of the annotation.

Returns:

the height of the annotation.

Type: number

getNoZoomReferencePoint()

Gets the x and y zoom reference point for NoZoom annotation.

Returns:

The (x, y) no zoom reference factor.

Type: Core.Math.Point

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: Core.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.<Core.Annotations.Annotation>

getRichTextStyle()

Gets the rich text style of the annotation.

Returns:

the current rich text style

Type: Core.Annotations.Annotation.RichTextStyle

getStatus()

Gets the status of the annotation, and returns an empty string if no status set.

Returns:

The last status update.

Type: string

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

isContentEditPlaceholder()

Returns whether the annotation is a content editing placeholder, which are annotations used as placeholders for content edit boxes when the content editing tool is active

Returns:

Whether the annotation is a content edit placeholder or not

Type: boolean

isFullSignature()

Checks if the annotation is a full signature

Returns:

Returns whether the annotation is a full signature or not

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

isInContentEditFocusMode(contentEditManager)

Checks if a content edit annotation is being edited and has focus.

Parameters:

Name	Type	Description
`contentEditManager`	Core.ContentEditManager	An instance of contentEditManager

Returns:

Returns whether an annotation is on content edit focus mode or not

Type: boolean

isInitials()

Checks if the annotation is initials

Returns:

Returns whether the annotation is initials or not

Type: boolean

isInternal()

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

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

move(rect)

Move the annotation based on a new given Core.Math.Rect. Use this method instead of setRect when internal properties (other than x, y, width and height) need to be modified on move.

Parameters:

Name	Type	Description
`rect`	Core.Math.Rect	the new bounding rectangle

removeCustomAppearance()

Removes the custom appearance of the annotation.

resize(rect)

Resize the annotation based on a new given Core.Math.Rect. Use this method instead of setRect when internal properties (other than x, y, width and height) need to be modified on resize.

Parameters:

Name	Type	Description
`rect`	Core.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.<void>

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

setAssociatedNumber(number)

Sets the number to be associated with this annotation.

Parameters:

Name	Type	Description
`number`	number	The number to be associated with this annotation.

See:

enableAnnotationNumbering

setAttachments(files)

Sets the attachments of the annotation.

Parameters:

Name	Type	Description
`files`	Array.<(File\|Core.Annotations.Annotation.AnnotationAttachment)>	Array of attachments data.

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`	string	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( [shouldKeepAppearance])

Flags the annotation as modified if it has been before the last call to exportAnnotationCommand 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
`shouldKeepAppearance`	boolean	<optional>	If true then the annotation's appearance will be maintained

setNoZoomReferencePoint(referencePoint)

Set the x and y zoom reference point for NoZoom annotation. When this value is set, the NoZoom annotation will stay relative to the given point after the page zoom changes.

Parameters:

Name Type Description

referencePoint

object

The proportional factor for calculating the reference point which is relative to the top left of the annotation. For example, setting this value to {x:0.5, y:1} will set the reference point to the center bottom of the annotation.

Properties

Name	Type	Description
`x`	number	The x value of the reference point. Needs to be a value between 0 and 1.
`y`	number	The y value of the reference point. Needs to be a value between 0 and 1.

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`	Core.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`	Core.Math.Rect	the new bounding rectangle

setRichTextStyle(richTextStyle)

Sets the rich text style of the annotation. New style will replace the old one

Parameters:

Name	Type	Description
`richTextStyle`	Core.Annotations.Annotation.RichTextStyle	The new rich text style of the annotation

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

updateRichTextStyle(object [, startIndex] [, endIndex])

Update the rich text style of the annotation. Can provide a range to set the which characters the style should apply to

Parameters:

Name Type Argument Description

object

Core.Annotations.Annotation.StyleObject

The new rich text style of the annotation

Properties

Name	Type	Description
`'underline'`	boolean	boolean value for whether string should be underlined
`'line-through'`	boolean	boolean value for whether string should be strike through
`'font-weight'`	string	String for the font weight of the rich text (can be 'bold')
`'font-style'`	string	String for font style of the rich text (can be 'italic')
`'color'`	string	string for what color to set text to

startIndex number <optional> Starting character to apply style, if null apply to every character

endIndex number <optional> Last character to apply style. If null, apply till end

Type Definitions

AnnotationAttachment

An object that represents an annotation attchment.

Type:

Object

Properties:

Name	Type	Argument	Description
`name`	string		Name of the attachment
`size`	number		Size of the attachment
`type`	string		MIME type of the attachment
`content`	string	<optional>	Compressed data of the attachment
`url`	string	<optional>	URL pointing to the attachment saved on cloud

Example

{
  name: 'test_image.png',
  size: 1024
  type: 'image/png',
  content: '789CAD79075453DBD62E2DF',
}

ContentEditingFormat

an object that contains content editing properties which apply to selections of text while inline editing.

Type:

Object

Properties:

Name	Type	Description
`bold`	boolean	Whether or not the selection of text is bold
`color`	Core.Annotations.Color	The color of the selection of text
`italic`	boolean	Whether or not the selection of text is italic
`underline`	boolean	Whether or not the selection of text is underlined

Example

{
 bold: false,
 color: new instance.Core.Annotations.Color('#424242'),
 italic: false,
 underline: false,
}

ContentStyleProperties

an object that contains content style properties from a content editing annotation.

Type:

Object

Properties:

Name	Type	Description
`fontFamily`	string	the font family of the text content
`fontSize`	string	the font size of the text content
`textAlign`	string	the alignment of the text content

Example

{
 fontFamily: 'SourceSansProSemiBold',
 fontSize: '30pt',
 textAlign: 'left'
}

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'
`'font-family'`	string	<optional>
`'font-size'`	string	<optional>
`color`	string	<optional>	color in RGB hex format

RichTextStyle

an object that maps between a text style location(character index) to css styles.

Type:

Object.<string, Core.Annotations.Annotation.RichTextCSSStyle>

Example

{
  0: {
    'font-weight': 'bold',
    'color': '#ff0000',
  },
  10: {
    'font-style': 'italic',
    'font-weight': 'bold',
    'color': '#0000ff',
    'font-family': 'Arial',
    'font-size': '20pt',
  },
  12: {
    'text-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.