PDFTron WebViewer Class: Annot

new Annot()

Annot is a base class for different types of annotations. For annotation specific properties, please refer to derived classes. An annotation is an interactive object placed on a page, such as a text note, a link, or an embedded file. PDF includes a wide variety of standard annotation types. An annotation associates an object such as a widget, note, or movie with a location on a page of a PDF document, or provides a means of interacting with the user via the mouse and keyboard. For more details on PDF annotations please refer to section 12.5 in the PDF Reference Manual and the documentation in derived classes.

Members

<static> EventType

Properties:

Name	Type	Description
`e_action_trigger_activate`	number
`e_action_trigger_annot_enter`	number
`e_action_trigger_annot_exit`	number
`e_action_trigger_annot_down`	number
`e_action_trigger_annot_up`	number
`e_action_trigger_annot_focus`	number
`e_action_trigger_annot_blur`	number
`e_action_trigger_annot_page_open`	number
`e_action_trigger_annot_page_close`	number
`e_action_trigger_annot_page_visible`	number
`e_action_trigger_annot_page_invisible`	number

<static> Flag

Properties:

Name	Type	Description
`e_invisible`	number
`e_hidden`	number
`e_print`	number
`e_no_zoom`	number
`e_no_rotate`	number
`e_no_view`	number
`e_annot_read_only`	number
`e_locked`	number
`e_toggle_no_view`	number
`e_locked_contents`	number

<static> State

Properties:

Name	Type	Description
`e_normal`	number
`e_rollover`	number
`e_down`	number

<static> Type

Properties:

Name	Type	Description
`e_Text`	number
`e_Link`	number
`e_FreeText`	number
`e_Line`	number
`e_Square`	number
`e_Circle`	number
`e_Polygon`	number
`e_Polyline`	number
`e_Highlight`	number
`e_Underline`	number
`e_Squiggly`	number
`e_StrikeOut`	number
`e_Stamp`	number
`e_Caret`	number
`e_Ink`	number
`e_Popup`	number
`e_FileAttachment`	number
`e_Sound`	number
`e_Movie`	number
`e_Widget`	number
`e_Screen`	number
`e_PrinterMark`	number
`e_TrapNet`	number
`e_Watermark`	number
`e_3D`	number
`e_Redact`	number
`e_Projection`	number
`e_RichMedia`	number
`e_Unknown`	number

Methods

<static> create(doc, type, pos)

Creates a new annotation of a given type, in the specified document. The newly created annotation does not contain any properties specific to a given annotation type, which means an invalid annotation object could be created. It is therefore recommended to always create an annotation using type specific methods, such as Annots::Line::Create() or Annots::FileAttachment::Create(). Users should only call Annot::Create() to create annotations of non-standard types that are not recognized by PDFTron software (by using Annot::e_Unknown as a type).

Parameters:

Name Type Description

doc PDFNet.PDFDoc | PDFNet.SDFDoc | PDFNet.FDFDoc A document to which the annotation is added.

Name	Type	Description
`doc`	PDFNet.PDFDoc \| PDFNet.SDFDoc \| PDFNet.FDFDoc	A document to which the annotation is added.
`type`	number	PDFNet.Annot.Type = { e_Text : 0 e_Link : 1 e_FreeText : 2 e_Line : 3 e_Square : 4 e_Circle : 5 e_Polygon : 6 e_Polyline : 7 e_Highlight : 8 e_Underline : 9 e_Squiggly : 10 e_StrikeOut : 11 e_Stamp : 12 e_Caret : 13 e_Ink : 14 e_Popup : 15 e_FileAttachment : 16 e_Sound : 17 e_Movie : 18 e_Widget : 19 e_Screen : 20 e_PrinterMark : 21 e_TrapNet : 22 e_Watermark : 23 e_3D : 24 e_Redact : 25 e_Projection : 26 e_RichMedia : 27 e_Unknown : 28 } Subtype of annotation to create.
`pos`	PDFNet.Rect	A rectangle specifying the annotation's bounds, specified in user space coordinates.

type

number

PDFNet.Annot.Type = {
	e_Text : 0
	e_Link : 1
	e_FreeText : 2
	e_Line : 3
	e_Square : 4
	e_Circle : 5
	e_Polygon : 6
	e_Polyline : 7
	e_Highlight : 8
	e_Underline : 9
	e_Squiggly : 10
	e_StrikeOut : 11
	e_Stamp : 12
	e_Caret : 13
	e_Ink : 14
	e_Popup : 15
	e_FileAttachment : 16
	e_Sound : 17
	e_Movie : 18
	e_Widget : 19
	e_Screen : 20
	e_PrinterMark : 21
	e_TrapNet : 22
	e_Watermark : 23
	e_3D : 24
	e_Redact : 25
	e_Projection : 26
	e_RichMedia : 27
	e_Unknown : 28
}

Subtype of annotation to create.

pos PDFNet.Rect A rectangle specifying the annotation's bounds, specified in user space coordinates.

Returns:

A promise that resolves to a newly created blank annotation for the given annotation type.

Type: Promise.<PDFNet.Annot>

<static> createFromObj( [d])

Create an annotation and initialize it using given Cos/SDF object.

Parameters:

Name	Type	Argument	Description
`d`	PDFNet.Obj	<optional>	The Cos/SDF object to initialze the annotation with.

Returns:

A promise that resolves to an object of type: "PDFNet.Annot"

Type: Promise.<PDFNet.Annot>

<static> getBorderStyleStyle(bs)

Parameters:

Name	Type	Description
`bs`	PDFNet.AnnotBorderStyle

Returns:

A promise that resolves to an object of type: "number"

PDFNet.AnnotBorderStyle.Style = {
	e_solid : 0
	e_dashed : 1
	e_beveled : 2
	e_inset : 3
	e_underline : 4
}

Type: Promise.<number>

<static> setBorderStyleStyle(bs, bst)

Parameters:

Name	Type	Description
`bs`	PDFNet.AnnotBorderStyle
`bst`	number

Returns:

Type: Promise.<void>

compare(d)

Compares two annotations for equality. The comparison will return true only if both annotations share the same underlying SDF/Cos object.

Parameters:

Name	Type	Description
`d`	PDFNet.Annot	Annotation to compare to

Returns:

A promise that resolves to an object of type: "boolean"

Type: Promise.<boolean>

copy()

Copy Constructor

Returns:

A promise that resolves to an object of type: "PDFNet.Annot"

Type: Promise.<PDFNet.Annot>

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.

Returns:

Type: Promise.<void>

flatten(page)

Parameters:

Name	Type	Description
`page`	PDFNet.Page

Returns:

Type: Promise.<void>

getActiveAppearanceState()

Gets the annotation's active appearance state.

Returns:

A promise that resolves to the name of the active state. The annotation's appearance state, which selects the applicable appearance stream from an appearance subdictionary.

Type: Promise.<string>

getAppearance( [annot_state] [, app_state])

Gets the annotation's appearance for the given combination of annotation and appearance states.

Parameters:

Name	Type	Argument	Description
`annot_state`	number	<optional>	PDFNet.Annot.State = { e_normal : 0 e_rollover : 1 e_down : 2 } the annotation's appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
`app_state`	string	<optional>	is an optional parameter specifying the appearance state to look for (e.g. "Off", "On", etc). If appearance_state is NULL, the choice between different appearance states is determined by the AS (Appearance State) entry in the annotation dictionary.

Returns:

A promise that resolves to the appearance stream for this annotation, or NULL if the annotation does not have an appearance for the given combination of annotation and appearance states.

Type: Promise.<PDFNet.Obj>

getBorderStyle()

Gets the border style for the annotation. Typically used for Link annotations.

Returns:

A promise that resolves to annotation's border style.

Type: Promise.<PDFNet.AnnotBorderStyle>

getColor()

Gets an annotation's color without any specified color space. It is generally recommended to use getColorAsRGB(), getColorAsCMYK() or getColorAsGray() for more predictable behavior

Returns:

A promise that resolves to a ColorPt object containing an array of numbers in the range 0.0 to 1.0.

Type: Promise.<PDFNet.ColorPt>

getColorAsCMYK()

Returns the annotation's color in CMYK color space.

Returns:

A promise that resolves to a ColorPt object containing an array of four numbers in the range 0.0 to 1.0, representing a CMYK color used for the following purposes: The background of the annotation's icon when closed The title bar of the annotation's pop-up window The border of a link annotation If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

Type: Promise.<PDFNet.ColorPt>

getColorAsGray()

Returns the annotation's color in Gray color space.

Returns:

A promise that resolves to a ColorPt object containing a number in the range 0.0 to 1.0, representing a Gray Scale color used for the following purposes: The background of the annotation's icon when closed The title bar of the annotation's pop-up window The border of a link annotation If the annotation does not specify an explicit color, black color is returned.

Type: Promise.<PDFNet.ColorPt>

getColorAsRGB()

Gets an annotation's color in RGB color space.

Returns:

A promise that resolves to a ColorPt object containing an array of three numbers in the range 0.0 to 1.0, representing an RGB colour used for the following purposes: The background of the annotation's icon when closed The title bar of the annotation's pop-up window The border of a link annotation If the annotation does not specify an explicit color, a default color is returned. Text annotations return 'default yellow;' all others return black.

Type: Promise.<PDFNet.ColorPt>

getColorCompNum()

Returns the color space the annotation's color is represented in.

Returns:

A promise that resolves to an integer that is either 1(for DeviceGray), 3(DeviceRGB), or 4(DeviceCMYK). If the annotation has no color, i.e. is transparent, 0 will be returned.

Type: Promise.<number>

getContents()

Extract the content of this annotation. (Optional).

Returns:

A promise that resolves to A unicode string object with the text that is associated with this annotation. This is the text that annotation displays on user interaction, if the annotation type supports it.

Type: Promise.<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:

A promise that resolves to the custom data string. If no data is available an empty string is returned.

Type: Promise.<string>

getDate()

Gets an annotation's last modified date.

Returns:

A promise that resolves to the annotation's last modified time and date. If the annotation has no associated date structure, the returned date is not valid (date.IsValid() returns false). Corresponds to the "M" entry of the annotation dictionary.

Type: Promise.<PDFNet.Date>

getFlag(flag)

Parameters:

Name	Type	Description
`flag`	number	PDFNet.Annot.Flag = { e_invisible : 0 e_hidden : 1 e_print : 2 e_no_zoom : 3 e_no_rotate : 4 e_no_view : 5 e_annot_read_only : 6 e_locked : 7 e_toggle_no_view : 8 e_locked_contents : 9 } The Flag property to query.

Returns:

A promise that resolves to the value of given Flag

Type: Promise.<boolean>

getOptionalContent()

Returns optional content associated with this annotation.

Returns:

A promise that resolves to a SDF object corresponding to the group of optional properties.

Type: Promise.<PDFNet.Obj>

getPage()

Gets the page the annotation is associated with.

Returns:

A promise that resolves to a Page object or null page object if the page reference is not available. The page object returned is an indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions. Optional. PDF 1.3 PDF 1.4 PDF 1.5 not used in FDF files.

Type: Promise.<PDFNet.Page>

getRect()

Returns:

A promise that resolves to annotation's bounding rectangle, specified in user space coordinates. The meaning of the rectangle depends on the annotation type. For Link and RubberStamp annotations, the rectangle specifies the area containing the hyperlink area or stamp. For Note annotations, the rectangle is describing the popup window when it's opened. When it's closed, the icon is positioned at lower left corner.

Type: Promise.<PDFNet.Rect>

getRotation()

Returns the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90.

Returns:

A promise that resolves to an integer representing the rotation value of the annotation.

Type: Promise.<number>

getSDFObj()

Returns:

A promise that resolves to the underlying SDF/Cos object.

Type: Promise.<PDFNet.Obj>

getStructParent()

Returns the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Returns:

A promise that resolves to an integer which is the integer key of the annotation's entry in the structural parent tree.

Type: Promise.<number>

getTriggerAction(trigger)

Get the Action associated with the selected Annot Trigger event.

Parameters:

Name Type Description

Name	Type	Description
`trigger`	number	PDFNet.Annot.EventType = { e_action_trigger_activate : 0 e_action_trigger_annot_enter : 1 e_action_trigger_annot_exit : 2 e_action_trigger_annot_down : 3 e_action_trigger_annot_up : 4 e_action_trigger_annot_focus : 5 e_action_trigger_annot_blur : 6 e_action_trigger_annot_page_open : 7 e_action_trigger_annot_page_close : 8 e_action_trigger_annot_page_visible : 9 e_action_trigger_annot_page_invisible : 10 } the type of trigger event to get

trigger

number

PDFNet.Annot.EventType = {
	e_action_trigger_activate : 0
	e_action_trigger_annot_enter : 1
	e_action_trigger_annot_exit : 2
	e_action_trigger_annot_down : 3
	e_action_trigger_annot_up : 4
	e_action_trigger_annot_focus : 5
	e_action_trigger_annot_blur : 6
	e_action_trigger_annot_page_open : 7
	e_action_trigger_annot_page_close : 8
	e_action_trigger_annot_page_visible : 9
	e_action_trigger_annot_page_invisible : 10
}

the type of trigger event to get

Returns:

A promise that resolves to the Action Obj if present, otherwise NULL

Type: Promise.<PDFNet.Obj>

getType()

Returns:

A promise that resolves to the type of this annotation. Corresponds to the "Subtype" entry of annotation dictionary, as per PDF Reference Manual section 12.5.2

Type: Promise.<number>

Example

Return value enum:
<pre>
PDFNet.Annot.Type = {
	e_Text : 0
	e_Link : 1
	e_FreeText : 2
	e_Line : 3
	e_Square : 4
	e_Circle : 5
	e_Polygon : 6
	e_Polyline : 7
	e_Highlight : 8
	e_Underline : 9
	e_Squiggly : 10
	e_StrikeOut : 11
	e_Stamp : 12
	e_Caret : 13
	e_Ink : 14
	e_Popup : 15
	e_FileAttachment : 16
	e_Sound : 17
	e_Movie : 18
	e_Widget : 19
	e_Screen : 20
	e_PrinterMark : 21
	e_TrapNet : 22
	e_Watermark : 23
	e_3D : 24
	e_Redact : 25
	e_Projection : 26
	e_RichMedia : 27
	e_Unknown : 28
}
</pre>

getUniqueID()

Returns:

A promise that resolves to the unique identifier for this annotation, or NULL if the identifier is not available. The returned value is a String object and is the value of the "NM" field, which was added as an optional attribute in PDF 1.4.

Type: Promise.<PDFNet.Obj>

getVisibleContentBox()

It is possible during viewing that GetRect does not return the most accurate bounding box of what is actually rendered. This method calculates the bounding box, rather than relying on what is specified in the PDF document. The bounding box is defined as the smallest rectangle that includes all the visible content on the annotation.

Returns:

A promise that resolves to the bounding box for this annotation. The dimensions are specified in user space coordinates.

Type: Promise.<PDFNet.Rect>

isMarkup()

Return true if this annotation is classified as a markup annotation.

Returns:

A promise that resolves to boolean value, true if this annotation is classified as a markup annotation.

Type: Promise.<boolean>

isValid()

Returns:

A promise that resolves to true if this is a valid (non-null) annotation, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid and the annotation object should be treated as a null object.

Type: Promise.<boolean>

refreshAppearance()

Regenerates the appearance stream for the annotation. This method can be used to auto-generate the annotation appearance after creating or modifying the annotation without providing an explicit appearance or setting the "NeedAppearances" flag in the AcroForm dictionary.

Returns:

Type: Promise.<void>

refreshAppearanceRefreshOptions( [options])

A version of RefreshAppearance allowing custom options to make slight tweaks in behaviour.

Parameters:

Name	Type	Argument	Description
`options`	PDFNet.RefreshOptions	<optional>	The RefreshOptions.

Returns:

Type: Promise.<void>

removeAppearance( [annot_state] [, app_state])

Removes the annotation's appearance for the given combination of annotation and appearance states.

Parameters:

Name	Type	Argument	Description
`annot_state`	number	<optional>	PDFNet.Annot.State = { e_normal : 0 e_rollover : 1 e_down : 2 } the annotation's appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
`app_state`	string	<optional>	is an optional parameter specifying the appearance state (e.g. "Off", "On", etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotation state.

Returns:

Type: Promise.<void>

resize(newrect)

Scales the geometry of the annotation so that its appearance would now fit a new rectangle on the page, in user units. Users still have to call RefreshAppearance() later if they want a corresponding appearance stream to be generated for the new rectangle. The main reason for not combining the two operations together is to be able to resize annotations that do not have an appearance stream.

Parameters:

Name	Type	Description
`newrect`	PDFNet.Rect	A reference to the new rectangle to which this annotation has to be resized.

Returns:

Type: Promise.<void>

setActiveAppearanceState(astate)

Parameters:

Name	Type	Description
`astate`	string

Returns:

Type: Promise.<void>

setAppearance(app_stream [, annot_state] [, app_state])

Sets the annotation's appearance for the given combination of annotation and appearance states. (Optional; PDF 1.2)

Parameters:

Name	Type	Argument	Description
`app_stream`	PDFNet.Obj		a content stream defining the new appearance.
`annot_state`	number	<optional>	PDFNet.Annot.State = { e_normal : 0 e_rollover : 1 e_down : 2 } the annotation's appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.
`app_state`	string	<optional>	is an optional parameter specifying the appearance state (e.g. "Off", "On", etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotation state.

Returns:

Type: Promise.<void>

setBorderStyle(bs [, oldStyleOnly])

Sets the border style for the annotation.

Parameters:

Name	Type	Argument	Description
`bs`	PDFNet.AnnotBorderStyle		New border style for this annotation.
`oldStyleOnly`	boolean	<optional>	PDF manual specifies two ways to add border information to an annotation object, either through an array named 'Border' (PDF 1.0), or a dictionary called 'BS' (PDF 1.2) the latter taking precedence over the former. However, if you want to create a border with rounded corners, you can only do that using PDF 1.0 Border specification, in which case if you call SetBorderStyle() set the parameter oldStyleOnly to true. This parameter has a default value of false in the API and does not need to be used otherwise.

Returns:

Type: Promise.<void>

setColor(col [, numcomp])

Sets an annotation's color. (Optional; PDF 1.1)

Parameters:

Name	Type	Argument	Description
`col`	PDFNet.ColorPt		A ColorPt object in RGB or Gray or CMYK color space representing the annotation's color. The ColorPt contains an array of numbers in the range 0.0 to 1.0, representing a color used for the following purposes: The background of the annotation's icon when closed The title bar of the annotation's pop-up window The border of a link annotation The number of array elements determines the color space in which the color shall be defined: 0 No color; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK
`numcomp`	number	<optional>	The number of color components used to represent the color (i.e. 1, 3, 4).

Returns:

Type: Promise.<void>

setColorDefault(col)

Parameters:

Name	Type	Description
`col`	PDFNet.ColorPt

Returns:

Type: Promise.<void>

setContents(contents)

Sets the content of this annotation. (Optional).

Parameters:

Name	Type	Description
`contents`	string	A reference to unicode string object with the text that will be associated with this annotation. This is the text that annotation displays on user interaction, if the annotation type supports it.

Returns:

Type: Promise.<void>

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
`value`	string	The custom data string to store

Returns:

Type: Promise.<void>

setDate(date)

Sets an annotation's last modified date.

Parameters:

Name	Type	Description
`date`	PDFNet.Date	The annotation's last modified time and date. Corresponds to the "M" entry of the annotation dictionary.

Returns:

Type: Promise.<void>

setFlag(flag, value)

sets the value of given Flag.

Parameters:

Name	Type	Description
`flag`	number	PDFNet.Annot.Flag = { e_invisible : 0 e_hidden : 1 e_print : 2 e_no_zoom : 3 e_no_rotate : 4 e_no_view : 5 e_annot_read_only : 6 e_locked : 7 e_toggle_no_view : 8 e_locked_contents : 9 } The Flag property to modify.
`value`	boolean	The new value for the property.

Returns:

Type: Promise.<void>

setOptionalContent(content)

Associates optional content with this annotation. (Optional, PDF1.5).

Parameters:

Name	Type	Description
`content`	PDFNet.Obj	A pointer to an SDF object corresponding to the optional content, a PDF::OCG::Group or membership dictionary specifying the PDF::OCG::Group properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the Flag entry . If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document.

Returns:

Type: Promise.<void>

setPage(Page)

sets the reference to a page the annotation is associated with. (Optional PDF 1.3; not used in FDF files)

Parameters:

Name	Type	Description
`Page`	PDFNet.Page	The page object user wants the annotation to be associated with.

Returns:

Type: Promise.<void>

setRect(pos)

Sets the size and location of an annotation on its page.

Parameters:

Name	Type	Description
`pos`	PDFNet.Rect	Annotation's bounding rectangle, specified in user space coordinates. The meaning of the rectangle depends on the annotation type. For Link and RubberStamp annotations, the rectangle specifies the area containing the hyperlink area or stamp. For Note annotations, the rectangle is describing the popup window when it's opened. When it's closed, the icon is positioned at lower left corner.

Returns:

Type: Promise.<void>

setRotation(angle)

Sets the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90. (Optional)

Parameters:

Name	Type	Description
`angle`	number	An integer representing the rotation value of the annotation.

Returns:

Type: Promise.<void>

setStructParent(parkeyval)

sets the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Parameters:

Name	Type	Description
`parkeyval`	number	An integer which is the integer key of the annotation's entry in the structural parent tree.

Returns:

Type: Promise.<void>