PDFAnnotation¶

PDF Annotations belong to a specific PDFPage and may be created/changed/removed. Because annotation appearances may change (for several reasons) it is possible to scan through the annotations on a page and query them to see whether a re-render is necessary.

Additionally redaction annotations can be applied to a PDFPage, destructively removing content from the page.

Annotation Types¶

These are the annotation types, and which attributes they have.

Text

An icon with a popup of text.

Set the appearance with the Icon attribute.

Attributes: Rect, Color, Icon.

FreeText

Text in a rectangle on the page.

The text font and color is defined by DefaultAppearance.

Attributes: Border, Rect, Default Appearance.

Line

A line with optional arrow heads.

The line width is determined by the border attribute.

The end points are defined by the Line attribute.

Attributes: Border, Color, Line, Line Ending Styles.

Square

A rectangle.

Attributes: Rect, Rect, Color, Interior Color.

Circle

An ellipse.

Attributes: Rect, Border, Color, Interior Color.

Polygon, PolyLine

A polygon shape (closed and open).

The shape is defined by the Vertices attribute.

The line width is defined by the Border attribute.

Attributes: Vertices, Border, Color, Interior Color, LineEndingStyles.

Highlight, Underline, Squiggly, StrikeOut

Text markups.

The shape is defined by the QuadPoints.

Stamp

A rubber stamp.

The appearance is either a stock name, or a custom image.

Ink

A free-hand line.

The shape is defined by the Ink List attribute.

FileAttachment

A file attachment.

The appearance is an icon on the page.

Set the attached file contents with the Filespec attribute, and the appearance with the Icon attribute.

Redaction

A black box.

Redaction annotations are used to mark areas of the page that can be redacted. They do NOT redact any content by themselves, you MUST apply them using PDFAnnotation.prototype.applyRedaction or PDFPage.prototype.applyRedactions.

These annotation types are special and handled with other APIs:

Link
Popup – see PDFAnnotation.prototype.setPopup()
Widget – see PDFWidget

Constructors¶

class PDFAnnotation()¶: You cannot create instances of this class with the new operator!

To get the annotations on a page use PDFPage.prototype.getAnnotations().

To create a new annotation call PDFPage.prototype.createAnnotation().

Instance methods¶

PDFAnnotation.prototype.getBounds()¶

Returns a rectangle containing the location and dimension of the annotation.

Returns:: Rect

var bounds = annotation.getBounds()

PDFAnnotation.prototype.run(device, matrix)¶

Calls the device functions to draw the annotation.

Arguments:

device (Device) – The device to make device calls to while rendering the annotation.
matrix (Matrix) – The transformation matrix.

annotation.run(device, mupdf.Matrix.identity)

PDFAnnotation.prototype.toPixmap(matrix, colorspace, alpha)¶

Render the annotation into a Pixmap, using the transform, colorspace and alpha parameters.

Arguments:

matrix (Matrix) – Transformation matrix.
colorspace (ColorSpace) – The desired colorspace of the returned pixmap.
alpha (boolean) – Whether the returned pixmap has transparency or not. If the pixmap handles transparency, it starts out transparent (otherwise it is filled white), before the contents of the display list are rendered onto the pixmap.

Returns:

Pixmap

var pixmap = annotation.toPixmap(mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, true)

PDFAnnotation.prototype.toDisplayList()¶

Record the contents of the annotation into a DisplayList.

Returns:: DisplayList

var displayList = annotation.toDisplayList()

PDFAnnotation.prototype.getObject()¶

Get the underlying PDFObject for an annotation.

Returns:: PDFObject

var obj = annotation.getObject()

PDFAnnotation.prototype.setAppearance(appearance, state, transform, bbox, resources, contents)¶

Set the annotation appearance stream for the given appearance. The desired appearance is given as a transform along with a bounding box, a PDF dictionary of resources and a content stream.

Arguments:

appearance (string | null) – Appearance stream (“N” for normal, “R” for roll-over or “D” for down). Defaults to “N”.
state (string | null) – The annotation state to set the appearance for or null for the current state. Only widget annotations of pushbutton, check box, or radio button type have states, which are “Off” or “Yes”. For other types of annotations pass null.
transform (Matrix) – The transformation matrix.
bbox (Rect) – The bounding box.,
resources (PDFObject) – Resources object.
contents (Buffer | ArrayBuffer | Uint8Array | string) – Contents string.

annotation.setAppearance(
        "N",
        null,
        mupdf.Matrix.identity,
        [0, 0, 100, 100],
        resources,
        contents
)

PDFAnnotation.prototype.update()¶

Update the appearance stream to account for changes in the annotation.

Returns true if the annotation appearance changed during the call.

Returns:: boolean

annotation.update()

PDFAnnotation.prototype.setAppearanceFromDisplayList(appearance, state, transform, list)¶

Set the annotation appearance stream for the given appearance. The desired appearance is given as a transform along with a display list.

Arguments:

appearance (string) – Appearance stream (“N”, “R” or “D”).
state (string) – The annotation state to set the appearance for or null for the current state. Only widget annotations of pushbutton, check box, or radio button type have states, which are “Off” or “Yes”. For other types of annotations pass null.
transform (Matrix) – The transformation matrix.
list (DisplayList) – The display list.

annotation.setAppearanceFromDisplayList(
        "N",
        null,
        mupdf.Matrix.identity,
        displayList
)

PDFAnnotation.prototype.getHiddenForEditing()¶

Get a special annotation hidden flag for editing. This flag prevents the annotation from being rendered.

Returns:: boolean

var hidden = annotation.getHiddenForEditing()

PDFAnnotation.prototype.setHiddenForEditing(hidden)¶

Set a special annotation hidden flag for editing. This flag prevents the annotation from being rendered.

Arguments:

hidden (boolean)

annotation.setHiddenForEditing(true)

PDFAnnotation.prototype.getHot()¶

only mutool run

Check if the annotation is hot, i.e. that the pointing device’s cursor is hovering over the annotation.

Returns:: boolean

annotation.getHot()

PDFAnnotation.prototype.setHot(hot)¶

only mutool run

Set the annotation as being hot, i.e. that the pointing device’s cursor is hovering over the annotation.

Arguments:

hot (boolean)

annotation.setHot(true)

PDFAnnotation.prototype.requestSynthesis()¶

only mutool run

Request that if an annotation does not have an appearance stream, flag the annotation to have one generated. The appearance stream will be created during future calls to PDFAnnotation.prototype.update() on or PDFPage.prototype.update().

annotation.requestSynthesis()

PDFAnnotation.prototype.requestResynthesis()¶

only mutool run

Request that an appearance stream shall be re-generated for an annotation next time update() is called on PDFAnnotation.prototype.update() or PDFPage.prototype.update().

This is a side-effect of setting annotation attributes through the PDFAnnotation interface, so normally this call does not need to be done explicitly.

annotation.requestResynthesis()

PDFAnnotation.prototype.process(processor)¶

only mutool run

Run through the annotation appearance stream and call methods on the supplied PDFProcessor.

Arguments:

processor (PDFProcessor) – User defined function.

annotation.process(processor)

PDFAnnotation.prototype.applyRedaction(blackBoxes, imageMethod, lineArtMethod, textMethod)¶

Applies a single Redaction annotation.

See PDFPage.prototype.applyRedactions for details.

Annotation attributes¶

PDF Annotations have many attributes. Some of these are common to all annotations, and some only exist on specific annotation types.

Common¶

PDFAnnotation.prototype.getType()¶

Return the annotation type for this annotation.

Returns:: string

var type = annotation.getType()

PDFAnnotation.prototype.getFlags()¶

Get the annotation flags.

See PDFAnnotation.prototype.setFlags.

Returns:: number

var flags = annotation.getFlags()

PDFAnnotation.prototype.setFlags(flags)¶

Set the annotation flags.

Arguments:

flags (number) – A bit mask with the flags (see below).

Bit	Name
1	Invisible
2	Hidden
3	Print
4	NoZoom
5	NoRotate
6	NoView
7	ReadOnly
8	Locked
9	ToggleNoView
10	LockedContents

annotation.setFlags(4) // Clears all other flags and sets "NoZoom".

PDFAnnotation.prototype.getContents()¶

Get the annotation contents.

Returns:: string

var contents = annotation.getContents()

PDFAnnotation.prototype.setContents(text)¶

Set the annotation contents.

Arguments:

text (string)

annotation.setContents("Hello World")

PDFAnnotation.prototype.getCreationDate()¶

Get the annotation creation date as a Date object.

Returns:: Date

var date = annotation.getCreationDate()

PDFAnnotation.prototype.setCreationDate(date)¶

Set the creation date.

Arguments:

date (Date) – A Date object.

annotation.setCreationDate(new Date())

PDFAnnotation.prototype.getModificationDate()¶

Get the annotation modification date as a Date object.

Returns:: Date

var date = annotation.getModificationDate()

PDFAnnotation.prototype.setModificationDate(date)¶

Set the modification date.

Arguments:

date (Date)

annotation.setModificationDate(new Date())

PDFAnnotation.prototype.getLanguage()¶

Get the annotation language code (or get the one inherited from the document).

Returns:: string | null

var language = annotation.getLanguage()

PDFAnnotation.prototype.setLanguage(language)¶

Set the annotation language code.

Arguments:

language (string) – The desired language code.

annotation.setLanguage("en")

Rect¶

For annotations that can be resized by setting its bounding box rectangle (e.g. Square and FreeText), PDFAnnotation.prototype.hasRect() returns true.

Other annotation types, (e.g. Line, Polygon, and InkList) change size by adding/removing vertices. Yet other annotations (e.g. Highlight and StrikeOut) change size by adding/removing QuadPoints.

The underlying Rect attribute on the PDF object is automatically updated as needed for these other annotation types.

PDFAnnotation.prototype.hasRect()¶

Checks whether the annotation can be resized by setting its bounding box.

Returns:: boolean

var hasRect = annotation.hasRect()

PDFAnnotation.prototype.getRect()¶

Get the annotation bounding box.

Returns:: Rect

var rect = annotation.getRect()

PDFAnnotation.prototype.setRect(rect)¶

Set the annotation bounding box.

Arguments:

rect (Rect) – The new desired bounding box.

annotation.setRect([0, 0, 100, 100])

Rich contents¶

PDFAnnotation.prototype.hasRichContents()¶

Returns whether the annotation is capable of supporting rich text contents.

Returns:: boolean

var hasRichContents = annotation.hasRichContents()

PDFAnnotation.prototype.getRichContents()¶

Obtain the annotation’s rich-text contents, as opposed to the plain text contents obtained by getContents().

Returns:: string

var richContents = annotation.getRichContents()

PDFAnnotation.prototype.setRichContents(plainText, richText)¶

Set the annotation’s rich-text contents, as opposed to the plain text contents set by setContents().

Arguments:

plainText (string)
richText (string)

annotation.setRichContents("plain text", "<b><i>Rich-Text</i></b>")

PDFAnnotation.prototype.getRichDefaults()¶

Get the default style used for the annotation’s rich-text contents.

Returns:: string

var richDefaults = annotation.getRichDefaults()

PDFAnnotation.prototype.setRichDefaults(style)¶

Set the default style used for the annotation’s rich-text contents.

Arguments:

style (string)

annotation.setRichDefaults("font-size: 16pt")

Color¶

The meaning of the color attribute depends on the annotation type. For some it is the color of the border.

PDFAnnotation.prototype.getColor()¶

Get the annotation color, represented as an array of 0, 1, 3, or 4 component values.

Returns:: Color

var color = annotation.getColor()

PDFAnnotation.prototype.setColor(color)¶

Set the annotation color, represented as an array of 0, 1, 3, or 4 component values.

Arguments:

color (Color) – The new color.

Throws:

TypeError if number of components is not 0, 1, 3, or 4.

annotation.setColor([0, 1, 0])

Opacity¶

PDFAnnotation.prototype.getOpacity()¶

Get the annotation opacity.

Returns:: number

var opacity = annotation.getOpacity()

PDFAnnotation.prototype.setOpacity(opacity)¶

Set the annotation opacity.

Arguments:

opacity (number) – The desired opacity.

annotation.setOpacity(0.5)

Quadding¶

PDFAnnotation.prototype.hasQuadding()¶

only mutool run

Returns whether the annotation is capable of supporting quadding (justification).

Returns:: boolean

var hasQuadding = annotation.hasQuadding()

PDFAnnotation.prototype.getQuadding()¶

Get the annotation quadding (justification). Quadding value, 0 for left-justified, 1 for centered, 2 for right-justified

Returns:: number

var quadding = annotation.getQuadding()

PDFAnnotation.prototype.setQuadding(value)¶

Set the annotation quadding (justification). Quadding value, 0 for left-justified, 1 for centered, 2 for right-justified.

Arguments:

value (number) – The desired quadding.

annotation.setQuadding(1)

Author¶

PDFAnnotation.prototype.hasAuthor()¶

Returns whether the annotation is capable of supporting an author.

Returns:: boolean

var hasAuthor = annotation.hasAuthor()

PDFAnnotation.prototype.getAuthor()¶

Gets the annotation author.

Returns:: string

var author = annotation.getAuthor()

PDFAnnotation.prototype.setAuthor(author)¶

Sets the annotation author.

Arguments:

author (string)

annotation.setAuthor("Jane Doe")

Border¶

PDFAnnotation.prototype.hasBorder()¶

Returns whether the annotation is capable of supporting a border.

Returns:: boolean

var hasBorder = annotation.hasBorder()

PDFAnnotation.prototype.getBorderStyle()¶

Get the annotation border style.

Returns:: string

var borderStyle = annotation.getBorderStyle()

PDFAnnotation.prototype.setBorderStyle(style)¶

Set the annotation border style.

Arguments:

style (string) – The annotation style.

annotation.setBorderStyle("Dashed")

PDFAnnotation.prototype.getBorderWidth()¶

Get the border width in points.

Returns:: number

var w = annotation.getBorderWidth()

PDFAnnotation.prototype.setBorderWidth(width)¶

Set the border width in points. Retains any existing border effects.

Arguments:

width (number)

annotation.setBorderWidth(1.5)

PDFAnnotation.prototype.getBorderDashCount()¶

Returns the number of items in the border dash pattern.

Returns:: number

var dashCount = annotation.getBorderDashCount()

PDFAnnotation.prototype.getBorderDashItem(idx)¶

Returns the length of dash pattern item idx.

Arguments:

idx (number)

Returns:

number

var length = annotation.getBorderDashItem(0)

PDFAnnotation.prototype.setBorderDashPattern(list)¶

Set the annotation border dash pattern to the given array of dash item lengths. The supplied array represents the respective line stroke and gap lengths, e.g. [1, 1] sets a small dash and small gap, [2, 1, 4, 1] would set a medium dash, a small gap, a longer dash and then another small gap.

Arguments:

dashPattern (Array of number)

annotation.setBorderDashPattern([2.0, 1.0, 4.0, 1.0])

PDFAnnotation.prototype.clearBorderDash()¶

Clear the entire border dash pattern for an annotation.

annotation.clearBorderDash()

PDFAnnotation.prototype.addBorderDashItem(length)¶

Append an item (of the given length) to the end of the border dash pattern.

Arguments:

length (number)

annotation.addBorderDashItem(10.0)

PDFAnnotation.prototype.hasBorderEffect()¶

Returns whether the annotation is capable of supporting a border effect.

Returns:: boolean

var hasEffect = annotation.hasBorderEffect()

PDFAnnotation.prototype.getBorderEffect()¶

Get the border effect.

Returns:: string

var effect = annotation.getBorderEffect()

PDFAnnotation.prototype.setBorderEffect(effect)¶

Set the border effect.

Arguments:

effect (string) – The border effect.

annotation.setBorderEffect("None")

PDFAnnotation.prototype.getBorderEffectIntensity()¶

Get the annotation border effect intensity.

Returns:: number

var intensity = annotation.getBorderEffectIntensity()

PDFAnnotation.prototype.setBorderEffectIntensity(intensity)¶

Set the annotation border effect intensity. Recommended values are between 0 and 2 inclusive.

Arguments:

intensity (number) – Border effect intensity.

annotation.setBorderEffectIntensity(1.5)

Callout¶

Callouts are used with FreeText annotations and allow for a graphical line to point to an area on a page.

PDFAnnotation.prototype.hasCallout()¶

Returns whether the annotation is capable of supporting a callout.

Returns:: boolean

PDFAnnotation.prototype.setCalloutLine(line)¶

Takes an array of 2 or 3 points. Supply an empty array to remove the callout line.

Arguments:

points (Array of Point)

PDFAnnotation.prototype.getCalloutLine()¶

Returns the array of points.

Returns:: Array of Point | null

PDFAnnotation.prototype.setCalloutPoint(p)¶

Takes a point where the callout should point to.

Arguments:

p (Point)

PDFAnnotation.prototype.getCalloutPoint()¶

Returns the callout point.

Returns:: Point

PDFAnnotation.prototype.setCalloutStyle(style)¶

Sets the line ending style of the callout line.

Arguments:

style (string)

PDFAnnotation.prototype.getCalloutStyle()¶

Returns the callout style.

Returns:: string

Default Appearance¶

PDFAnnotation.prototype.hasDefaultAppearance()¶

only mutool run

Returns whether the annotation is capable of supporting a default appearance.

Returns:: boolean

var hasRect = annotation.hasDefaultAppearance()

PDFAnnotation.prototype.getDefaultAppearance()¶

Get the default text appearance used for free text annotations as an object containing the font, size, and color.

Returns:: { font: string, size: number, color: Color }

var appearance = annotation.getDefaultAppearance()
console.log("DA font:", appearance.font, appearance.size)
console.log("DA color:", appearance.color)

PDFAnnotation.prototype.setDefaultAppearance(font, size, color)¶

Set the default text appearance used for free text annotations.

Arguments:

font (string) – The desired default font: "Helv" | "TiRo" | "Cour" for Helvetica, Times Roman, and Courier respectively.
size (number) – The desired default font size.
color (Color) – The desired default font color.

annotation.setDefaultAppearance("Helv", 16, [0, 0, 0])

Filespec¶

PDFAnnotation.prototype.hasFilespec()¶

Returns whether the annotation is capable of supporting a file specification.

Returns:: boolean

var hasFilespec = annotation.hasFilespec()

PDFAnnotation.prototype.getFilespec()¶

Get the file specification PDF object for the file attachment, or null if none set.

Returns:: PDFObject | null

var fs = annotation.getFilespec()

PDFAnnotation.prototype.setFilespec(fs)¶

Set the file specification PDF object for the file attachment.

Arguments:

fs (PDFObject)

annotation.setFilespec(fs)

Icon¶

PDFAnnotation.prototype.hasIcon()¶

Returns whether the annotation is capable of supporting an icon.

Returns:: boolean

var hasIcon = annotation.hasIcon()

PDFAnnotation.prototype.getIcon()¶

Get the annotation icon name, either a standard or custom name.

Returns:: string

var icon = annotation.getIcon()

PDFAnnotation.prototype.setIcon(name)¶

Set the annotation icon name.

Note that standard icon names can be used to resynthesize the annotation appearance, but custom names cannot.

Arguments:

name (string) – An icon name.

annotation.setIcon("Note")

Ink List¶

Ink annotations consist of a number of strokes, each consisting of a sequence of vertices between which a smooth line will be drawn.

PDFAnnotation.prototype.hasInkList()¶

Returns whether the annotation is capable of supporting an ink list.

Returns:: boolean

var hasInkList = annotation.hasInkList()

PDFAnnotation.prototype.getInkList()¶

Get the annotation ink list, represented as an array of strokes. Each stroke consists of an array of points.

Returns:: Array of Array of Point

var inkList = annotation.getInkList()

PDFAnnotation.prototype.setInkList(inkList)¶

Set the annotation ink list, represented as an array of strokes. Each stroke consists of an array of points.

Arguments:

inkList (Array of Array of Point)

// this draws a box with a cross in three strokes:
annotation.setInkList([
        [
                [0, 0], [10, 0], [10, 10], [0, 10], [0, 0]
        ],
        [
                [10, 0], [0, 10]
        ],
        [
                [0, 0], [10, 10]
        ]
])

PDFAnnotation.prototype.clearInkList()¶

Clear the list of ink strokes for the annotation.

annotation.clearInkList()

PDFAnnotation.prototype.addInkListStroke()¶

Add a new empty stroke to the ink annotation.

annotation.addInkListStroke()

PDFAnnotation.prototype.addInkListStrokeVertex(v)¶

Append a vertex to end of the last stroke in the ink annotation.

Arguments:

v (Point)

annotation.addInkListStrokeVertex([0, 0])

Interior Color¶

PDFAnnotation.prototype.hasInteriorColor()¶

Returns whether the annotation is capable of supporting an interior color.

Returns:: boolean

var hasInteriorColor = annotation.hasInteriorColor()

PDFAnnotation.prototype.getInteriorColor()¶

Get the annotation interior color, represented as an array of 0, 1, 3, or 4 component values.

Returns:: Color

var interiorColor = annotation.getInteriorColor()

PDFAnnotation.prototype.setInteriorColor(color)¶

Sets the annotation interior color.

Arguments:

color (Color) – The new desired interior color.

Throws:

TypeError if number of components is not 0, 1, 3, or 4.

annotation.setInteriorColor([0, 1, 1])

Line¶

PDFAnnotation.prototype.hasLine()¶

Returns whether the annotation is capable of supporting a line.

Returns:: boolean

var hasLine = annotation.hasLine()

PDFAnnotation.prototype.getLine()¶

Get line end points, represented by an array of two points, each represented as an [x, y] array.

Returns:: Array of Point

var line = annotation.getLine()

PDFAnnotation.prototype.setLine(a, b)¶

Set the two line end points, each represented as an [x, y] array.

Arguments:

a (Point) – The new point a.
b (Point) – The new point b.

annotation.setLine([100, 100], [150, 175])

Line Ending Styles¶

PDFAnnotation.prototype.hasLineEndingStyles()¶

Returns whether the annotation is capable of supporting line ending style.

Returns:: boolean

var hasLineEndingStyles = annotation.hasLineEndingStyles()

PDFAnnotation.prototype.getLineEndingStyles()¶

Get the start and end line ending style values for each end of the line annotation.

Returns:: { start: string, end: string } Returns an object with the key/value pairs

var lineEndingStyles = annotation.getLineEndingStyles()

PDFAnnotation.prototype.setLineEndingStyles(start, end)¶

Sets the line ending style values for each end of the line annotation.

Arguments:

start (string)
end (string)

annotation.setLineEndingStyles("Square", "OpenArrow")

Line Leaders¶

In a PDF line leaders refer to two lines at the ends of the line annotation, oriented perpendicular to the line itself. These are common in technical drawings when illustrating distances.

PDFAnnotation.prototype.setLineLeader(v)¶

Sets the line leader length.

Arguments:

v (number) – The length of leader lines that extend from each endpoint of the line perpendicular to the line itself. A positive value means that the leader lines appear in the direction that is clockwise when traversing the line from its starting point to its ending point a negative value indicates the opposite direction.

Setting a value of 0 effectively removes the line leader.

PDFAnnotation.prototype.getLineLeader()¶

Gets the line leader length.

Returns:: number

PDFAnnotation.prototype.setLineLeaderExtension(v)¶

Sets the line leader extension.

Arguments:

v (number) – A non-negative number representing the length of leader line extensions that extend from the line proper 180 degrees from the leader lines.

Setting a value of 0 effectively removes the line leader extension.

PDFAnnotation.prototype.getLineLeaderExtension()¶

Gets the line leader extension.

Returns:: number

PDFAnnotation.prototype.setLineLeaderOffset(v)¶

Sets the line leader offset.

Arguments:

v (number) – A non-negative number representing the length of the leader line offset, which is the amount of empty space between the endpoints of the annotation and the beginning of the leader lines.

Setting a value of 0 effectively removes the line leader offset.

PDFAnnotation.prototype.getLineLeaderOffset()¶

Gets the line leader offset.

Returns:: number

PDFAnnotation.prototype.setLineCaption(on)¶

Sets whether line caption is enabled or not.

When line captions are enabled then calling the PDFAnnotation.prototype.setContents on the line annotation will render the contents onto the line as the caption text.

Arguments:

on (boolean)

PDFAnnotation.prototype.getLineCaption()¶

Returns whether the line caption is enabled or not.

Returns:: boolean

PDFAnnotation.prototype.setLineCaptionOffset(point)¶

Sets the line caption offset.

The x value of the offset point is the horizontal offset along the annotation line from its midpoint, with a positive value indicating offset to the right and a negative value indicating offset to the left. The y value of the offset point is the vertical offset perpendicular to the annotation line, with a positive value indicating a shift up and a negative value indicating a shift down.

Setting a point of [0, 0] removes the caption offset.

Arguments:

point (Point) – A point specifying the offset of the caption text from its normal position.

PDFAnnotation.prototype.getLineCaptionOffset()¶

Returns the line caption offset as a point, [x, y].

Returns:: Point

Open¶

Open refers to whether the annotation is display in an open state when the page is loaded. A Text Note annotation is considered open if the user has clicked on it to view its contents.

PDFAnnotation.prototype.hasOpen()¶

Returns whether the annotation is capable of supporting annotation open state.

Returns:: boolean

var hasOpen = annotation.hasOpen()

PDFAnnotation.prototype.getIsOpen()¶

Get annotation open state.

Returns:: boolean

var isOpen = annotation.getIsOpen()

PDFAnnotation.prototype.setIsOpen(state)¶

Set annotation open state.

Arguments:

state (boolean)

annotation.setIsOpen(true)

QuadPoints¶

Text markup and redaction annotations consist of a set of quadadrilaterals, or QuadPoints. These are used in e.g. Highlight annotations to mark up several disjoint spans of text.

In Javascript QuadPoints are represented with Quad objects.

PDFAnnotation.prototype.hasQuadPoints()¶

Returns whether the annotation is capable of supporting quadpoints.

Returns:: boolean

var hasQuadPoints = annotation.hasQuadPoints()

PDFAnnotation.prototype.getQuadPoints()¶

Get the annotation’s quadpoints, describing the areas affected by text markup annotations and link annotations.

Returns:: Array of Quad

var quadPoints = annotation.getQuadPoints()

PDFAnnotation.prototype.setQuadPoints(quadList)¶

Set the annotation quadpoints describing the areas affected by text markup annotations and link annotations.

Arguments:

quadList (Array of Quad) – The quadpoints to set.

// two quads, the first one wider than the second one
annotation.setQuadPoints([
        [ 100, 100, 200, 100, 200, 150, 100, 150 ],
        [ 125, 150, 175, 150, 175, 200, 125, 200 ]
])

PDFAnnotation.prototype.clearQuadPoints()¶

Clear the list of quadpoints for the annotation.

annotation.clearQuadPoints()

PDFAnnotation.prototype.addQuadPoint(quad)¶

Append a single quadpoint to the annotation.

Arguments:

quad (Quad) – The quadpoint to add.

annotation.addQuadPoint([1, 2, 3, 4, 5, 6, 7, 8])

Vertices¶

Polygon and polyline annotations consist of a sequence of vertices with a straight line between them. Those can be controlled by:

PDFAnnotation.prototype.hasVertices()¶

Returns whether the annotation is capable of supporting vertices.

Returns:: boolean

var hasVertices = annotation.hasVertices()

PDFAnnotation.prototype.getVertices()¶

Get the annotation vertices, represented as an array of points.

Returns:: Array of Point

var vertices = annotation.getVertices()

PDFAnnotation.prototype.setVertices(vertices)¶

Set the annotation vertices, represented as an array of points.

Arguments:

vertices (Array of Point)

annotation.setVertices([
        [0, 0],
        [10, 10],
        [20, 20]
])

PDFAnnotation.prototype.clearVertices()¶

Clear the list of vertices for the annotation.

annotation.clearVertices()

PDFAnnotation.prototype.addVertex(vertex)¶

Append a single vertex point to the annotation.

Arguments:

vertex (Point)

annotation.addVertex([0, 0])

Stamp image¶

PDFAnnotation.prototype.getStampImageObject()¶

only mutool run

If the annotation is a stamp annotation and it consists of an image, return the PDFObject representing that image.

Returns:: PDFObject | null

var pdfobj = annotation.getStampImageObject()

PDFAnnotation.prototype.setStampImageObject(imgobj)¶

only mutool run

Create an appearance stream containing the image passed as argument and set that as the normal appearance of the annotation.

Arguments:

imgobj (PDFObject) – PDFObject corresponding to the desired image.

annotation.setStampImageObject(imgobj)

PDFAnnotation.prototype.setStampImage(img)¶

only mutool run

Add the image passed as argument to the document as a PDF object, and pass a reference to that object to when setting the normal appearance of the stamp annotation.

Arguments:

img (Image) – The image to become the stamp annotations appearance.

annotation.setStampImage(img)

Intent¶

PDFAnnotation.prototype.hasIntent()¶

only mutool run

Returns whether the annotation is capable of supporting an intent.

Returns:: boolean

var hasIntent = annotation.hasIntent()

PDFAnnotation.prototype.getIntent()¶

Get the annotation intent, one of the values below:

“FreeTextCallout”
“FreeTextTypeWriter”
“LineArrow”
“LineDimension”
“PolyLineDimension”
“PolygonCloud”
“PolygonDimension”
“StampImage”
“StampSnapshot”

Returns:: string

var intent = annotation.getIntent()

PDFAnnotation.prototype.setIntent(intent)¶

Set the annotation intent.

Arguments:

intent (string) – Intent value, see getIntent() for permissible values.

annotation.setIntent("LineArrow")

Events¶

PDF annotations can have different appearances depending on whether the pointing device’s cursor is hovering over an annotation, or if the pointing device’s button is pressed.

PDF widgets, which is a type of annotation, may also have associated Javascript functions that are executed when certain events occur.

Therefore it is important to tell an PDFAnnotation when the pointing device’s cursor enters/exits an annotation, when it’s button is clicked, or when an annotation gains/loses input focus.

PDFAnnotation.prototype.eventEnter()¶

only mutool run

Trigger appearance changes and event handlers for when the pointing device’s cursor enters an annotation’s active area.

annot.eventEnter()

PDFAnnotation.prototype.eventExit()¶

only mutool run

Trigger appearance changes and event handlers for when the pointing device’s cursor exits an annotation’s active area.

annot.eventExit()

PDFAnnotation.prototype.eventDown()¶

only mutool run

Trigger appearance changes and event handlers for when the pointing device’s button is depressed within an annotation’s active area.

widget.eventDown()

PDFAnnotation.prototype.eventUp()¶

only mutool run

Trigger appearance changes and event handlers for when the pointing device’s button is released within an annotation’s active area.

widget.eventUp()

PDFAnnotation.prototype.eventFocus()¶

only mutool run

Trigger event handlers for when an annotation gains input focus.

widget.eventFocus()

PDFAnnotation.prototype.eventBlur()¶

only mutool run

Trigger event handlers for when an annotation loses input focus.

widget.eventBlur()

PDFAnnotation¶

Annotation Types¶

Constructors¶

Instance methods¶

Annotation attributes¶

Common¶

Rect¶

Rich contents¶

Color¶

Opacity¶

Quadding¶

Author¶

Border¶

Callout¶

Default Appearance¶

Filespec¶

Icon¶

Ink List¶

Interior Color¶

Line¶

Line Ending Styles¶

Line Leaders¶

Open¶

Popup¶

QuadPoints¶

Vertices¶

Stamp image¶

Intent¶

Events¶