Annotations

Annotation Hierarchy

The abstract Annotation class is the base for all PDF annotations. All annotations are positioned on a Page at a Rectangle and are added via page.getAnnotations().add(annotation).

WidgetAnnotation

WidgetAnnotation represents a form widget. Appearance is controlled through AppearanceCharacteristics, which exposes setBorder(), setBackground(), setRotate(), and setCaption().

try (Document doc = new Document()) {
    Page page = doc.getPages().add();
    WidgetAnnotation w = new WidgetAnnotation(page, new Rectangle(0, 0, 100, 50));
    w.getCharacteristics().setBorder(Color.fromRgb(1, 0, 0));
    w.getCharacteristics().setCaption("Submit");
    page.getAnnotations().add(w);
    doc.save("annotated.pdf");
}

FreeTextAnnotation

FreeTextAnnotation displays a text callout at a specified location. It accepts a DefaultAppearance to set the font, size, and color of the annotation text.

DefaultAppearance da = new DefaultAppearance("Helv", 12, Color.BLACK);
FreeTextAnnotation fta = new FreeTextAnnotation(page,
    new Rectangle(50, 50, 200, 100), da);
fta.setContents("Review comment here");
page.getAnnotations().add(fta);

setCallout(double[][]) sets a three-point callout line for the annotation. getIntent() returns the annotation’s FreeTextIntent value.

Markup Annotations

HighlightAnnotation and UnderlineAnnotation mark text spans with quad points. The getQuadPoints() method returns an 8-element array defining the four corners of the marked region.

HighlightAnnotation h = new HighlightAnnotation(page,
    new Rectangle(100, 200, 300, 220));
page.getAnnotations().add(h);

CircleAnnotation and CaretAnnotation

CircleAnnotation draws an ellipse at the given rectangle; CaretAnnotation marks an insertion point in text. Both extend Annotation and share the same color and border properties.

Flattening Annotations

Use PdfAnnotationEditor.flattenAnnotations() to merge all annotations into the page content stream, making them non-editable.