Find #mupdf.js on Discord

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.

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

INSTANCE METHODS

getBounds()#

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

Returns:: Rect.

EXAMPLE

let bounds = annotation.getBounds()

run(device: Device, matrix: Matrix)#

Calls the device functions to draw the annotation.

Parameters:

device – Device.
matrix – Matrix.

EXAMPLE

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

toPixmap(matrix: Matrix, colorspace: ColorSpace, alpha: boolean = false)#

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

Parameters:

matrix – Matrix.
colorspace – ColorSpace.
alpha – boolean.

Returns:

Pixmap.

EXAMPLE

let pixmap = annotation.toPixmap(mupdfjs.Matrix.identity, mupdfjs.ColorSpace.DeviceRGB, true)

toDisplayList()#

Record the contents of the annotation into a DisplayList.

Returns:: DisplayList.

EXAMPLE

let displayList = annotation.toDisplayList()

getObject()#

Get the underlying PDFObject for an annotation.

Returns:: PDFObject.

EXAMPLE

let obj = annotation.getObject()

setAppearanceFromDisplayList(appearance: string | null, state: string | null, transform: Matrix, list: DisplayList)#

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

Parameters:

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.
list – DisplayList.

EXAMPLE

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

setAppearance(appearance: string | null, state: string | null, transform: Matrix, bbox: Rect, resources: any, contents: AnyBuffer)#

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.

Parameters:

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.
bbox – Rect.
resources – object. Resources object.
contents – string. Contents string.

EXAMPLE

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

update()#

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

EXAMPLE

annotation.update()

getHiddenForEditing()#

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

Returns:: boolean.

EXAMPLE

let hidden = annotation.getHiddenForEditing()

setHiddenForEditing(hidden: boolean)#

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

Parameters:: hidden – boolean.

EXAMPLE

annotation.setHiddenForEditing(true)

getType()#

Return the annotation type.

Returns:: string. See: Annotation types.

EXAMPLE

let type = annotation.getType()

getFlags()#

Get the annotation flags.

Returns:: number. Representaton of a bit-field of flags specified below.

EXAMPLE

var flags = annotation.getFlags();

setFlags(flags: number)#

Set the annotation flags.

Parameters:: flags – number. Representaton of a bit-field of flags specified below.

EXAMPLE

annotation.setFlags(4); // 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: string)#

Set the annotation contents.

Parameters:: text – string.

EXAMPLE

annotation.setContents("Hello World");

getColor()#

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

Returns:: Color.

EXAMPLE

var color = annotation.getColor();

setColor(color: Color)#

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

Parameters:: color – Color.

EXAMPLE

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

getOpacity()#

Get the annotation opacity.

Returns:: number. The opacity value.

EXAMPLE

var opacity = annotation.getOpacity();

setOpacity(opacity: number)#

Set the annotation opacity.

Parameters:: opacity – number. The opacity value.

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

Set the creation date.

Parameters:: date – Date. JavaScript Date object.

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

Set the modification date.

Parameters:: date – Date. JavaScript Date object.

EXAMPLE

annotation.setModificationDate(new Date());

getQuadding()#

Get the annotation quadding (justification).

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

EXAMPLE

var quadding = annotation.getQuadding();

setQuadding(value: number)#

Set the annotation quadding (justification).

Parameters:: value – number. 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: string)#

Set the annotation language.

Parameters:: language – string.

EXAMPLE

annotation.setLanguage("en");

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

hasRect()#

Checks the support for annotation bounding box.

Returns:: boolean.

EXAMPLE

var hasRect = annotation.hasRect();

getRect()#

Get the annotation bounding box.

Returns:: Rect.

EXAMPLE

var rect = annotation.getRect();

setRect(rect: Rect)#

Set the annotation bounding box.

Parameters:: rect – Rect.

EXAMPLE

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

getDefaultAppearance()#

Get the default text appearance used for free text annotations.

Returns:: {font:string, size:number, color:Color} Returns a default text appearance with the key/value pairs.

EXAMPLE

var appearance = annotation.getDefaultAppearance();

setDefaultAppearance(font: string, size: number, color: Color)#

Set the default text appearance used for free text annotations.

Parameters:

font – string (“Helv” = Helvetica, “TiRo” = Times New Roman, “Cour” = Courier).
size – number.
color – Color.

EXAMPLE

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

hasInteriorColor()#

Checks whether the annotation has support for an interior color.

Returns:: boolean.

EXAMPLE

var hasInteriorColor = annotation.hasInteriorColor();

getInteriorColor()#

Gets the annotation interior color.

Returns:: Color.

EXAMPLE

var interiorColor = annotation.getInteriorColor();

setInteriorColor(color: Color)#

Sets the annotation interior color.

Parameters:: color – Color.

EXAMPLE

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

hasAuthor()#

Checks whether the annotation has an author.

Returns:: boolean.

EXAMPLE

var hasAuthor = annotation.hasAuthor();

getAuthor()#

Gets the annotation author.

Returns:: string.

EXAMPLE

var author = annotation.getAuthor();

setAuthor(author: string)#

Sets the annotation author.

Parameters:: author – string.

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: PDFAnnotationLineEndingStyle, end: PDFAnnotationLineEndingStyle)#

Sets the line ending styles object.

Parameters:

start – PDFAnnotationLineEndingStyle.
end – PDFAnnotationLineEndingStyle.

EXAMPLE

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

hasIcon()#

Checks the support for annotation icon.

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

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.

Parameters:: name – string.

EXAMPLE

annotation.setIcon("Note");

hasLine()#

Checks the support for annotation line.

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:: Point[].

EXAMPLE

var line = annotation.getLine();

setLine(a: Point, b: Point)#

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

Parameters:

a – Point.
b – Point.

EXAMPLE

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

hasPopup()#

Checks the support for annotation popup.

Returns:: boolean.

EXAMPLE

var hasPopup = annotation.hasPopup();

getPopup()#

Get annotation popup rectangle.

Returns:: Rect.

EXAMPLE

var popupRect = annotation.getPopup();

setPopup(rect: Rect)#

Set annotation popup rectangle.

Parameters:: rect – Rect.

EXAMPLE

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

hasOpen()#

Checks the support for annotation open state.

Returns:: boolean.

EXAMPLE

var hasOpen = annotation.hasOpen();

getIsOpen()#

Get annotation open state.

Returns:: boolean.

EXAMPLE

var isOpen = annotation.getIsOpen();

setIsOpen(state: boolean)#

Set annotation open state.

Parameters:: state – boolean.

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

Checks support for the annotation file specification.

Returns:: boolean.

EXAMPLE

var hasFileSpec = annotation.hasFilespec();

getFilespec()#

Gets the file specification object.

Returns:: PDFObject File Specification Object.

EXAMPLE

var fileSpec = annotation.getFilespec();

setFilespec(fileSpec: PDFObject)#

Sets the file specification object.

Parameters:: fileSpec – PDFObject File Specification object.

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

Check support for the annotation border style.

Returns:: boolean.

EXAMPLE

var hasBorder = annotation.hasBorder();

getBorderStyle()#

Get the annotation border style.

Returns:: string.

EXAMPLE

var borderStyle = annotation.getBorderStyle();

setBorderStyle(style: string)#

Set the annotation border style.

Arg:: string.

EXAMPLE

annotation.setBorderStyle("Dashed");

getBorderWidth()#

Get the border width in points.

Returns:: number.

EXAMPLE

var w = annotation.getBorderWidth();

setBorderWidth(width: number)#

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

Parameters:: width – number.

EXAMPLE

annotation.setBorderWidth(1.5);

getBorderDashCount()#

Returns the number of items in the border dash pattern.

Returns:: number.

EXAMPLE

var dashCount = annotation.getBorderDashCount();

getBorderDashItem(idx: number)#

Returns the length of dash pattern item idx.

Parameters:: idx – number. Item index.
Returns:: number.

EXAMPLE

var length = annotation.getBorderDashItem(0);

setBorderDashPattern(list: number[])#

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.

Parameters:: dashPattern – number[].

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

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

Parameters:: length – number.

EXAMPLE

annotation.addBorderDashItem(10.0);

hasBorderEffect()#

Check support for annotation border effect.

Returns:: boolean.

EXAMPLE

var hasEffect = annotation.hasBorderEffect();

getBorderEffect()#

Get the annotation border effect.

Returns:: string.

EXAMPLE

var effect = annotation.getBorderEffect();

setBorderEffect(effect: string)#

Set the annotation border effect.

Arg:: string.

EXAMPLE

annotation.setBorderEffect("None");

getBorderEffectIntensity()#

Get the annotation border effect intensity.

Returns:: number.

EXAMPLE

var intensity = annotation.getBorderEffectIntensity();

setBorderEffectIntensity(intensity: number)#

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

Arg:: number.

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

Check support for the annotation 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:: Point[][].

EXAMPLE

var inkList = annotation.getInkList();

setInkList(inkList: Point[][])#

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

Parameters:: inkList – Point[][].

EXAMPLE

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

clearInkList()#

Clear the list of ink strokes for the annotation.

EXAMPLE

annotation.clearInkList();

addInkListStroke()#

Add a new empty stroke to the ink annotation.

EXAMPLE

annotation.addInkListStroke();

addInkListStrokeVertex(v: Point)#

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

Parameters:: v – Point.

EXAMPLE

annotation.addInkListStrokeVertex([0,0]);

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

hasQuadPoints()#

Check support for the annotation 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:: Quad[].

EXAMPLE

var quadPoints = annotation.getQuadPoints();

setQuadPoints(quadList: Quad[])#

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

Parameters:: quadList – Quad[].

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 QuadPoints for the annotation.

EXAMPLE

annotation.clearQuadPoints();

addQuadPoint(quad: Quad)#

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

Parameters:: quad – Quad

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

Check support for the 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:: Point[].

EXAMPLE

var vertices = annotation.getVertices();

setVertices(vertices:Point[])#

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

Parameters:: vertices – Point[].

EXAMPLE

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

clearVertices()#

Clear the list of vertices for the annotation.

EXAMPLE

annotation.clearVertices();

addVertex(vertex: Point)#

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

Parameters:: vertex – Point.

EXAMPLE

annotation.addVertex([0,0]);

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.

setLineLeader(v: number)#

Sets the line leader length.

Parameters:: 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.

Note

Setting a value of 0 effectivley removes the line leader.

getLineLeader()#

Gets the line leader length.

Returns:: number

setLineLeaderExtension(v: number)#

Sets the line leader extension.

Parameters:: 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.

Note

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

getLineLeaderExtension()#

Gets the line leader extension.

Returns:: number

setLineLeaderOffset(v: number)#

Sets the line leader offset.

Parameters:: 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.

Note

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

getLineLeaderOffset()#

Gets the line leader offset.

Returns:: number

setLineCaption(on: boolean)#

Sets whether line caption is enabled or not.

Parameters:: on – boolean.

Note

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

getLineCaption()#

Returns whether the line caption is enabled or not.

Returns:: boolean.

setLineCaptionOffset(point: Point)#

Sets any line caption offset.

Parameters:: point – Point. 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.

Note

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

getLineCaptionOffset()#

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

Returns:: Point.

Callouts#

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

hasCallout()#

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

Returns:: boolean.

setCalloutLine(line: Point[])#

Takes an array of 2 or 3 points.

Parameters:: points – Point[].

getCalloutLine()#

Returns the array of points.

Returns:: Point[].

setCalloutPoint(p: Point)#

Takes a point where the callout should point to.

Parameters:: points – Point.

getCalloutPoint()#

Returns the callout point.

Returns:: Point.

setCalloutStyle(style: PDFAnnotationLineEndingStyle)#

Sets the style of the callout line.

Parameters:: style – PDFAnnotationLineEndingStyle. A line ending style.

getCalloutStyle()#

Returns the callout style.

Returns:: PDFAnnotationLineEndingStyle.

Redactions#

Redactions are a special type of annotation used to permanently remove (or “redact”) content from a PDF.

To create a redaction annotation use the addRedaction() method on a PDFPage instance.

Once redactions are added to a page you can apply them, which is an irreversable action, thus it is a two step process as follows:

// create a redaction annotation
let redactionAnnotation = page.addRedaction(rect)
// apply redaction to the annotation with options
redactionAnnotation.applyRedaction(true, mupdfjs.PDFPage.REDACT_IMAGE_NONE);

applyRedaction(blackBoxes: boolean = true, imageMethod: number = PDFPage.REDACT_IMAGE_PIXELS)#

Applies redaction to the annotation.

Parameters:

blackBoxes – boolean. Whether to use black boxes on the redaction or not. (Default: true)
imageMethod – number. Used to declare how to redact image content affected by the redaction rectangle area. (Default: PDFPage.REDACT_IMAGE_PIXELS).

Image redaction variable	Description
`PDFPage.REDACT_IMAGE_NONE`	Do not redact images
`PDFPage.REDACT_IMAGE_REMOVE`	Redact entire images
`PDFPage.REDACT_IMAGE_PIXELS`	Redact just the covered pixels

Note

Redactions are secure as they remove the affected content completely.

EXAMPLE

annotation.applyRedaction(true, mupdfjs.PDFPage.REDACT_IMAGE_REMOVE);

Code samples

Code samples are in TypeScript and assume that the following requirements are defined in your TypeScript file header as follows:

import * as fs from "fs"
import * as mupdfjs from "mupdf/mupdfjs"

Was this page helpful?

PDFAnnotation#

Line Leaders#

Callouts#

Redactions#

Are you a human?