Supported Annotation Flags in the PDF Spec and PSPDFKit

Every annotation in a PDF document can specify flags that further define the annotation’s behavior and capabilities.

This post will give you an overview of the annotation flags defined in the PDF specification. Then, you’ll find out which flags PSPDFKit for Web supports.

Annotation Flags in the PDF Specification

Here’s how the latest PDF spec defines annotation flags:

• Print — When this flag is set to true, an annotation should be printable, unless the hidden flag is also set. If it’s false, the annotation is never printable, regardless of any other flag. If an annotation doesn’t contain an appearance stream, this flag will be ignored.

• Invisible — Applies only to unknown annotations, meaning they don’t belong to one of the standard annotation types and no annotation handler is available. If set to true, the annotation isn’t rendered and isn’t printed, even if it has the noPrint flag set to false. If the Invisible flag is set to false, render such an unknown annotation using an appearance stream specified by its appearance dictionary, if any.

• Hidden — An annotation with the hidden flag set to true won’t be rendered and can’t be interacted with.

• noZoom — If an annotation has this flag set to true, scaling the annotation’s appearance to match the page zoom isn’t allowed.

• NoRotate — An annotation with the noRotate flag set to true won’t change its rotation when a page rotation is specified. Instead, it’ll be locked to the top-left corner of its bounding box.

• noView — An annotation with the NoView flag won’t be rendered in the UI. It might still be printable.

• ReadOnly — An annotation with this flag set to true won’t interact with the user. The annotation may be rendered and printed (according to the NoView and Print flags), but it won’t respond to mouse clicks or change its appearance according to mouse inputs. This flag is ignored for widget annotations, as the ReadOnly flag of the associated form field supersedes it. It’s also ignored by link annotations.

• Locked — If set to true, this doesn’t allow the annotation to be deleted. Nor does it allow its properties — like position, size, and color — to be modified by the user. However, this flag doesn’t restrict changes to the annotation’s contents, such as the text of a text annotation.

• ToggleNoView — When true, it inverts the interpretation of the NoView flag, meaning that annotations will be visible when hovered or when it’s selected.

• LockedContents — If set to true, this doesn’t allow the contents of the annotation to be modified by the user. This flag doesn’t restrict deletion of the annotation or changes to other annotation properties, such as position and size, meaning that, for example, a text annotation can have its position, color, and size modified, but not its text.

Annotation Flags Supported by PSPDFKit for Web

PSPDFKit for Web 2023.5.0 supports the following flags:

• noView — Defaults to false.

• noPrint — By default, we assign print: true to annotations, but this flag allows customers to disable printing.

• noRotate — Currently only enabled for note annotations, defaults to false.

• readOnly — Defaults to false.

• locked — Supported by all annotation types except widget annotations, defaults to false.

• lockedContents — Supported by all annotation types except widget annotations, defaults to false.

Using Annotation Flags

Here’s how to create a new annotation with the readOnly and noPrint flags set to true:

const annotation = new PSPDFKit.Annotations.TextAnnotation({
	pageIndex: 0,
	text: { format: 'plain', value: 'Welcome to\nPSPDFKit' },
	font: 'Helvetica',
	isBold: true,
	horizontalAlign: 'center',
	boundingBox: new PSPDFKit.Geometry.Rect({
		left: 10,
		top: 20,
		width: 30,
		height: 40,
	}),
	fontColor: PSPDFKit.Color.RED,
	readOnly: true,
	noPrint: true,
});

Here’s how to set the locked and lockedContents flags on an annotation that already exists:

// Create a new text annotation.
let annotation = new PSPDFKit.Annotations.TextAnnotation({
	pageIndex: 0,
	text: { format: 'plain', value: 'Welcome to\nPSPDFKit' },
	font: 'Helvetica',
	isBold: true,
	horizontalAlign: 'center',
	boundingBox: new PSPDFKit.Geometry.Rect({
		left: 10,
		top: 20,
		width: 30,
		height: 40,
	}),
	fontColor: PSPDFKit.Color.RED,
	noPrint: true,
});

await instance.create(annotation);

// Set flags on the text annotation.
annotation = annotation.set('locked', true).set('lockedContents', true);

await instance.update(annotation);

Conclusion

In this post, you learned all about annotation flags, and you saw how to use PSPDFKit to apply them to the annotations in your document.

If you want to learn more about PSPDFKit, you can request a free trial of our SDK, or browse our demo page to see what our API is capable of.