PDFOne (for Java)
Create, edit, view, print & enhance PDF documents and forms in Java SE/EE

Compatibility

J2SE J2EE Windows Linux Mac (OS X)

Home » Newsletter » February 2008

By Santhanam L.

Annotations and forms are two popular interactive features available in the PDF format. While forms or AcroForms allow you to gather information from the user interactively, annotations enable you to display text, image, shape, animation, sound or video in an interactive manner.

In this article, you will learn about creating and editing various kinds of annotations. Forms will be covered next month.

PDF Annotations

Annotations are of several types and each type behaves in a specific way. However, they all share some common properties.

When an annotation is created, it is placed on a particular page at a particular location. This location is known as the annotation rectangle.

Many annotation types implement a popup window. When the user interacts with the annotation in the viewer application (think Adobe® Reader), the popup window opens^* and displays more text information. This additional information is available as the title, subject, and content of the popup window.

Each annotation has a set of attributes known as annotation attributes, which define how the annotation is displayed by a viewer application, allowed to interact with a user, and printed or processed by the viewer or another application.

Creating Annotations

When you create an annotation in PDFOne Java, you can specify common properties of the annotation such as annotation rectangle, popup window and annotation attributes, and also other features specific to the annotation type.

PDFOne Java defines a base class PdfAnnot for annotations in general. Individual annotation types are represented by classes that are derived from this base class. The derived classes offer properties and methods that are unique to that annotation type.

Class	Type	Description
PdfTextAnnot	Text Annotation	A "sticky note" icon is displayed in the annotation rectangle. When selected, it can display a popup window.
PdfLinkAnnot	Link Annotation	A link is displayed in the annotation rectangle (usually placed around some text). When selected by the user, the viewer application can execute a go-to action, remote go-to action, URI action, launch action, JavaScript action or named action. A highlight mode can be specified to describe how the annotation should be displayed when the user presses the mouse over the annotation link.
PdfFreeTextAnnot	Free Text Annotation	Text is displayed directly on the page inside a box. A callout line can be associated with the box.
PdfStampAnnot	Rubber Stamp Annotation	A rubber stamp-like impression is displayed in the annotation rectangle with text such as "DRAFT", "CONFIDENTIAL", and "APPROVED"

Here is a code snippet that shows how to create various types of annotations.

// Create an empty PDF document
PdfDocument doc1 = new PdfDocument();

// Create an A4-size page
PdfPage pg1 = new PdfPage(PdfPageSize.A4,
                          1, 1, 1, 1,
                          PdfMeasurement.MU_INCHES);
// Add the page to document
doc1.add(pg1);

// Add text annotation
PdfTextAnnot ta1 = new PdfTextAnnot(
                         1, // x-coordinate
			 1, // y-coordinate
			 Color.ORANGE);
ta1.setTitle("Text annotation");
ta1.setSubject("Demo 1");
ta1.setContents("This is a text annotation.");
pg1.addAnnotation(ta1);

// Add link annotation
PdfRect rct1 = new PdfRect(3, 1, 1.5, 0.5);
pg1.writeText("Click here! This is a link annotation.", rct1);
PdfLinkAnnot la1 =
   new PdfLinkAnnot(
         rct1, // Annotation rectangle
         Color.BLUE);
la1.addActionURI("www.gnostice.com");
la1.setHighlightMode(PdfLinkAnnot.HIGHLIGHT_MODE_PUSH);
pg1.addAnnotation(la1);

// Add stamp annotation
PdfStampAnnot sa1 =
   new PdfStampAnnot(
         // Annotation rectangle
         new PdfRect(3, 3, 1.5, 1),
         // Subject
	 "Demo 3",
	 // Contents
	 "This is a rubber stamp annotation.",
	 // Title
	 "Rubber stamp annotation",
	 Color.LIGHT_GRAY);
sa1.setStamp(PdfStampAnnot.FOR_COMMENT);
pg1.addAnnotation(sa1);

pg1.setMeasurementUnit(PdfMeasurement.MU_POINTS);

// Add free text annotation
PdfFreeTextAnnot fta1 =
  new PdfFreeTextAnnot(
           new PdfRect(75, 150, 150, 30),
           "Demo 4", 
           "This is a free text annotation.", 
           "Free text annotation",
           PdfAnnot.FLAG_PRINT, 
           Color.YELLOW);
double cl1[] = {225, 180, 200, 180, 150, 200};
fta1.setCalloutLine(cl1);
fta1.setIntent(PdfFreeTextAnnot.INTENT_FREETEXT_CALLOUT);
pg1.addAnnotation(fta1);

doc1.setOpenAfterSave(true);
// Write document to file
doc1.save("Annot_doc1.pdf");		
doc1.close();

Modifying Annotations

Modifying an existing annotation is very simple. First, load the PDF document, as mentioned in Part - 1 of article. Next, get the page where the annotation is located and retrieve all its annotations using the getAllAnnotations(int type). Use the methods of the annotation class to modify the annotation. When you call the PdfDocument.write() method, all the changes you have done to the annotation objects in the list will be saved.

In the code snippet below, the annotation PDF document created earlier is loaded and the content of the free text annotation is modified.

// Read existing document 		
PdfDocument doc1 = new PdfDocument();
doc1.load("Annot_doc1.pdf");

// Get first page
PdfPage pg1 = new PdfPage();
pg1 = doc1.getPage(1);

// Get list of free text annotations in page 1 
List ftaList =
  pg1.getAllAnnotations(PdfAnnot.ANNOT_TYPE_FREE_TEXT);

// Get first free text annotation
PdfFreeTextAnnot fta1 = (PdfFreeTextAnnot) ftaList.get(0);

// Modify contents of the free text annotation
fta1.setContents("This is a modified free text annotation");

// Save changes to output file
doc1.save("Annot_doc2.pdf");
doc1.close();

* - Popup windows can also be kept open by default.