View Source

h3. Annotation Creation

Link Annotations and their respective actions can be created edited and delete from a PDF document page. The Page Object has three new methods that allow developers to manipulate a PDF documents annotations:

* Page.addAnnotation(Annotation):Annotation
* Page.createAnnotation(Rectangle, AnnotationState):Annotation
* Page.deleteAnnotation(Annotation):void

Annotations are added at the document page level. The PDF specification recommends that duplicate Annotation object are not shared between pages and that a distinct instance of each should be created for every page.

Annotations and their child Action object must created using their respective factory classes. The factory class insures that the new instance of these object are properly setup so that they can be property inserted or removed from the PDF document structure and saved to file.

h4. Annotation Factory

The Annotation factory call AnnotationFactory.buildAnnotation(..) returns a new instance of the specified annotation type which can be inserted into the Document Page Object via the addAnnotation method.

LinkAnnotation linkAnnotation = (LinkAnnotation)
new Rectangle());

h4. Action factory

The Action factory call Annotation.buildAction(..) returns an new instance of the specified action type. Action must be added to Annotation object in a similar way as Annotations are to pages to insure that the Action objects are wired correctly to the document structure and their parent annotation object.

* Annotation.addAction(Action):Annotation
* Annotation.deleteAction(Action):void

The following code snippet is an example of creating a new Launch Action using the ActionFactory.

LaunchAction action = (LaunchAction) ActionFactory.buildAction(

h4. Using the Non-visual vs. the Visual API

Creating annotation in a headless environment can be done using Page and Annotation classes, no special considerations need to be taken into account. However if the annotation updates are to occur though a GUI the ICEpdf PageView objects must be made aware of any changes to the document structure.

The first step in update the UI of a new annotation or action is to get a reference to the current views page objects with the following call which returns a list of all pages that make up the document view:

java.util.List<AbstractPageViewComponent> pageComponents =

The list of AbstractPageViewComponent is very similar to a list of a PDF documents Page Object. The PageViewComponents are actually JComponents and contain all the interactive state logic. But adding annotation to AbstractPageViewComponent is the same as adding new annotations to Page objects.


The distinction between visual and none visual annotation creation is very important. If you use the non-visual method in a visual environment you will not see the annotation until the document is saved and opened. You can however use the visual method to create annotation in a non-visual environment but you will be loading a lot of extra classes that are not needed.

The source-code for the example is located at [install_dir|install_dir]/icepdf/examples/annotation/

The source-code for the example is located at [install_dir|install_dir]/icepdf/examples/annotation/

h4. Saving Document Changes (Pro version only)

Annotation and action document changes are stored in a StateManager class. In most cases developers will not have to modify the StateManager class directly, it was designed to be used by the Page, PageComponent and Annotation object directly. Saving document change is quite simple:

document.saveToOutputStream(OutputStream out):long

When a file is saved all changed are appended to the PDF file as an incremental update.