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 » September 2006

By Arjun Chandra and Amol M Gade

PDF annotations are very intuitive and user-friendly. However, there are many situations where their standard appearances may seem inadequate. In organizations that deal with complex document workflows, annotations play a crucial role and are expected to be more versatile.

Also, not all PDF viewer applications (or viewers) can be expected to support all the 15-plus (and increasing) annotation types with a single uniform look-and-feel. Lack of adequate support may prevent certain annotation types from being noticed at all.

Recognizing this, Adobe has offered support for custom appearances for PDF annotations. Custom annotation appearances overcome the above limitations by actually specifying the exact manner with which the annotations need to be displayed.

Gnostice PDFOne Java makes use of appearance streams to define a custom appearance for any given annotation type and thus giving it a mandatory and uniform appearance on any viewer on the planet that supports Form XObjects rendering.

In this article, you will learn the use of the com.gnostice.pdfone.PdfAppearanceStream class to create custom annotation appearances.

Although PDFOne Java is capable of defining custom appearances for any annotation type, in this article, we will deal with just one of them - the popular file-attachment annotation.

Example 1: Create a PDF file with a default icon for a file attachment annotation.
First, a PdfFileAttachmentAnnot object is created and then it is added to a PdfPage object. The default push pin icon is used for the annotation.

// Create a PDF document
PdfDocument doc1 = new PdfDocument();

// Create an A4 PDF page
PdfPage page1 = new PdfPage(PdfPageSize.A4);

// Set inches as the default measurement unit for the page
page1.setMeasurementUnit(PdfMeasurement.MU_INCHES);

try {
  // Create a file attachment annotation
  PdfFileAttachmentAnnot fileAnnot1;
  fileAnnot1 = new PdfFileAttachmentAnnot(
                  1, // x-coordinate of the annotation icon
                  1, // y-coordinate of the annotation icon
                  "Default icon annot demo",
                  "Logo image in BMP format",
                  "Default icon annotation",
                  PdfAnnot.FLAG_NO_ZOOM,
                  Color.RED);
  // Set pathname of the file that needs to embedded
  // as an annotation
  fileAnnot1.setFilePath("logo.bmp");
  // Specify the icon used to display the annotation
  fileAnnot1.setIcon(PdfFileAttachmentAnnot.ICON_PUSHPIN);      
  
  // Add the annotation to the page
  page1.addAnnotation(fileAnnot1);
  
  // Add the page to the document
  doc1.add(page1);

  // Save the document to file
  doc1.save("CustomAnnotationIcon.pdf");
  doc1.close();

} catch (IOException | PdfException e) {
  // TODO Auto-generated catch block
  e.printStackTrace();
}

Snapshot 1: This annotation uses the default push pin icon supported by Adobe^® Reader™

A PDF file containing a file attachment annotation with the default push-pin icon has been created. Selecting the icon will open up an attached BMP image file.

However, the look and feel of this icon will vary from one viewer to another. Moreover, the annotation is static i.e., there is no change in appearance when the user interacts with the annotation.

Now, let's use the PdfAppearanceStream object to define a customized push-pin icon to achieve uniformity across all viewers.

Example 2: Create a PDF file with custom icon for the file attachment annotation.
In this example, a PdfFileAttachmentAnnot object is created and added to a PdfPage object. A custom icon for this annotation is then specified.

// Create a new PDF document      
PdfDocument doc2 = new PdfDocument();
PdfPage page2 = new PdfPage(PdfPageSize.A4);
page2.setMeasurementUnit(PdfMeasurement.MU_INCHES);

// Creates a rectangle
PdfRect annotRectangle = 
  new PdfRect(1, 1,       // x-y coordinates of the annotation
              1.5, 1.5);  // dimensions of the annotation

try {
  // Create a file attachment annotation
  PdfFileAttachmentAnnot fileAnnot2;
  fileAnnot2 = 
    new PdfFileAttachmentAnnot(
      1, 1, // x-y coordinates of the annotation
      "Custom icon annot demo",
      "File attachment annotation",
      "Annotation with custom icon",
      PdfAnnot.FLAG_NO_ZOOM,
      Color.RED);
  // Set pathname of the file that needs to embedded
  // as an annotation
  fileAnnot2.setFilePath("logo.bmp");
  // Set the annotation rectangle
  fileAnnot2.setRect(annotRectangle);
  
  // Create a custom "normal" appearance stream
  PdfAppearanceStream normalAppearance =
  new PdfAppearanceStream(annotRectangle);
  // Draw the normal icon image on the appearance stream
  normalAppearance.drawImage(PdfImage.create("normalIcon.jpg"));
  
  // Creates a custom "rollover" appearance stream
  PdfAppearanceStream rolloverAppearance =
  new PdfAppearanceStream(annotRectangle);
  // Draws the rollover icon image on the appearance stream
  rolloverAppearance.drawImage(PdfImage.create("rolloverIcon.jpg"));

  // Set the normal appearance to the annotation
  fileAnnot2.setNormalAppearance(normalAppearance);
  // Set the rollover appearance to the annotation
  fileAnnot2.setRolloverAppearance(rolloverAppearance);
  
  // Add the annotation to the page
  page2.addAnnotation(fileAnnot2);
  
  // Add the page to the document
  doc2.add(page2);
  
  // Save the document to file
  doc2.save("CustomAnnotationIcon.pdf");
  doc2.close();
  
} catch (IOException | PdfException e) {
  // TODO Auto-generated catch block
  e.printStackTrace();
} 

Snapshot 2: The file attachment annotation sports a customized push-pin icon

Snapshot 3: The custom icon changes with user interaction

This PDF file contains a file attachment annotation with a customized push-pin icon. When the mouse pointer hovers over the icon, another customized push-pin icon is displayed. As usual, clicking the annotation opens up the BMP image file.

This look and feel of the annotation will be uniform across all viewers. With the addition of rollover appearance, the annotation is now dynamic i.e. it changes with user interaction.

You have learned how to create a uniform appearance for PDF annotations using the com.gnostice.pdfone.PdfAppearanceStream class.

In our next article, we will demonstrate a similar use of this class with PDF form fields (AcroForms).