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. Finally redaction annotations can be applied to a PDFPage, destructively removing content from the page.

To get the annotations on a page see: PDFPage getAnnotations(), to create an annotation see: PDFPage createAnnotation().

Instance methods

getBounds()

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

Returns:

[ulx,uly,lrx,lry] Rectangle.

EXAMPLE

var bounds = annotation.getBounds();
run(device, transform)

Calls the device functions to draw the annotation.

Arguments:
  • deviceDevice.

  • transform[a,b,c,d,e,f]. The transform matrix.

EXAMPLE

annotation.run(device, mupdf.Matrix.identity);
toPixmap(transform, colorspace, alpha)

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

Arguments:
  • transform[a,b,c,d,e,f]. The transform matrix.

  • colorspaceColorSpace.

  • alphaBoolean.

Returns:

Pixmap.

EXAMPLE

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

Record the contents of the annotation into a DisplayList.

Returns:

DisplayList.

EXAMPLE

var displayList = annotation.toDisplayList();
getObject()

Get the underlying PDFObject for an annotation.

Returns:

PDFObject.

EXAMPLE

var obj = annotation.getObject();
process(processor)

mutool only

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

Arguments:
  • processor – User defined function.

EXAMPLE

annotation.process(processor);
setAppearance(appearance, state, transform, displayList)

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

Arguments:
  • appearanceString Appearance stream (“N”, “R” or “D”).

  • stateString 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[a,b,c,d,e,f]. The transform matrix.

  • displayListDisplayList.

EXAMPLE

annotation.setAppearance("N", null, mupdf.Matrix.identity, displayList);
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:
  • appearanceString Appearance stream (“N”, “R” or “D”).

  • stateString 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[a,b,c,d,e,f]. The transform matrix.

  • bbox[ulx,uly,lrx,lry] Rectangle.

  • resources – Resources object.

  • contents – Contents string.

EXAMPLE

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

Set a stamp annotation’s appearance to that of an image.

Arguments:
  • imageImage containing the desired appearance.

EXAMPLE

var img = new Image("photo.jpg");
annotation.setAppearance(img);

Appearance stream values

Value

Description

N

normal appearance

R

roll-over appearance

D

down (pressed) appearance

update()

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

EXAMPLE

annotation.update();
getHot()

mutool only

Get the annotation as being hot, i.e. that the pointer is hovering over the annotation.

Returns:

Boolean.

EXAMPLE

annotation.getHot();
setHot(hot)

mutool only

Set the annotation as being hot, i.e. that the pointer is hovering over the annotation.

Arguments:
  • hotBoolean.

EXAMPLE

annotation.setHot(true);
getHiddenForEditing()

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

Returns:

Boolean.

EXAMPLE

var hidden = annotation.getHiddenForEditing();
setHiddenForEditing(hidden)

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

Arguments:
  • hiddenBoolean.

EXAMPLE

annotation.setHiddenForEditing(true);
getType()

Return the annotation type.

Returns:

String Annotation type.

EXAMPLE

var type = annotation.getType();
getFlags()

Get the annotation flags.

Returns:

Integer representaton of a bit-field of flags specified below.

EXAMPLE

var flags = annotation.getFlags();
setFlags(flags)

Set the annotation flags.

Arguments:
  • flagsInteger representaton of a bit-field of flags specified below.

EXAMPLE

annotation.setFlags(8); // Clears all other flags and sets NoZoom.

Annotation flags

Bit position

Name

1

Invisible

2

Hidden

3

Print

4

NoZoom

5

NoRotate

6

NoView

7

ReadOnly

8

Locked

9

ToggleNoView

10

LockedContents

getContents()

Get the annotation contents.

Returns:

String.

EXAMPLE

var contents = annotation.getContents();
setContents(text)

Set the annotation contents.

Arguments:
  • textString.

EXAMPLE

annotation.setContents("Hello World");
getBorder()

mutool only

Get the annotation border line width in points.

Returns:

Float.

EXAMPLE

var border = annotation.getBorder();
setBorder(width)

mutool only

Set the annotation border line width in points. Use setBorderWidth() to avoid removing the border effect.

Arguments:
  • widthFloat Border width.

EXAMPLE

annotation.setBorder(1.0);
getColor()

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

Returns:

The color value.

EXAMPLE

var color = annotation.getColor();
setColor(color)

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

Arguments:

EXAMPLE

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

Get the annotation opacity.

Returns:

The opacity value.

EXAMPLE

var opacity = annotation.getOpacity();
setOpacity(opacity)

Set the annotation opacity.

Arguments:

EXAMPLE

annotation.setOpacity(0.5);
getCreationDate()

Get the annotation creation date as a JavaScript Date object.

Returns:

Date.

EXAMPLE

var date = annotation.getCreationDate();
setCreationDate(date)

Set the creation date.

Arguments:
  • dateDate.

EXAMPLE

annotation.setCreationDate(new Date());
getModificationDate()

Get the annotation modification date as a JavaScript Date object.

Returns:

Date.

EXAMPLE

var date = annotation.getModificationDate();
setModificationDate(date)

Set the modification date.

Arguments:
  • dateDate.

EXAMPLE

annotation.setModificationDate(new Date());
getQuadding()

Get the annotation quadding (justification).

Returns:

Quadding value, 0 for left-justified, 1 for centered, 2 for right-justified.

EXAMPLE

var quadding = annotation.getQuadding();
setQuadding(value)

Set the annotation quadding (justification).

Arguments:
  • valueNumber. Quadding value, 0 for left-justified, 1 for centered, 2 for right-justified.

EXAMPLE

annotation.setQuadding(1);
getLanguage()

Get the annotation language (or get the inherited document language).

Returns:

String.

EXAMPLE

var language = annotation.getLanguage();
setLanguage(language)

Set the annotation language.

Arguments:
  • languageString.

EXAMPLE

annotation.setLanguage("en");

These properties are only present for some annotation types, so support for them must be checked before use.

hasRect()

Returns whether the annotation is capable of supporting a bounding box.

Returns:

Boolean.

EXAMPLE

var hasRect = annotation.hasRect();
getRect()

Get the annotation bounding box.

Returns:

Array. [ulx,uly,lrx,lry] Rectangle.

EXAMPLE

var rect = annotation.getRect();
setRect(rect)

Set the annotation bounding box.

Arguments:
  • rectArray. [ulx,uly,lrx,lry] Rectangle.

EXAMPLE

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

Get the default text appearance used for free text annotations.

Returns:

{font:String, size:Integer, color:[r,g,b]} Returns a default text appearance with the key/value pairs.

EXAMPLE

var appearance = annotation.getDefaultAppearance();
setDefaultAppearance(font, size, color)

Set the default text appearance used for free text annotations.

Arguments:
  • fontString (“Helv” = Helvetica, “TiRo” = Times New Roman, “Cour” = Courier).

  • sizeInteger.

  • colorArray. The color value.

EXAMPLE

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

Returns whether the annotation has support for an interior color.

Returns:

Boolean.

EXAMPLE

var hasInteriorColor = annotation.hasInteriorColor();
getInteriorColor()

Gets the annotation interior color.

Returns:

The color value.

EXAMPLE

var interiorColor = annotation.getInteriorColor();
setInteriorColor(color)

Sets the annotation interior color.

Arguments:

EXAMPLE

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

Returns whether the annotation has support for an author.

Returns:

Boolean.

EXAMPLE

var hasAuthor = annotation.hasAuthor();
getAuthor()

Gets the annotation author.

Returns:

String.

EXAMPLE

var author = annotation.getAuthor();
setAuthor(author)

Sets the annotation author.

Arguments:
  • authorString.

EXAMPLE

annotation.setAuthor("Jane Doe");
hasLineEndingStyles()

Checks the support for line ending styles.

Returns:

Boolean.

EXAMPLE

var hasLineEndingStyles = annotation.hasLineEndingStyles();
getLineEndingStyles()

Gets the line ending styles object.

Returns:

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

EXAMPLE

var lineEndingStyles = annotation.getLineEndingStyles();
setLineEndingStyles(start, end)

Sets the line ending styles object.

Arguments:
  • startString.

  • endString.

EXAMPLE

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

Line ending names

“None”

“Square”

“Circle”

“Diamond”

“OpenArrow”

“ClosedArrow”

“Butt”

“ROpenArrow”

“RClosedArrow”

“Slash”

Line Leaders

In a PDF line annotation, “line leaders” refer to visual elements that can be added to the endpoints of a line annotation to enhance its appearance or meaning.

Leader lines explained
setLineLeader(ll)

mutool only

Sets the line leader length.

Arguments:
  • llNumber. 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.

Note

Setting a value of 0 effectivley removes the line leader.

getLineLeader()

mutool only

Gets the line leader length.

Returns:

Number

setLineLeaderExtension(lle)

mutool only

Sets the line leader extension.

Arguments:
  • lleNumber. A non-negative number representing the length of leader line extensions that extend from the line proper 180 degrees from the leader lines.

Note

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

getLineLeaderExtension()

mutool only

Gets the line leader extension.

Returns:

Number

setLineLeaderOffset(llo)

mutool only

Sets the line leader offset.

Arguments:
  • lloNumber. 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.

Note

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

getLineLeaderOffset()

mutool only

Gets the line leader offset.

Returns:

Number

setLineCaption(enable)

mutool only

Sets whether line caption is enabled or not.

Arguments:
  • enableBoolean.

Note

When line captions are enabled then using the setContents() method on the Line will graphically render the caption contents onto the line.

getLineCaption()

mutool only

Returns whether the line caption is enabled or not.

Returns:

Boolean.

setLineCaptionOffset(point)

mutool only

Sets any line caption offset.

Arguments:
  • pointArray. A point, [x, y], specifying the offset of the caption text from its normal position. The first value 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 second value 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.

Offset caption explained

Note

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

getLineCaptionOffset()

mutool only

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

Returns:

Array.


Callouts

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

Callout annotation
hasCallout()

mutool only

Returns whether the annotation is capable of supporting a callout or not.

Returns:

Boolean.

setCalloutLine(points)

mutool only

Takes an array of 2 or 3 points.

Arguments:
  • points – [ [x1, y1], [x2, y2], [x3, y3]? ].

getCalloutLine()

mutool only

Returns the array of points.

Returns:

[ [x1, y1], [x2, y2], [x3, y3]? ].

setCalloutPoint(point)

mutool only

Takes a point where the callout should point to.

Arguments:
  • points[x,y].

getCalloutPoint()

mutool only

Returns the callout point.

Returns:

[x,y].

setCalloutStyle(style)

mutool only

Sets the style of the callout line.

Arguments:
getCalloutStyle()

mutool only

Returns the callout style.

Returns:

String.


hasIcon()

Returns whether the annotation is capable of supporting an icon or not.

Returns:

Boolean.

EXAMPLE

var hasIcon = annotation.hasIcon();
getIcon()

Gets the annotation icon name, either one of the standard icon names, or something custom.

Returns:

String.

EXAMPLE

var icon = annotation.getIcon();
setIcon(name)

Sets the annotation icon name, either one of the standard icon names, or something custom. Note that standard icon names can be used to resynthesize the annotation apperance, but custom names cannot.

Arguments:
  • nameString.

EXAMPLE

annotation.setIcon("Note");

Icon type

Icon name

File attachment

“Graph”

“PaperClip”

“PushPin”

“Tag”

Sound

“Mic”

“Speaker”

Stamp

“Approved”

“AsIs”

“Confidential”

“Departmental”

“Draft”

“Experimental”

“Expired”

“Final”

“ForComment”

“ForPublicRelease”

“NotApproved”

“NotForPublicRelease”

“Sold”

“TopSecret”

Text

“Comment”

“Help”

“Insert”

“Key”

“NewParagraph”

“Note”

“Paragraph”

hasLine()

Returns whether the annotation is capable of supporting a line or not.

Returns:

Boolean.

EXAMPLE

var hasLine = annotation.hasLine();
getLine()

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

Returns:

[[x,y],...].

EXAMPLE

var line = annotation.getLine();
setLine(endpoints)

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

Arguments:
  • endpoint1[x,y].

  • endpoint2[x,y].

EXAMPLE

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

Returns whether the annotation is capable of supporting a popup or not.

Returns:

Boolean.

EXAMPLE

var hasPopup = annotation.hasPopup();
getPopup()

Get annotation popup rectangle.

Returns:

[ulx,uly,lrx,lry] Rectangle.

EXAMPLE

var popupRect = annotation.getPopup();
setPopup(rect)

Set annotation popup rectangle.

Arguments:

EXAMPLE

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

Returns whether the annotation is capable of supporting an open state or not.

Returns:

Boolean.

EXAMPLE

var hasOpen = annotation.hasOpen();
getIsOpen()

Get annotation open state.

Returns:

Boolean.

EXAMPLE

var isOpen = annotation.getIsOpen();
setIsOpen(state)

Set annotation open state.

Arguments:
  • stateBoolean.

EXAMPLE

annotation.setIsOpen(true);

Note

“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.

hasFilespec()

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

Returns:

Boolean.

EXAMPLE

var hasFileSpec = annotation.hasFilespec();
getFilespec()

Gets the file specification object.

Returns:

Object File Specification Object.

EXAMPLE

var fileSpec = annotation.getFilespec(true);
setFilespec(fileSpecObject)

Sets the file specification object.

Arguments:

EXAMPLE

annotation.setFilespec({filename:"my_file.pdf",
                        mimetype:"application/pdf",
                        size:1000,
                        creationDate:date,
                        modificationDate:date});

The border drawn around some annotations can be controlled by:

hasBorder()

Returns whether the annotation is capable of supporting border style.

Returns:

Boolean.

EXAMPLE

var hasBorder = annotation.hasBorder();
getBorderStyle()

Get the annotation border style, either of “Solid” or “Dashed”.

Returns:

String.

EXAMPLE

var borderStyle = annotation.getBorderStyle();
setBorderStyle(style)

Set the annotation border style, either of “Solid” or “Dashed”.

Arg:

String.

EXAMPLE

annotation.setBorderStyle("Dashed");
getBorderWidth()

Get the border width in points.

Returns:

Float.

EXAMPLE

var w = annotation.getBorderWidth();
setBorderWidth(width)

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

Arguments:
  • widthFloat.

EXAMPLE

annotation.setBorderWidth(1.5);
getBorderDashCount()

Returns the number of items in the border dash pattern.

Returns:

Integer.

EXAMPLE

var dashCount = annotation.getBorderDashCount();
getBorderDashItem(i)

Returns the length of dash pattern item i.

Arguments:
  • iInteger Item index.

Returns:

Float.

EXAMPLE

var length = annotation.getBorderDashItem(0);
setBorderDashPattern(dashPattern)

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 – [Float, Float, ….].

EXAMPLE

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

Clear the entire border dash pattern for an annotation.

EXAMPLE

annotation.clearBorderDash();
addBorderDashItem(length)

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

Arguments:
  • lengthFloat.

EXAMPLE

annotation.addBorderDashItem(10.0);

Annotations that have a border effect allows the effect to be controlled by:

hasBorderEffect()

Returns whether the annotation is capable of supporting border effect.

Returns:

Boolean.

EXAMPLE

var hasEffect = annotation.hasBorderEffect();
getBorderEffect()

Get the annotation border effect, either of “None” or “Cloudy”.

Returns:

String.

EXAMPLE

var effect = annotation.getBorderEffect();
setBorderEffect(effect)

Set the annotation border effect, either of “None” or “Cloudy”.

Arg:

String.

EXAMPLE

annotation.setBorderEffect("None");
getBorderEffectIntensity()

Get the annotation border effect intensity.

Returns:

Float.

EXAMPLE

var intensity = annotation.getBorderEffectIntensity();
setBorderEffectIntensity(intensity)

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

Arg:

Float.

EXAMPLE

annotation.setBorderEffectIntensity(1.5);

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

hasInkList()

Returns whether the annotation is capable of supporting ink list.

Returns:

Boolean.

EXAMPLE

var hasInkList = annotation.hasInkList();
getInkList()

Get the annotation ink list, represented as an array of strokes, each an array of points each an array of its X/Y coordinates.

Returns:

[...].

EXAMPLE

var inkList = annotation.getInkList();
setInkList(inkList)

Set the annotation ink list, represented as an array of strokes, each an array of points each an array of its X/Y coordinates.

Arg:

[...].

EXAMPLE

annotation.setInkList([
                          [
                              [0,0]
                          ],
                          [
                              [10,10], [20,20], [30,30]
                          ]
                      ]);
clearInkList()

Clear the list of ink strokes for the annotation.

EXAMPLE

annotation.clearInkList();
addInkList(stroke)

To the list of strokes, append a stroke, represented as an array of vertices each an array of its X/Y coordinates.

Arguments:
  • stroke[].

EXAMPLE

annotation.addInkList(
                        [
                            [0,0]
                        ],
                        [
                            [10,10], [20,20], [30,30]
                        ]
                     );
addInkListStroke()

Add a new empty stroke to the ink annotation.

EXAMPLE

annotation.addInkListStroke();
addInkListStrokeVertex(vertex)

Append a vertex to end of the last stroke in the ink annotation. The vertex is an array of its X/Y coordinates.

Arguments:
  • vertex[...].

EXAMPLE

annotation.addInkListStrokeVertex([0,0]);

Text markup and redaction annotations consist of a set of quadadrilaterals controlled by:

hasQuadPoints()

Returns whether the annotation is capable of supporting quadpoints.

Returns:

Boolean.

EXAMPLE

var hasQuadPoints = annotation.hasQuadPoints();
getQuadPoints()

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

Returns:

[...].

EXAMPLE

var quadPoints = annotation.getQuadPoints();
setQuadPoints(quadPoints)

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

Arguments:
  • quadPoints[...].

EXAMPLE

annotation.setQuadPoints([
                            [1,2,3,4,5,6,7,8],
                            [1,2,3,4,5,6,7,8],
                            [1,2,3,4,5,6,7,8]
                        ]);
clearQuadPoints()

Clear the list of quad points for the annotation.

EXAMPLE

annotation.clearQuadPoints();
addQuadPoint(quadpoint)

Append a single quad point as an array of 8 elements, where each pair are the X/Y coordinates of a corner of the quad.

Arguments:
  • quadpoint[].

EXAMPLE

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

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

hasVertices()

Returns whether the annotation is capable of supporting annotation vertices.

Returns:

Boolean.

EXAMPLE

var hasVertices = annotation.hasVertices();
getVertices()

Get the annotation vertices, represented as an array of vertices each an array of its X/Y coordinates.

Returns:

[...].

EXAMPLE

var vertices = annotation.getVertices();
setVertices(vertices)

Set the annotation vertices, represented as an array of vertices each an array of its X/Y coordinates.

Arguments:
  • vertices[...].

EXAMPLE

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

Clear the list of vertices for the annotation.

EXAMPLE

annotation.clearVertices();
addVertex(vertex)

Append a single vertex as an array of its X/Y coordinates.

Arguments:
  • vertex[...].

EXAMPLE

annotation.addVertex([0,0]);
applyRedaction(blackBoxes, imageMethod)

Applies redaction to the annotation.

Arguments:
  • blackBoxesBoolean Whether to use black boxes at each redaction or not.

  • imageMethodInteger. 0 for no redactions, 1 to redact entire images, 2 for redacting just the covered pixels.

Note

Redactions are secure as they remove the affected content completely.

EXAMPLE

annotation.applyRedaction(true, 1);