PdfAcroForm (iText 7 7.1.17 API)

java.lang.Object
- com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>
- - com.itextpdf.forms.PdfAcroForm

All Implemented Interfaces:

Serializable
```
public class PdfAcroForm
extends PdfObjectWrapper<PdfDictionary>
```
This class represents the static form technology AcroForm on a PDF file.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`APPEND_ONLY` To be used with `setSignatureFlags(int)`.
`protected PdfDocument`	`document` The PdfDocument to which the PdfAcroForm belongs.
`protected Map<String,PdfFormField>`	`fields` A map of field names and their associated `form field` objects.
`protected boolean`	`generateAppearance` Keeps track of whether or not appearances must be generated by the form fields themselves, or by the PDF viewer application.
`static int`	`SIGNATURE_EXIST` To be used with `setSignatureFlags(int)`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addField(PdfFormField field)` This method adds the field to the last page in the document.
`void`	`addField(PdfFormField field, PdfPage page)` This method adds the field to a specific page.
`void`	`addFieldAppearanceToPage(PdfFormField field, PdfPage page)` This method merges field with its annotation and place it on the given page.
`PdfFormField`	`copyField(String name)` Creates an in-memory copy of a `PdfFormField`.
`void`	`flattenFields()` Flattens interactive `form field`s in the document.
`static PdfAcroForm`	`getAcroForm(PdfDocument document, boolean createIfNotExist)` Retrieves AcroForm from the document.
`PdfArray`	`getCalculationOrder()` Gets the `CO` array property on the AcroForm.
`PdfString`	`getDefaultAppearance()` Gets the `DA` String property on the AcroForm.
`PdfNumber`	`getDefaultJustification()` Gets the `Q` integer property on the AcroForm.
`PdfDictionary`	`getDefaultResources()` Gets the `DR` dictionary property on the AcroForm.
`PdfFormField`	`getField(String fieldName)` Gets a `form field` by its name.
`protected PdfArray`	`getFields()` Gets all AcroForm fields in the document.
`Collection<PdfFormField>`	`getFieldsForFlattening()` Gets a collection of `form field`s, prepared for flattening using `partialFormFlattening(java.lang.String)` method.
`Map<String,PdfFormField>`	`getFormFields()` Gets the `form field`s as a `Map`.
`PdfBoolean`	`getNeedAppearances()` Gets the `NeedAppearances` boolean property on the AcroForm.
`PdfDocument`	`getPdfDocument()` Gets the `PdfDocument` this `PdfAcroForm` belongs to.
`int`	`getSignatureFlags()` Gets the `SigFlags` integer property on the AcroForm.
`XfaForm`	`getXfaForm()` Gets the `XfaForm` atribute.
`PdfObject`	`getXFAResource()` Gets the `XFA` property on the AcroForm.
`boolean`	`hasXfaForm()` Determines whether the AcroForm contains XFA data.
`boolean`	`isGenerateAppearance()` Gets the attribute generateAppearance, which tells `flattenFields()` to generate an appearance Stream for all `form field`s that don't have one.
`protected boolean`	`isWrappedObjectMustBeIndirect()` Defines if the object behind this wrapper must be an indirect object in the resultant document.
`void`	`partialFormFlattening(String fieldName)` Adds a `form field`, identified by name, to the list of fields to be flattened.
`PdfAcroForm`	`put(PdfName key, PdfObject value)`
`void`	`release()` Releases underlying pdf object and other pdf entities used by wrapper.
`boolean`	`removeField(String fieldName)` Tries to remove the `form field` with the specified name from the document.
`void`	`removeXfaForm()` Removes the XFA stream from the document.
`void`	`renameField(String oldName, String newName)` Changes the identifier of a `form field`.
`void`	`replaceField(String name, PdfFormField field)` Replaces the `PdfFormField` of a certain name with another `PdfFormField`.
`PdfAcroForm`	`setCalculationOrder(PdfArray calculationOrder)` Sets the `CO` array property on the AcroForm.
`PdfAcroForm`	`setDefaultAppearance(String appearance)` Sets the `DA` String property on the AcroForm.
`PdfAcroForm`	`setDefaultJustification(int justification)` Sets the `Q` integer property on the AcroForm.
`PdfAcroForm`	`setDefaultResources(PdfDictionary defaultResources)` Sets the `DR` dictionary property on the AcroForm.
`void`	`setGenerateAppearance(boolean generateAppearance)` Sets the attribute generateAppearance, which tells `flattenFields()` to generate an appearance Stream for all `form field`s that don't have one.
`PdfObjectWrapper<PdfDictionary>`	`setModified()`
`PdfAcroForm`	`setNeedAppearances(boolean needAppearances)` Sets the `NeedAppearances` boolean property on the AcroForm.
`PdfAcroForm`	`setSignatureFlag(int sigFlag)` Changes the `SigFlags` integer property on the AcroForm.
`PdfAcroForm`	`setSignatureFlags(int sigFlags)` Sets the `SigFlags` integer property on the AcroForm.
`PdfAcroForm`	`setXFAResource(PdfArray xfaResource)` Sets the `XFA` property on the AcroForm.
`PdfAcroForm`	`setXFAResource(PdfStream xfaResource)` Sets the `XFA` property on the AcroForm.

Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper
ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, flush, getPdfObject, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setPdfObject, unsetForbidRelease

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SIGNATURE_EXIST
```
public static final int SIGNATURE_EXIST
```
    To be used with setSignatureFlags(int).
    
    If set, the document contains at least one signature field. This flag allows a conforming reader to enable user interface items (such as menu items or pushbuttons) related to signature processing without having to scan the entire document for the presence of signature fields. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    See Also:
    
    Constant Field Values
  - APPEND_ONLY
```
public static final int APPEND_ONLY
```
    To be used with setSignatureFlags(int).
    
    If set, the document contains signatures that may be invalidated if the file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. Merely updating the file by appending new information to the end of the previous version is safe. Conforming readers may use this flag to inform a user requesting a full save that signatures will be invalidated and require explicit confirmation before continuing with the operation. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    See Also:
    
    Constant Field Values
  - generateAppearance
```
protected boolean generateAppearance
```
    Keeps track of whether or not appearances must be generated by the form fields themselves, or by the PDF viewer application. Default is true.
  - fields
```
protected Map<String,PdfFormField> fields
```
    A map of field names and their associated form field objects.
  - document
```
protected PdfDocument document
```
    The PdfDocument to which the PdfAcroForm belongs.
- Method Detail
  - getAcroForm
```
public static PdfAcroForm getAcroForm(PdfDocument document,
                                      boolean createIfNotExist)
```
    Retrieves AcroForm from the document. If there is no AcroForm in the document Catalog and createIfNotExist flag is true then the AcroForm dictionary will be created and added to the document.
    
    Parameters:
    
    document - the document to retrieve the PdfAcroForm from
    
    createIfNotExist - when true, this method will create a PdfAcroForm if none exists for this document
    
    Returns:
    
    the document's AcroForm, or a new one provided that createIfNotExist parameter is true, otherwise null.
  - addField
```
public void addField(PdfFormField field)
```
    This method adds the field to the last page in the document. If there's no pages, creates a new one.
    
    Parameters:
    
    field - the PdfFormField to be added to the form
  - addField
```
public void addField(PdfFormField field,
                     PdfPage page)
```
    This method adds the field to a specific page.
    
    Parameters:
    
    field - the PdfFormField to be added to the form
    
    page - the PdfPage on which to add the field
  - addFieldAppearanceToPage
```
public void addFieldAppearanceToPage(PdfFormField field,
                                     PdfPage page)
```
    This method merges field with its annotation and place it on the given page. This method won't work if the field has no or more than one widget annotations.
    
    Parameters:
    
    field - the PdfFormField to be added to the form
    
    page - the PdfPage on which to add the field
  - getFormFields
```
public Map<String,PdfFormField> getFormFields()
```
    Gets the form fields as a Map.
    
    Returns:
    
    a map of field names and their associated form field objects
  - getFieldsForFlattening
```
public Collection<PdfFormField> getFieldsForFlattening()
```
    Gets a collection of form fields, prepared for flattening using partialFormFlattening(java.lang.String) method. If returned collection is empty, all form fields will be flattened on flattenFields call.
    
    Returns:
    
    a collection of form fields for flattening
  - getPdfDocument
```
public PdfDocument getPdfDocument()
```
    Gets the PdfDocument this PdfAcroForm belongs to.
    
    Returns:
    
    the document of this form
  - setNeedAppearances
```
public PdfAcroForm setNeedAppearances(boolean needAppearances)
```
    Sets the NeedAppearances boolean property on the AcroForm. NeedAppearances has been deprecated in PDF 2.0.
    
    NeedAppearances is a flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Parameters:
    
    needAppearances - a boolean. Default value is false
    
    Returns:
    
    current AcroForm.
  - getNeedAppearances
```
public PdfBoolean getNeedAppearances()
```
    Gets the NeedAppearances boolean property on the AcroForm. NeedAppearances has been deprecated in PDF 2.0.
    
    NeedAppearances is a flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Returns:
    
    the NeedAppearances property as a PdfBoolean. Default value is false
  - setSignatureFlags
```
public PdfAcroForm setSignatureFlags(int sigFlags)
```
    Sets the SigFlags integer property on the AcroForm.
    
    SigFlags is a set of flags specifying various document-level characteristics related to signature fields. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Parameters:
    
    sigFlags - an integer. Use SIGNATURE_EXIST and/or APPEND_ONLY. Use bitwise OR operator to combine these values. Default value is 0
    
    Returns:
    
    current AcroForm.
  - setSignatureFlag
```
public PdfAcroForm setSignatureFlag(int sigFlag)
```
    Changes the SigFlags integer property on the AcroForm. This method allows only to add flags, not to remove them.
    
    SigFlags is a set of flags specifying various document-level characteristics related to signature fields. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Parameters:
    
    sigFlag - an integer. Use SIGNATURE_EXIST and/or APPEND_ONLY. Use bitwise OR operator to combine these values. Default is 0
    
    Returns:
    
    current AcroForm.
  - getSignatureFlags
```
public int getSignatureFlags()
```
    Gets the SigFlags integer property on the AcroForm.
    
    SigFlags is a set of flags specifying various document-level characteristics related to signature fields (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Returns:
    
    current value for SigFlags.
  - setCalculationOrder
```
public PdfAcroForm setCalculationOrder(PdfArray calculationOrder)
```
    Sets the CO array property on the AcroForm.
    
    CO, Calculation Order, is an array of indirect references to field dictionaries with calculation actions, defining the calculation order in which their values will be recalculated when the value of any field changes (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Parameters:
    
    calculationOrder - an array of indirect references
    
    Returns:
    
    current AcroForm
  - getCalculationOrder
```
public PdfArray getCalculationOrder()
```
    Gets the CO array property on the AcroForm.
    
    CO, Calculation Order, is an array of indirect references to field dictionaries with calculation actions, defining the calculation order in which their values will be recalculated when the value of any field changes (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Returns:
    
    an array of indirect references
  - setDefaultResources
```
public PdfAcroForm setDefaultResources(PdfDictionary defaultResources)
```
    Sets the DR dictionary property on the AcroForm.
    
    DR is a resource dictionary containing default resources (such as fonts, patterns, or colour spaces) that shall be used by form field appearance streams. At a minimum, this dictionary shall contain a Font entry specifying the resource name and font dictionary of the default font for displaying text. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Parameters:
    
    defaultResources - a resource dictionary
    
    Returns:
    
    current AcroForm
  - getDefaultResources
```
public PdfDictionary getDefaultResources()
```
    Gets the DR dictionary property on the AcroForm.
    
    DR is a resource dictionary containing default resources (such as fonts, patterns, or colour spaces) that shall be used by form field appearance streams. At a minimum, this dictionary shall contain a Font entry specifying the resource name and font dictionary of the default font for displaying text. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Returns:
    
    a resource dictionary
  - setDefaultAppearance
```
public PdfAcroForm setDefaultAppearance(String appearance)
```
    Sets the DA String property on the AcroForm.
    This method sets a default (fallback value) for the DA attribute of variable text form fields.
    
    Parameters:
    
    appearance - a String containing a sequence of valid PDF syntax
    
    Returns:
    
    current AcroForm
    
    See Also:
    
    PdfFormField.setDefaultAppearance(java.lang.String)
  - getDefaultAppearance
```
public PdfString getDefaultAppearance()
```
    Gets the DA String property on the AcroForm.
    This method returns the default (fallback value) for the DA attribute of variable text form fields.
    
    Returns:
    
    the form-wide default appearance, as a String
  - setDefaultJustification
```
public PdfAcroForm setDefaultJustification(int justification)
```
    Sets the Q integer property on the AcroForm.
    This method sets a default (fallback value) for the Q attribute of variable text form fields.
    
    Parameters:
    
    justification - an integer representing a justification value
    
    Returns:
    
    current AcroForm
    
    See Also:
    
    PdfFormField.setJustification(int)
  - getDefaultJustification
```
public PdfNumber getDefaultJustification()
```
    Gets the Q integer property on the AcroForm.
    This method gets the default (fallback value) for the Q attribute of variable text form fields.
    
    Returns:
    
    an integer representing a justification value
    
    See Also:
    
    PdfFormField.getJustification()
  - setXFAResource
```
public PdfAcroForm setXFAResource(PdfStream xfaResource)
```
    Sets the XFA property on the AcroForm.
    XFA can either be a PdfStream or a PdfArray. Its contents must be valid XFA.
    
    Parameters:
    
    xfaResource - a stream containing the XDP
    
    Returns:
    
    current AcroForm
  - setXFAResource
```
public PdfAcroForm setXFAResource(PdfArray xfaResource)
```
    Sets the XFA property on the AcroForm.
    XFA can either be a PdfStream or a PdfArray. Its contents must be valid XFA.
    
    Parameters:
    
    xfaResource - an array of text string and stream pairs representing the individual packets comprising the XML Data Package. (ISO 32000-1, section 12.7.2 "Interactive Form Dictionary")
    
    Returns:
    
    current AcroForm
  - getXFAResource
```
public PdfObject getXFAResource()
```
    Gets the XFA property on the AcroForm.
    
    Returns:
    
    an object representing the entire XDP. It can either be a PdfStream or a PdfArray.
  - getField
```
public PdfFormField getField(String fieldName)
```
    Gets a form field by its name.
    
    Parameters:
    
    fieldName - the name of the form field to retrieve
    
    Returns:
    
    the form field, or null if it isn't present
  - isGenerateAppearance
```
public boolean isGenerateAppearance()
```
    Gets the attribute generateAppearance, which tells flattenFields() to generate an appearance Stream for all form fields that don't have one.
    
    Returns:
    
    bolean value indicating if the appearances need to be generated
  - setGenerateAppearance
```
public void setGenerateAppearance(boolean generateAppearance)
```
    Sets the attribute generateAppearance, which tells flattenFields() to generate an appearance Stream for all form fields that don't have one.
    Not generating appearances will speed up form flattening but the results can be unexpected in Acrobat. Don't use it unless your environment is well controlled. The default is true.
    
    If generateAppearance is set to true, then NeedAppearances is set to false. This does not apply vice versa.
    
    Note, this method does not change default behaviour of PdfFormField.setValue(String) method.
    
    Parameters:
    
    generateAppearance - a boolean
  - flattenFields
```
public void flattenFields()
```
    Flattens interactive form fields in the document. If no fields have been explicitly included via partialFormFlattening(java.lang.String), then all fields are flattened. Otherwise only the included fields are flattened.
  - removeField
```
public boolean removeField(String fieldName)
```
    Tries to remove the form field with the specified name from the document.
    
    Parameters:
    
    fieldName - the name of the form field to remove
    
    Returns:
    
    a boolean representing whether or not the removal succeeded.
  - partialFormFlattening
```
public void partialFormFlattening(String fieldName)
```
    Adds a form field, identified by name, to the list of fields to be flattened. Does not perform a flattening operation in itself.
    
    Parameters:
    
    fieldName - the name of the form field to be flattened
  - renameField
```
public void renameField(String oldName,
                        String newName)
```
    Changes the identifier of a form field.
    
    Parameters:
    
    oldName - the current name of the field
    
    newName - the new name of the field. Must not be used currently.
  - copyField
```
public PdfFormField copyField(String name)
```
    Creates an in-memory copy of a PdfFormField. This new field is not added to the document.
    
    Parameters:
    
    name - the name of the form field to be copied
    
    Returns:
    
    a clone of the original PdfFormField
  - replaceField
```
public void replaceField(String name,
                         PdfFormField field)
```
    Replaces the PdfFormField of a certain name with another PdfFormField.
    
    Parameters:
    
    name - the name of the form field to be replaced
    
    field - the new PdfFormField
  - getFields
```
protected PdfArray getFields()
```
    Gets all AcroForm fields in the document.
    
    Returns:
    
    a PdfArray of field dictionaries
  - isWrappedObjectMustBeIndirect
```
protected boolean isWrappedObjectMustBeIndirect()
```
    Description copied from class: PdfObjectWrapper
    
    Defines if the object behind this wrapper must be an indirect object in the resultant document.
    
    If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.
    
    Return value of this method shouldn't depend on any logic, it should return always true or false.
    
    Specified by:
    
    isWrappedObjectMustBeIndirect in class PdfObjectWrapper<PdfDictionary>
    
    Returns:
    
    true if in the resultant document the object behind the wrapper must be indirect, otherwise false.
  - hasXfaForm
```
public boolean hasXfaForm()
```
    Determines whether the AcroForm contains XFA data.
    
    Returns:
    
    a boolean
  - getXfaForm
```
public XfaForm getXfaForm()
```
    Gets the XfaForm atribute.
    
    Returns:
    
    the XFA form object
  - removeXfaForm
```
public void removeXfaForm()
```
    Removes the XFA stream from the document.
  - put
```
public PdfAcroForm put(PdfName key,
                       PdfObject value)
```
  - release
```
public void release()
```
    Releases underlying pdf object and other pdf entities used by wrapper. This method should be called instead of direct call to PdfObject.release() if the wrapper is used.
  - setModified
```
public PdfObjectWrapper<PdfDictionary> setModified()
```
    Overrides:
    
    setModified in class PdfObjectWrapper<PdfDictionary>

Class PdfAcroForm

Field Summary

Method Summary

Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper

Methods inherited from class java.lang.Object

Field Detail

SIGNATURE_EXIST

APPEND_ONLY

generateAppearance

fields

document

Method Detail

getAcroForm

addField

addField

addFieldAppearanceToPage

getFormFields

getFieldsForFlattening

getPdfDocument

setNeedAppearances

getNeedAppearances

setSignatureFlags

setSignatureFlag

getSignatureFlags

setCalculationOrder

getCalculationOrder

setDefaultResources

getDefaultResources

setDefaultAppearance

getDefaultAppearance

setDefaultJustification

getDefaultJustification

setXFAResource

setXFAResource

getXFAResource

getField

isGenerateAppearance

setGenerateAppearance

flattenFields

removeField

partialFormFlattening

renameField

copyField

replaceField

getFields

isWrappedObjectMustBeIndirect

hasXfaForm

getXfaForm

removeXfaForm

put

release

setModified