Package org.apache.pdfbox.pdmodel.interactive.form

Class PDAcroForm

java.lang.Object
org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm
All Implemented Interfaces:
COSObjectable
public final class PDAcroForm extends Object implements COSObjectable
An interactive form, also known as an AcroForm.
Author:
Ben Litchfield

  • Constructor Details

    • PDAcroForm

      public PDAcroForm(PDDocument doc)
      Constructor.
      Parameters:
      doc - The document that this form is part of.

    • PDAcroForm

      public PDAcroForm(PDDocument doc, COSDictionary form)
      Constructor. Side effect: /Helv and /ZaDb fonts added with update mark.
      Parameters:
      doc - The document that this form is part of.
      form - The existing acroForm.

  • Method Details

    • getCOSObject

      public COSDictionary getCOSObject()
      Description copied from interface: COSObjectable
      Convert this standard java object to a COS object.
      Specified by:
      getCOSObject in interface COSObjectable
      Returns:
      The cos object that matches this Java object.

    • importFDF

      public void importFDF(FDFDocument fdf) throws IOException
      This method will import an entire FDF document into the PDF document that this acroform is part of.
      Parameters:
      fdf - The FDF document to import.
      Throws:
      IOException - If there is an error doing the import.

    • exportFDF

      public FDFDocument exportFDF() throws IOException
      This will export all FDF form data.
      Returns:
      An FDF document used to export the document.
      Throws:
      IOException - If there is an error when exporting the document.

    • flatten

      public void flatten() throws IOException
      This will flatten all form fields.

      Flattening a form field will take the current appearance and make that part of the pages content stream. All form fields and annotations associated are removed.

      Invisible and hidden fields will be skipped and will not become part of the page content stream

      The appearances for the form fields widgets will not be generated

      Throws:
      IOException

    • flatten

      public void flatten(List<PDField> fields, boolean refreshAppearances) throws IOException
      This will flatten the specified form fields.

      Flattening a form field will take the current appearance and make that part of the pages content stream. All form fields and annotations associated are removed.

      Invisible and hidden fields will be skipped and will not become part of the page content stream

      Parameters:
      fields -
      refreshAppearances - if set to true the appearances for the form field widgets will be updated
      Throws:
      IOException

    • refreshAppearances

      public void refreshAppearances() throws IOException
      Refreshes the appearance streams and appearance dictionaries for the widget annotations of all fields.
      Throws:
      IOException

    • refreshAppearances

      public void refreshAppearances(List<PDField> fields) throws IOException
      Refreshes the appearance streams and appearance dictionaries for the widget annotations of the specified fields.
      Parameters:
      fields -
      Throws:
      IOException

    • getFields

      public List<PDField> getFields()
      This will return all of the documents root fields. A field might have children that are fields (non-terminal field) or does not have children which are fields (terminal fields). The fields within an AcroForm are organized in a tree structure. The documents root fields might either be terminal fields, non-terminal fields or a mixture of both. Non-terminal fields mark branches which contents can be retrieved using PDNonTerminalField.getChildren().
      Returns:
      A list of the documents root fields, never null. If there are no fields then this method returns an empty list.

    • setFields

      public void setFields(List<PDField> fields)
      Set the documents root fields.
      Parameters:
      fields - The fields that are part of the documents root fields.

    • getFieldIterator

      public Iterator<PDField> getFieldIterator()
      Returns an iterator which walks all fields in the field tree, in order.

    • getFieldTree

      public PDFieldTree getFieldTree()
      Return the field tree representing all form fields

    • setCacheFields

      public void setCacheFields(boolean cache)
      This will tell this form to cache the fields into a Map structure for fast access via the getField method. The default is false. You would want this to be false if you were changing the COSDictionary behind the scenes, otherwise setting this to true is acceptable.
      Parameters:
      cache - A boolean telling if we should cache the fields.

    • isCachingFields

      public boolean isCachingFields()
      This will tell if this acro form is caching the fields.
      Returns:
      true if the fields are being cached.

    • getField

      public PDField getField(String fullyQualifiedName)
      This will get a field by name, possibly using the cache if setCache is true.
      Parameters:
      fullyQualifiedName - The name of the field to get.
      Returns:
      The field with that name of null if one was not found.

    • getDefaultAppearance

      public String getDefaultAppearance()
      Get the default appearance.
      Returns:
      the DA element of the dictionary object

    • setDefaultAppearance

      public void setDefaultAppearance(String daValue)
      Set the default appearance.
      Parameters:
      daValue - a string describing the default appearance

    • getNeedAppearances

      public boolean getNeedAppearances()
      True if the viewing application should construct the appearances of all field widgets. The default value is false.
      Returns:
      the value of NeedAppearances, false if the value isn't set

    • setNeedAppearances

      public void setNeedAppearances(Boolean value)
      Set the NeedAppearances value. If this is false, PDFBox will create appearances for all field widget.
      Parameters:
      value - the value for NeedAppearances

    • getDefaultResources

      public PDResources getDefaultResources()
      This will get the default resources for the AcroForm.
      Returns:
      The default resources or null if there is none.

    • setDefaultResources

      public void setDefaultResources(PDResources dr)
      This will set the default resources for the acroform.
      Parameters:
      dr - The new default resources.

    • hasXFA

      public boolean hasXFA()
      This will tell if the AcroForm has XFA content.
      Returns:
      true if the AcroForm is an XFA form

    • xfaIsDynamic

      public boolean xfaIsDynamic()
      This will tell if the AcroForm is a dynamic XFA form.
      Returns:
      true if the AcroForm is a dynamic XFA form

    • getXFA

      public PDXFAResource getXFA()
      Get the XFA resource, the XFA resource is only used for PDF 1.5+ forms.
      Returns:
      The xfa resource or null if it does not exist.

    • setXFA

      public void setXFA(PDXFAResource xfa)
      Set the XFA resource, this is only used for PDF 1.5+ forms.
      Parameters:
      xfa - The xfa resource.

    • getQ

      public int getQ()
      This will get the document-wide default value for the quadding/justification of variable text fields.

      0 - Left(default)
      1 - Centered
      2 - Right
      See the QUADDING constants of PDVariableText.

      Returns:
      The justification of the variable text fields.

    • setQ

      public void setQ(int q)
      This will set the document-wide default value for the quadding/justification of variable text fields. See the QUADDING constants of PDVariableText.
      Parameters:
      q - The justification of the variable text fields.

    • isSignaturesExist

      public boolean isSignaturesExist()
      Determines if SignaturesExist is set.
      Returns:
      true if the document contains at least one signature.

    • setSignaturesExist

      public void setSignaturesExist(boolean signaturesExist)
      Set the SignaturesExist bit.
      Parameters:
      signaturesExist - The value for SignaturesExist.

    • isAppendOnly

      public boolean isAppendOnly()
      Determines if AppendOnly is set.
      Returns:
      true if the document contains signatures that may be invalidated if the file is saved.

    • setAppendOnly

      public void setAppendOnly(boolean appendOnly)
      Set the AppendOnly bit.
      Parameters:
      appendOnly - The value for AppendOnly.

    • getCalcOrder

      public List<PDField> getCalcOrder()
      Return the calculation order in which field values should be recalculated when the value of any field changes. (Read about "Trigger Events" in the PDF specification)
      Returns:
      field list. Note these objects may not be identical to PDField objects retrieved from other methods (depending on cache setting). The best strategy is to call getCOSObject() to check for identity. The list is not backed by the /CO COSArray in the document.

    • setCalcOrder

      public void setCalcOrder(List<PDField> fields)
      Set the calculation order in which field values should be recalculated when the value of any field changes. (Read about "Trigger Events" in the PDF specification)
      Parameters:
      fields - The field list.

    • getScriptingHandler

      public ScriptingHandler getScriptingHandler()
      Set a handler to support JavaScript actions in the form.
      Returns:
      scriptingHandler

    • setScriptingHandler

      public void setScriptingHandler(ScriptingHandler scriptingHandler)
      Set a handler to support JavaScript actions in the form.
      Parameters:
      scriptingHandler -