org.faceless.pdf2
Class Form

java.lang.Object
  extended byorg.faceless.pdf2.PDFObject
      extended byorg.faceless.pdf2.PDFMap
          extended byorg.faceless.pdf2.Form
All Implemented Interfaces:
Cloneable

public final class Form
extends org.faceless.pdf2.PDFMap

The Form class represents the interactive Form that may be included as part of a PDF document. This form can be filled out by users and then eventually submitted for processing in the same way as an HTML form. Unlike HTML, a PDF document may only have one form.

A form contains zero or more FormElement objects which you can access via the getElements() method. Each form element usually has one or more visual representation on the page - a WidgetAnnotation. These annotation can be accessed by the FormElement.getAnnotations() method. Each element in the form is stored under a name, which is used to reference the element and must be unique.

The name may be a simple string, like "Element1", or it may be a compound name, with fields separated with dots, for example "Employee.Address.City". Simple and Compound names must not collide - for example, it would be illegal to have elements called "Country.Capital" and "Country" in the same document.

Note that using interactive forms requires the "Extended Edition" of the library - although the classes are supplied with the package an "Extended Edition" license must be purchased to activate this functionality.

Since:
1.1.13
See Also:
PDF.getForm(), FormElement

Method Summary
 void addElement(String name, FormElement element)
           Add an element to the form.
 void clear()
          Remove all the elements from the form
 boolean equals(Object o)
           
 void flatten()
           Flatten the entire form.
 FormElement getElement(String name)
          Return the specified element from the form.
 Map getElements()
          Return a map of all the elements in the form.
 String getName(FormElement element)
          Given a FormElement, return the name by which this element is stored in the form, or null if it doesn't exist in this form.
 FormElement removeElement(String name)
          Remove the specified element from the form, if it exists.
 void renameAllElements(String prefix, String suffix)
          Rename all the elements in the form by adding a prefix and/or suffix to their names.
 void renameElement(String fromname, String toname)
          Rename an element in the form.
 void setBackgroundStyle(PDFStyle style)
          Set the default background style for all new elements added to the form.
 void setTextStyle(PDFStyle style)
          Set the default text style for all new elements added to the form.
 String toString()
           
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getElements

public Map getElements()
Return a map of all the elements in the form. Each key in the Map is a String representing the name of the element, and the corresponding value is the FormElement. The returned map can be modified to add or remove elements from the form. The fields are stored in the order they are added to the Map.

Returns:
a Map containing all the form elements
Since:
2.0

addElement

public void addElement(String name,
                       FormElement element)

Add an element to the form. Although a form can contain as many elements as you like, currently only a single signature with a state of FormSignature.STATE_PENDING can be added to each document. This method is identical to calling:

   form.getElements().put(name, element);
 

Parameters:
name - the name of the form element
element - the element to add to the form
Throws:
IllegalStateException - if the element already exists in the form
Since:
1.1.13

getElement

public FormElement getElement(String name)
Return the specified element from the form. This method is identical to calling:

   FormElement element = form.getElements().get(name);
 

Parameters:
name - the name of the form element
Returns:
the specified element, or null if it doesn't exist
Since:
1.1.13

removeElement

public FormElement removeElement(String name)
Remove the specified element from the form, if it exists. This method is identical to calling

   FormElement element = form.getElements().remove(name);
 

Parameters:
name - the name of the form element to remove
Returns:
the removed element, or null if it didn't exist

renameElement

public void renameElement(String fromname,
                          String toname)
Rename an element in the form. If the specified element name does not exist, an IllegalArgumentException is thrown. Since 2.0 the element keeps the same ordering in the form.

Parameters:
fromname - the original name of the form element
toname - the new name of the form element
Throws:
IllegalArgumentException - if the specified element does not exist
Since:
1.1.23

renameAllElements

public void renameAllElements(String prefix,
                              String suffix)
Rename all the elements in the form by adding a prefix and/or suffix to their names. This method is useful when merging two copies of the same document together - as each field must have a unique name, this method can be used to rename the fields in the first copy to "Name1", "Phone1", in the second copy to "Name2", "Phone2" and so on. The elements keep the same ordering in the form.

Parameters:
prefix - the prefix to add to all element names - may be null
suffix - the suffix to add to all element names - may be null
Since:
2.0

clear

public void clear()
Remove all the elements from the form

Since:
1.2.1

getName

public String getName(FormElement element)
Given a FormElement, return the name by which this element is stored in the form, or null if it doesn't exist in this form.

Returns:
the name of this element or null if it's not in the Form

setBackgroundStyle

public void setBackgroundStyle(PDFStyle style)
Set the default background style for all new elements added to the form. This can be overridden by the WidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle) method in the WidgetAnnotation class. The default is a white background with a plain black border

Parameters:
style - the default back style for new form elements
Since:
1.1.23
See Also:
WidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle)

setTextStyle

public void setTextStyle(PDFStyle style)
Set the default text style for all new elements added to the form. The style must include a font and a fill color to draw the text in. If a font size of 0 is specified, an appropriate size is chosen for each widget (the equivalent of "Auto" font size in Acrobat). Like background styles, this can be overridden for each widget. The default is black auto-sized Helvetica.

Parameters:
style - the default text style for new form elements
Since:
1.1.23
See Also:
WidgetAnnotation.setTextStyle(org.faceless.pdf2.PDFStyle)

flatten

public void flatten()

Flatten the entire form. Calls FormElement.flatten() on every element in the form and then delete it, so only the visible appearance of the form remains. Provided the user is not going to edit the values in the form, flattening a form before rendering is an extremely effective way to reduce the size of the document.

Note that if you use JavaScript to format the field before display, this will not be taken into used when the field is flattened. Only the exact value returned by FormElement.getValue() will be used.

Since:
2.0

toString

public String toString()

equals

public boolean equals(Object o)


Copyright © 2001-2004 Big Faceless Organization