Skip to content
Back to top

# 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)

### Popup

PDFAnnotation.prototype.hasPopup()

  only mutool run

  Returns whether the annotation is capable of supporting a popup.

  Returns:

    boolean

      var hasPopup = annotation.hasPopup()

PDFAnnotation.prototype.getPopup()

  Get annotation popup rectangle.

  Returns:

    Rect

      var popupRect = annotation.getPopup()

PDFAnnotation.prototype.setPopup(rect)

  Set annotation popup rectangle.

  Arguments:

    - rect (`Rect`) – The desired area where the popup should appear.

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

### 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()