Table of Contents

Class PdfAcroForm

Namespace
iText.Forms
Assembly
itext.forms.dll

This class represents the static form technology AcroForm on a PDF file.

public class PdfAcroForm : PdfObjectWrapper<PdfDictionary>
Inheritance
PdfAcroForm
Inherited Members

Fields

APPEND_ONLY

To be used with SetSignatureFlags(int).

public const int APPEND_ONLY = 2

Field Value

int

Remarks

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")

SIGNATURE_EXIST

To be used with SetSignatureFlags(int).

public const int SIGNATURE_EXIST = 1

Field Value

int

Remarks

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")

document

The PdfDocument to which the PdfAcroForm belongs.

protected PdfDocument document

Field Value

PdfDocument

fields

A map of field names and their associated form field objects.

protected IDictionary<string, PdfFormField> fields

Field Value

IDictionary<string, PdfFormField>

generateAppearance

Keeps track of whether or not appearances must be generated by the form fields themselves, or by the PDF viewer application.

protected bool generateAppearance

Field Value

bool

Remarks

Keeps track of whether or not appearances must be generated by the form fields themselves, or by the PDF viewer application. Default is true.

Methods

AddField(PdfFormField)

This method adds the field to the last page in the document.

public virtual void AddField(PdfFormField field)

Parameters

field PdfFormField

the PdfFormField to be added to the form

Remarks

This method adds the field to the last page in the document. If there's no pages, creates a new one.

AddField(PdfFormField, PdfPage)

This method adds the field to a specific page.

public virtual void AddField(PdfFormField field, PdfPage page)

Parameters

field PdfFormField

the PdfFormField to be added to the form

page PdfPage

the PdfPage on which to add the field

AddField(PdfFormField, PdfPage, bool)

This method adds the field to a specific page.

public virtual void AddField(PdfFormField field, PdfPage page, bool throwExceptionOnError)

Parameters

field PdfFormField

the PdfFormField to be added to the form

page PdfPage

the PdfPage on which to add the field

throwExceptionOnError bool

true if the exception is expected to be thrown in case of error.

AddFieldAppearanceToPage(PdfFormField, PdfPage)

This method merges field with its annotation and places it on the given page.

public virtual void AddFieldAppearanceToPage(PdfFormField field, PdfPage page)

Parameters

field PdfFormField

the PdfFormField to be added to the form

page PdfPage

the PdfPage on which to add the field

Remarks

This method merges field with its annotation and places it on the given page. This method also work if the field has more than one widget annotation, but doesn't work with no annotations.

CopyField(string)

Creates an in-memory copy of a PdfFormField.

public virtual PdfFormField CopyField(string name)

Parameters

name string

the name of the form field to be copied

Returns

PdfFormField

a clone of the original PdfFormField

Remarks

Creates an in-memory copy of a PdfFormField . This new field is not added to the document.

DisableRegenerationForAllFields()

Disables appearance stream regeneration for all the root fields in the Acroform, so all of its children in the hierarchy will also not be regenerated.

public virtual void DisableRegenerationForAllFields()

EnableRegenerationForAllFields()

Enables appearance stream regeneration for all the fields in the Acroform and regenerates them.

public virtual void EnableRegenerationForAllFields()

FlattenFields()

Flattens interactive form field s in the document.

public virtual void FlattenFields()

Remarks

Flattens interactive form field s in the document. If no fields have been explicitly included via PartialFormFlattening(string) , then all fields are flattened. Otherwise only the included fields are flattened.

GetAcroForm(PdfDocument, bool)

Retrieves AcroForm from the document.

public static PdfAcroForm GetAcroForm(PdfDocument document, bool createIfNotExist)

Parameters

document PdfDocument

the document to retrieve the PdfAcroForm from

createIfNotExist bool

when true, this method will create a PdfAcroForm if none exists for this document

Returns

PdfAcroForm

the document 's AcroForm, or a new one provided that createIfNotExist parameter is true, otherwise null.

Remarks

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.

GetAcroForm(PdfDocument, bool, OnDuplicateFormFieldNameStrategy)

Retrieves AcroForm from the document.

public static PdfAcroForm GetAcroForm(PdfDocument document, bool createIfNotExist, OnDuplicateFormFieldNameStrategy onDuplicateFieldNameStrategy)

Parameters

document PdfDocument

the document to retrieve the PdfAcroForm from

createIfNotExist bool

when true, this method will create a PdfAcroForm if none exists for this document

onDuplicateFieldNameStrategy OnDuplicateFormFieldNameStrategy

the strategy to be used when a field with the same name already exists

Returns

PdfAcroForm

the document 's AcroForm, or a new one provided that createIfNotExist parameter is true, otherwise null.

Remarks

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.

GetAllFormFields()

Gets all form field s as a including fields kids.

public virtual IDictionary<string, PdfFormField> GetAllFormFields()

Returns

IDictionary<string, PdfFormField>

a map of field names and their associated form field objects

GetAllFormFieldsAndAnnotations()

Gets all form field s as a including fields kids and nameless fields.

public virtual ICollection<AbstractPdfFormField> GetAllFormFieldsAndAnnotations()

Returns

ICollection<AbstractPdfFormField>

a set of form field objects.

GetCalculationOrder()

Gets the CO array property on the AcroForm.

public virtual PdfArray GetCalculationOrder()

Returns

PdfArray

an array of indirect references

Remarks

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")

GetDefaultAppearance()

Gets the DA String property on the AcroForm.

public virtual PdfString GetDefaultAppearance()

Returns

PdfString

the form-wide default appearance, as a String

Remarks

Gets the DA String property on the AcroForm.
This method returns the default (fallback value) for the DA attribute of variable text form field s.

GetDefaultJustification()

Gets the Q integer property on the AcroForm.

public virtual PdfNumber GetDefaultJustification()

Returns

PdfNumber

an integer representing a justification value

Remarks

Gets the Q integer property on the AcroForm.
This method gets the default (fallback value) for the Q attribute of variable text form field s.

See Also

GetDefaultResources()

Gets the DR dictionary property on the AcroForm.

public virtual PdfDictionary GetDefaultResources()

Returns

PdfDictionary

a resource dictionary

Remarks

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")

GetField(string)

Gets a form field by its name.

public virtual PdfFormField GetField(string fieldName)

Parameters

fieldName string

the name of the form field to retrieve

Returns

PdfFormField

the form field , or null if it isn't present

GetFields()

Gets all AcroForm fields in the document.

protected virtual PdfArray GetFields()

Returns

PdfArray

a PdfArray of field dictionaries

GetFieldsForFlattening()

Gets a collection of form field s, prepared for flattening using PartialFormFlattening(string) method.

public virtual ICollection<PdfFormField> GetFieldsForFlattening()

Returns

ICollection<PdfFormField>

a collection of form field s for flattening

Remarks

Gets a collection of form field s, prepared for flattening using PartialFormFlattening(string) method. If returned collection is empty, all form fields will be flattened on flattenFields call.

GetNeedAppearances()

Gets the NeedAppearances boolean property on the AcroForm.

public virtual PdfBoolean GetNeedAppearances()

Returns

PdfBoolean

the NeedAppearances property as a PdfBoolean . Default value is false

Remarks

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")

GetPdfDocument()

Gets the PdfDocument this PdfAcroForm belongs to.

public virtual PdfDocument GetPdfDocument()

Returns

PdfDocument

the document of this form

GetRootFormFields()

Gets root fields (i.e. direct children of Acroform dictionary).

public virtual IDictionary<string, PdfFormField> GetRootFormFields()

Returns

IDictionary<string, PdfFormField>

a map of field names and their associated form field objects

GetSignatureFlags()

Gets the SigFlags integer property on the AcroForm.

public virtual int GetSignatureFlags()

Returns

int

current value for SigFlags.

Remarks

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")

GetXFAResource()

Gets the XFA property on the AcroForm.

public virtual PdfObject GetXFAResource()

Returns

PdfObject

an object representing the entire XDP. It can either be a PdfStream or a PdfArray.

GetXfaForm()

Gets the XfaForm atribute.

public virtual XfaForm GetXfaForm()

Returns

XfaForm

the XFA form object

HasXfaForm()

Determines whether the AcroForm contains XFA data.

public virtual bool HasXfaForm()

Returns

bool

a boolean

IsGenerateAppearance()

Gets the attribute generateAppearance, which tells FlattenFields() to generate an appearance Stream for all form field s that don't have one.

public virtual bool IsGenerateAppearance()

Returns

bool

bolean value indicating if the appearances need to be generated

IsWrappedObjectMustBeIndirect() 

protected override bool IsWrappedObjectMustBeIndirect()

Returns

bool

PartialFormFlattening(string)

Adds a form field , identified by name, to the list of fields to be flattened.

public virtual void PartialFormFlattening(string fieldName)

Parameters

fieldName string

the name of the form field to be flattened

Remarks

Adds a form field , identified by name, to the list of fields to be flattened. Does not perform a flattening operation in itself.

Put(PdfName, PdfObject)

Put a key/value pair in the dictionary and overwrite previous value if it already exists.

public virtual PdfAcroForm Put(PdfName key, PdfObject value)

Parameters

key PdfName

the key as pdf name

value PdfObject

the value as pdf object

Returns

PdfAcroForm

this PdfAcroForm instance

Release()

Releases underlying pdf object and other pdf entities used by wrapper.

public virtual void Release()

Remarks

Releases underlying pdf object and other pdf entities used by wrapper. This method should be called instead of direct call to Release() if the wrapper is used.

RemoveField(string)

Tries to remove the form field with the specified name from the document.

public virtual bool RemoveField(string fieldName)

Parameters

fieldName string

the name of the form field to remove

Returns

bool

a boolean representing whether or not the removal succeeded.

RemoveXfaForm()

Removes the XFA stream from the document.

public virtual void RemoveXfaForm()

RenameField(string, string)

Changes the identifier of a form field.

public virtual void RenameField(string oldName, string newName)

Parameters

oldName string

the current name of the field

newName string

the new name of the field. Must not be used currently.

ReplaceField(string, PdfFormField)

Replaces the PdfFormField of a certain name with another PdfFormField.

public virtual void ReplaceField(string name, PdfFormField field)

Parameters

name string

the name of the form field to be replaced

field PdfFormField

the new PdfFormField

SetCalculationOrder(PdfArray)

Sets the CO array property on the AcroForm.

public virtual PdfAcroForm SetCalculationOrder(PdfArray calculationOrder)

Parameters

calculationOrder PdfArray

an array of indirect references

Returns

PdfAcroForm

current AcroForm

Remarks

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")

SetDefaultAppearance(string)

Sets the DA String property on the AcroForm.

public virtual PdfAcroForm SetDefaultAppearance(string appearance)

Parameters

appearance string

a String containing a sequence of valid PDF syntax

Returns

PdfAcroForm

current AcroForm

Remarks

Sets the DA String property on the AcroForm.
This method sets a default (fallback value) for the DA attribute of variable text form field s.

SetDefaultJustification(int)

Sets the Q integer property on the AcroForm.

public virtual PdfAcroForm SetDefaultJustification(int justification)

Parameters

justification int

an integer representing a justification value

Returns

PdfAcroForm

current AcroForm

Remarks

Sets the Q integer property on the AcroForm.
This method sets a default (fallback value) for the Q attribute of variable text form field s.

See Also

SetDefaultResources(PdfDictionary)

Sets the DR dictionary property on the AcroForm.

public virtual PdfAcroForm SetDefaultResources(PdfDictionary defaultResources)

Parameters

defaultResources PdfDictionary

a resource dictionary

Returns

PdfAcroForm

current AcroForm

Remarks

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")

SetGenerateAppearance(bool)

Sets the attribute generateAppearance, which tells FlattenFields() to generate an appearance Stream for all form field s that don't have one.

public virtual void SetGenerateAppearance(bool generateAppearance)

Parameters

generateAppearance bool

a boolean

Remarks

Sets the attribute generateAppearance, which tells FlattenFields() to generate an appearance Stream for all form field s 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 SetValue(string) method.

SetModified() 

public override PdfObjectWrapper<PdfDictionary> SetModified()

Returns

PdfObjectWrapper<PdfDictionary>

SetNeedAppearances(bool)

Sets the NeedAppearances boolean property on the AcroForm.

public virtual PdfAcroForm SetNeedAppearances(bool needAppearances)

Parameters

needAppearances bool

a boolean. Default value is false

Returns

PdfAcroForm

current AcroForm.

Remarks

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")

SetSignatureFlag(int)

Changes the SigFlags integer property on the AcroForm.

public virtual PdfAcroForm SetSignatureFlag(int sigFlag)

Parameters

sigFlag int

an integer. Use SIGNATURE_EXIST and/or APPEND_ONLY. Use bitwise OR operator to combine these values. Default is 0

Returns

PdfAcroForm

current AcroForm.

Remarks

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")

SetSignatureFlags(int)

Sets the SigFlags integer property on the AcroForm.

public virtual PdfAcroForm SetSignatureFlags(int sigFlags)

Parameters

sigFlags int

an integer. Use SIGNATURE_EXIST and/or APPEND_ONLY. Use bitwise OR operator to combine these values. Default value is 0

Returns

PdfAcroForm

current AcroForm.

Remarks

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")

SetXFAResource(PdfArray)

Sets the XFA property on the AcroForm.

public virtual PdfAcroForm SetXFAResource(PdfArray xfaResource)

Parameters

xfaResource PdfArray

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

PdfAcroForm

current AcroForm

Remarks

Sets the XFA property on the AcroForm.
XFA can either be a PdfStream or a PdfArray. Its contents must be valid XFA.

SetXFAResource(PdfStream)

Sets the XFA property on the AcroForm.

public virtual PdfAcroForm SetXFAResource(PdfStream xfaResource)

Parameters

xfaResource PdfStream

a stream containing the XDP

Returns

PdfAcroForm

current AcroForm

Remarks

Sets the XFA property on the AcroForm.
XFA can either be a PdfStream or a PdfArray. Its contents must be valid XFA.