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

Arjun Chandra & Santhanam L.

Custom appearances for PDF form fields can be created in almost the same way we created custom appearances for PDF annotations in our September Newsletter article.

Gnostice PDFOne Java makes use of appearance streams to define a custom appearance for a form field and thus giving it a uniform appearance on any viewer that supports Form XObjects rendering.

In this article, you will learn about the use of com.gnostice.pdfone.PdfAppearanceStream class to create custom form field appearances for the push button form field type.

Please note that in the previous article, we used images for the appearance streams while in this article we will be using generic shapes.

Example 1: Create a PDF file with standard appearances for push button form fields

First, two PdfFormPushButton objects are created and are then added to a PdfPage object. Standard appearances for the PdfFormPushButton objects are created using setBackgroundColor(Color backgroundColor) and setBorderColor(Color borderColor) methods of PdfFormPushButton.

private static void formFieldSimpleAppearanceDemo() throws IOException, PdfException {

  PdfDocument doc = new PdfDocument();
  
  PdfFont font = 
    PdfFont.create("Helvetica",
                   10,
                   PdfEncodings.WINANSI);
  font.setColor(Color.BLACK);
  
  PdfPage page;
  page = new PdfPage(PdfPageSize.A4);
  page.setMeasurementUnit(PdfMeasurement.MU_INCHES);
  
  // X-y coordinates of the PdfFormPushButton
  int xPos = 1; // One inch
  int yPos = 1; // One inch
  // Dimensions for the PdfFormPushButton
  double buttonWidth = 1.5; // One inch
  double buttonHeight = 0.5; // Half inch
  // Creates an object for PdfFormPushButton
  // with coordinates created above
  
  PdfFormPushButton jsButton =
    new PdfFormPushButton(new PdfRect(xPos,
                          yPos,
                          buttonWidth,
                          buttonHeight));
  // Set JavaScript action to the PdfFormPushButton
  jsButton.addAction(PdfAction.JAVASCRIPT,
                     PdfEvent.ON_MOUSE_DOWN,
                     "app.alert('Gnostice PDFOne on Mouse Down')");
  // Set the properties for the PdfFormPushButton
  jsButton.setBackgroundColor(Color.LIGHT_GRAY);
  jsButton.setBorderColor(Color.DARK_GRAY);
  jsButton.setName("button1");
  jsButton.setNormalCaption("JavaScript-NormalAP");
  jsButton.setRolloverCaption("JavaScript-RolloverAP");
  jsButton.setDownCaption("Down");
  jsButton.setFont(font);
  
  // X-Y coordinates for the second PdfFormPushButton
  xPos = 1; // One inch
  yPos = 2; // One inch
  // Creates the second PdfFormPushButton object
  // with coordinates created above
  PdfFormPushButton submitButton =
    new PdfFormPushButton(new PdfRect(xPos, yPos, buttonWidth,  buttonHeight));
  // Set submit action to the PdfFormPushButton
  submitButton.addAction(PdfAction.URI,
                         PdfEvent.ON_MOUSE_DOWN, 
                         "http://www.gnostice.com");
  // Set properties for the PdfFormPushButton
  submitButton.setBackgroundColor(Color.LIGHT_GRAY);
  submitButton.setBorderColor(Color.DARK_GRAY);
  submitButton.setName("button2");
  submitButton.setNormalCaption("Submit-NormalAP");
  submitButton.setRolloverCaption("Submit-RolloverAP");
  submitButton.setDownCaption("Down");
  submitButton.setFont(font);
  
  // Add JS button to the page
  page.addFormField(jsButton);
  // Add the submit button to the page
  page.addFormField(submitButton);
  // Add the page to document
  doc.add(page);
  
  
  doc.save("FormfieldSimpleAppearanceDemo.pdf");
  doc.close();
}  

Snapshot 1: These push button form fields have standard appearances. The snapshot shows the first button in normal mode and second button in rollover mode. Clicking the first button executes a JavaScript action. Clicking the second button executes a URI action.

Example 2: Create a PDF file with custom shape appearances for push button form fields

First, custom appearances for both normal mode and rollover mode are created for the two push buttons. After that, two PdfFormPushButton objects are created. The custom appearances are then added to these PdfFormPushButton objects.

Please note that even when appearances for normal, rollover and down modes for two or more form fields are the same, you should instantiate individual appearance streams for them.

private static void formFieldCustomAppearanceShapeDemo() throws IOException, PdfException {
  PdfDocument doc = new PdfDocument();
   
  PdfFont font = PdfFont.create("Helvetica",10, PdfEncodings.WINANSI);
  font.setColor(Color.BLACK);
  
  PdfPage page;
  page = new PdfPage(PdfPageSize.A4);
  page.setMeasurementUnit(PdfMeasurement.MU_INCHES);
  
  // X-Y coordinates of the first PdfFormPushButton
  int xPos = 1; // One inch
  int yPos = 1; // One inch
  // Dimensions of the PdfFormPushButton
  double buttonWidth = 1.5; // One inch
  double buttonHeight = 0.5; // Half inch
  // Dimensions of the PdfFormPushButton in points
  double buttonWidth_Points =  
    PdfMeasurement.convertToPdfUnit(PdfMeasurement.MU_INCHES, 1.5);
  double buttonHeight_Points =  
    PdfMeasurement.convertToPdfUnit(PdfMeasurement.MU_INCHES, 0.5);
  
  PdfPen pen = new PdfPen();
  pen.dashPhase = 3 ;
  pen.dashLength = 4;
  pen.dashGap = 2;
  pen.strokeColor = Color.GREEN;
  pen.width = 4;
  
  PdfBrush brush = new PdfBrush();
  brush.fillColor = Color.YELLOW;

  // Creates a font for normal appearance stream
  // and set its color
  PdfFont normal_ap_font = 
    PdfFont.create("Arial", 
                   PdfFont.BOLD | PdfFont.ITALIC, 
                   8, 
                   PdfEncodings.WINANSI);
  normal_ap_font.setColor(Color.RED);

  // Creates a font for rollover appearance stream
  // and set its color
  PdfFont rollover_ap_font =
    PdfFont.create("Helvetica",
                   PdfFont.BOLD | PdfFont.ITALIC,
                   9, 
                   PdfEncodings.WINANSI);
  rollover_ap_font.setColor(Color.RED);

  // Creates a rectangle of the same size as the push
  // button, which will be drawn on all appearance streams
  PdfRect ap_rect = new PdfRect(0, 0, buttonWidth_Points, buttonHeight_Points);
  // Creates a TextFormatter to format the text to be
  // written inside the shape of the appearance stream
  PdfTextFormatter tf = new PdfTextFormatter();
  tf.setAlignment(PdfTextFormatter.CENTER);

  // Creates a PdfAppearanceStream for the normal
  // appearance of the first PdfFormPushButton
  PdfAppearanceStream js_normal_AP =
    new PdfAppearanceStream(ap_rect);
  // Draws the rectangle on the appearance stream
  js_normal_AP.drawRect(ap_rect, pen, brush);
  // Writes the name of the push button inside the rectangle
  js_normal_AP.writeText("JavaScript-NormalAP",
                         normal_ap_font,
                         new PdfRect(0, 13, buttonWidth_Points, buttonHeight_Points),
                         tf,
                         PdfMeasurement.MU_POINTS);

  // Creates a PdfAppearanceStream for the normal
  // appearance of the second PdfFormPushButton
  PdfAppearanceStream submit_normal_AP = new PdfAppearanceStream(ap_rect);
  // Draws the rectangle on the appearance stream
  submit_normal_AP.drawRect(ap_rect, pen, brush);
  // Writes the name of the push button inside the rectangle
  submit_normal_AP.writeText("Submit-NormalAP", 
                             normal_ap_font,  
                             new PdfRect(0, 13, buttonWidth_Points, buttonHeight_Points),
                             tf,
                             PdfMeasurement.MU_POINTS);
  pen.strokeColor = Color.RED;
  brush.fillColor = Color.GREEN;

  // Creates a PdfAppearanceStream for the rollover
  // appearance of the first PdfFormPushButton
  PdfAppearanceStream js_rollover_AP =
    new PdfAppearanceStream(ap_rect);
  // Draws the rectangle on the appearance stream
  js_rollover_AP.drawRect(ap_rect, pen, brush);
  // Writes the name of the push button inside the rectangle
  js_rollover_AP.writeText("JavaScript-RolloverAP",
                           rollover_ap_font,
                           new PdfRect(0, 11, buttonWidth_Points, buttonHeight_Points),
                           tf,
                           PdfMeasurement.MU_POINTS);
  
  // Creates a PdfAppearanceStream for the rollover
  // appearance of the second PdfFormPushButton
  PdfAppearanceStream submit_rollover_AP =
    new PdfAppearanceStream(ap_rect);
  // Draws the rectangle on the appearance stream
  submit_rollover_AP.drawRect(ap_rect, pen, brush);
  // Writes the name of the push button inside the rectangle
  submit_rollover_AP.writeText("Submit-RolloverAP",
                               rollover_ap_font,
                               new PdfRect(0, 11, buttonWidth_Points, buttonHeight_Points),
                               tf,
                               PdfMeasurement.MU_POINTS);
  
  // Create the first PdfFormPushButton control
  // with the specified coordinates
  PdfFormPushButton jsButton = 
    new PdfFormPushButton(new PdfRect(xPos, yPos, buttonWidth, buttonHeight));
  // Set JavaScript action to the PdfFormPushButton
  jsButton.addAction(PdfAction.JAVASCRIPT, 
                     PdfEvent.ON_MOUSE_DOWN,
                     "app.alert('Gnostice PDFOne on Mouse Down')");
  // Set the properties for the PdfFormPushButton
  jsButton.setName("button1");
  jsButton.setNormalCaption("JavaScript");
  // Set the normal appearance
  jsButton.setNormalAppearance(js_normal_AP);
  // Set the rollover appearance
  jsButton.setRolloverAppearance(js_rollover_AP);
  jsButton.setFont(font);
  // Add the jsButton to the page
  page.addFormField(jsButton);
  
  
  // X-Y coordinates for another PdfFormPushButton
  xPos = 1; // One inch
  yPos = 2; // One inch
  // Create the second PdfFormPushButton control
  // with the specified coordinates
  PdfFormPushButton submitButton =
    new PdfFormPushButton(new PdfRect(xPos, yPos, buttonWidth, buttonHeight));
  // Set submit action to the PdfFormPushButton
  submitButton.addAction(
    PdfAction.URI,
    PdfEvent.ON_MOUSE_DOWN,
    "http://www.gnostice.com");
  // Set the properties for the PdfFormPushButton
  submitButton.setName("button2");
  submitButton.setNormalCaption("Submit");
  // Set the normal appearance
  submitButton.setNormalAppearance(submit_normal_AP);
  // Set the rollover appearance
  submitButton.setRolloverAppearance(submit_rollover_AP);
  submitButton.setFont(font);    
  // Add submitButton to the page
  page.addFormField(submitButton);
  
  doc.add(page);    
  doc.save("FormfieldCustomAppearanceShapeDemo.pdf");
  doc.close();
} 

Snapshot 2: The snapshot shows Push Buttons created with Custom Appearances using a Colored Rectangle Shape drawn on it and the name of the form field written on it. The snapshot shows the first Button in Normal Mode and second Button in Rollover mode.

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

---o0O0o---

Downloads:

• Plain text source code for sample Java class file FormFieldsWithAppearanceStream.java containing methods to create a PDF file with
  • standard appearances for form fields (as described above)
  • custom shape appearances for form fields (as described above)
  • custom image appearances for form fields