Class AcroFields

Namespace

iTextSharp.text.pdf

Assembly

iTextSharp.LGPLv2.Core.dll

Query and change fields in existing documents either by method calls or by FDF merging. @author Paulo Soares (psoares@consiste.pt)

public class AcroFields

Inheritance

object

AcroFields

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Fields

DA_COLOR

public const int DA_COLOR = 2

Field Value

int

DA_FONT

public const int DA_FONT = 0

Field Value

int

DA_SIZE

public const int DA_SIZE = 1

Field Value

int

FIELD_TYPE_CHECKBOX

A field type.

public const int FIELD_TYPE_CHECKBOX = 2

Field Value

int

FIELD_TYPE_COMBO

A field type.

public const int FIELD_TYPE_COMBO = 6

Field Value

int

FIELD_TYPE_LIST

A field type.

public const int FIELD_TYPE_LIST = 5

Field Value

int

FIELD_TYPE_NONE

A field type invalid or not found.

public const int FIELD_TYPE_NONE = 0

Field Value

int

FIELD_TYPE_PUSHBUTTON

A field type.

public const int FIELD_TYPE_PUSHBUTTON = 1

Field Value

int

FIELD_TYPE_RADIOBUTTON

A field type.

public const int FIELD_TYPE_RADIOBUTTON = 3

Field Value

int

FIELD_TYPE_SIGNATURE

A field type.

public const int FIELD_TYPE_SIGNATURE = 7

Field Value

int

FIELD_TYPE_TEXT

A field type.

public const int FIELD_TYPE_TEXT = 4

Field Value

int

Properties

FieldCache

Sets a cache for field appearances. Parsing the existing PDF to create a new TextField is time expensive. For those tasks that repeatedly fill the same PDF with different field values the use of the cache has dramatic speed advantages. An example usage: String pdfFile = ...;// the pdf file used as template ArrayList xfdfFiles = ...;// the xfdf file names ArrayList pdfOutFiles = ...;// the output file names, one for each element in xpdfFiles Hashtable cache = new Hashtable();// the appearances cache PdfReader originalReader = new PdfReader(pdfFile); for (int k = 0; k < xfdfFiles.Size(); ++k) { PdfReader reader = new PdfReader(originalReader); XfdfReader xfdf = new XfdfReader((String)xfdfFiles.Get(k)); PdfStamper stp = new PdfStamper(reader, new FileOutputStream((String)pdfOutFiles.Get(k))); AcroFields af = stp.GetAcroFields(); af.SetFieldCache(cache); af.SetFields(xfdf); stp.Close(); }

public INullValueDictionary<string, TextField> FieldCache { get; set; }

Property Value

INullValueDictionary<string, TextField>

Fields

Gets all the fields. The fields are keyed by the fully qualified field name and the value is an instance of AcroFields.Item .

public INullValueDictionary<string, AcroFields.Item> Fields { get; }

Property Value

INullValueDictionary<string, AcroFields.Item>

all the fields

GenerateAppearances

Sets the option to generate appearances. Not generating apperances will speed-up form filling but the results can be unexpected in Acrobat. Don't use it unless your environment is well controlled. The default is true .

public bool GenerateAppearances { get; set; }

Property Value

bool

SubstitutionFonts

Sets a list of substitution fonts. The list is composed of BaseFont and can also be null . The fonts in this list will be used if the original font doesn't contain the needed glyphs.

public IList<BaseFont> SubstitutionFonts { get; set; }

Property Value

IList<BaseFont>

TotalRevisions

Gets the total number of revisions this document has.

public int TotalRevisions { get; }

Property Value

int

the total number of revisions

Xfa

Gets the XFA form processor.

public XfaForm Xfa { get; }

Property Value

XfaForm

the XFA form processor

Methods

AddSubstitutionFont(BaseFont)

Adds a substitution font to the list. The fonts in this list will be used if the original font doesn't contain the needed glyphs.

public void AddSubstitutionFont(BaseFont font)

Parameters

font BaseFont

the font

DecodeGenericDictionary(PdfDictionary, BaseField)

public void DecodeGenericDictionary(PdfDictionary merged, BaseField tx)

Parameters

merged PdfDictionary

tx BaseField

ExportAsFdf(FdfWriter)

Export the fields as a FDF.

public void ExportAsFdf(FdfWriter writer)

Parameters

writer FdfWriter

the FDF writer

ExtractRevision(string)

Extracts a revision from the document. it's not a signature field @throws IOException on error

public Stream ExtractRevision(string field)

Parameters

field string

the signature field name

Returns

Stream

an Stream covering the revision. Returns null if

GetAppearanceStates(string)

Gets the list of appearance names. Use it to get the names allowed with radio and checkbox fields. If the /Opt key exists the values will also be included. The name 'Off' may also be valid even if not returned in the list.

public string[] GetAppearanceStates(string fieldName)

Parameters

fieldName string

the fully qualified field name

Returns

string[]

the list of names or null if the field does not exist

GetBlankSignatureNames()

Gets the field names that have blank signatures.

public IList<string> GetBlankSignatureNames()

Returns

IList<string>

the field names that have blank signatures

GetField(string)

Gets the field value.

public string GetField(string name)

Parameters

name string

the fully qualified field name

Returns

string

the field value

GetFieldAndPositions(string)

Gets the field by name, and positions.

public List<object> GetFieldAndPositions(string name)

Parameters

name string

the name of the field

Returns

List<object>

arraylist with value and positions

GetFieldItem(string)

Gets the field structure. does not exist

public AcroFields.Item GetFieldItem(string name)

Parameters

name string

the name of the field

Returns

AcroFields.Item

the field structure or null if the field

GetFieldPositions(string)

Gets the field box positions in the document. The return is an array of float multiple of 5. For each of this groups the values are: [page, llx, lly, urx, ury]. The coordinates have the page rotation in consideration.

public float[] GetFieldPositions(string name)

Parameters

name string

the field name

Returns

float[]

the positions or null if field does not exist

GetFieldType(string)

Gets the field type. The type can be one of: FIELD_TYPE_PUSHBUTTON , FIELD_TYPE_CHECKBOX , FIELD_TYPE_RADIOBUTTON , FIELD_TYPE_TEXT , FIELD_TYPE_LIST , FIELD_TYPE_COMBO or FIELD_TYPE_SIGNATURE . If the field does not exist or is invalid it returns FIELD_TYPE_NONE .

public int GetFieldType(string fieldName)

Parameters

fieldName string

the field name

Returns

int

the field type

GetListOptionDisplay(string)

Gets the list of display option values from fields of type list or combo. If the field doesn't exist or the field type is not list or combo it will return null .

public string[] GetListOptionDisplay(string fieldName)

Parameters

fieldName string

the field name

Returns

string[]

the list of export option values from fields of type list or combo

GetListOptionExport(string)

Gets the list of export option values from fields of type list or combo. If the field doesn't exist or the field type is not list or combo it will return null .

public string[] GetListOptionExport(string fieldName)

Parameters

fieldName string

the field name

Returns

string[]

the list of export option values from fields of type list or combo

GetListSelection(string)

Gets the field values of a Choice field. @since 2.1.3

public string[] GetListSelection(string name)

Parameters

name string

the fully qualified field name

Returns

string[]

the field value

GetNewPushbuttonFromField(string)

Creates a new pushbutton from an existing field. If there are several pushbuttons with the same name only the first one is used. This pushbutton can be changed and be used to replace an existing one, with the same name or other name, as long is it is in the same document. To replace an existing pushbutton call {@link #replacePushbuttonField(String,PdfFormField)}.

public PushbuttonField GetNewPushbuttonFromField(string field)

Parameters

field string

the field name that should be a pushbutton

Returns

PushbuttonField

a new pushbutton or null if the field is not a pushbutton

GetNewPushbuttonFromField(string, int)

Creates a new pushbutton from an existing field. This pushbutton can be changed and be used to replace an existing one, with the same name or other name, as long is it is in the same document. To replace an existing pushbutton call {@link #replacePushbuttonField(String,PdfFormField,int)}.

public PushbuttonField GetNewPushbuttonFromField(string field, int order)

Parameters

field string

the field name that should be a pushbutton

order int

the field order in fields with same name

Returns

PushbuttonField

a new pushbutton or null if the field is not a pushbutton

GetRevision(string)

Gets this field revision.

public int GetRevision(string field)

Parameters

field string

the signature field name

Returns

int

the revision or zero if it's not a signature field

GetSignatureDictionary(string)

Gets the signature dictionary, the one keyed by /V. a signature

public PdfDictionary GetSignatureDictionary(string name)

Parameters

name string

the field name

Returns

PdfDictionary

the signature dictionary keyed by /V or null if the field is not

GetSignatureNames()

Gets the field names that have signatures and are signed.

public IList<string> GetSignatureNames()

Returns

IList<string>

the field names that have signatures and are signed

GetTranslatedFieldName(string)

Gets the long XFA translated name.

public string GetTranslatedFieldName(string name)

Parameters

name string

the name of the field

Returns

string

the long field name

MergeXfaData(XmlNode)

Merges an XML data structure into this form. @throws java.io.IOException on error @throws com.lowagie.text.DocumentException o error

public void MergeXfaData(XmlNode n)

Parameters

n XmlNode

the top node of the data structure

RegenerateField(string)

Regenerates the field appearance. This is usefull when you change a field property, but not its value, for instance form.SetFieldProperty("f", "bgcolor", Color.BLUE, null); This won't have any effect, unless you use RegenerateField("f") after changing the property. @throws IOException on error @throws DocumentException on error false otherwise

public bool RegenerateField(string name)

Parameters

name string

the fully qualified field name or the partial name in the case of XFA forms

Returns

bool

true if the field was found and changed,

RemoveField(string)

Removes a field from the document.

public bool RemoveField(string name)

Parameters

name string

the field name

Returns

bool

true if the field exists, false otherwise

RemoveField(string, int)

Removes a field from the document. If page equals -1 all the fields with this name are removed from the document otherwise only the fields in that particular page are removed.

public bool RemoveField(string name, int page)

Parameters

name string

the field name

page int

the page to remove the field from or -1 to remove it from all the pages

Returns

bool

true if the field exists, false otherwise

RemoveFieldsFromPage(int)

Removes all the fields from page .

public bool RemoveFieldsFromPage(int page)

Parameters

page int

the page to remove the fields from

Returns

bool

true if any field was removed, false otherwise

RenameField(string, string)

Renames a field. Only the last part of the name can be renamed. For example, if the original field is "ab.cd.ef" only the "ef" part can be renamed. otherwise

public bool RenameField(string oldName, string newName)

Parameters

oldName string

the old field name

newName string

the new field name

Returns

bool

true if the renaming was successful, false

ReplacePushbuttonField(string, PdfFormField)

Replaces the first field with a new pushbutton. The pushbutton can be created with {@link #getNewPushbuttonFromField(String)} from the same document or it can be a generic PdfFormField of the type pushbutton. was not a pushbutton

public bool ReplacePushbuttonField(string field, PdfFormField button)

Parameters

field string

the field name

button PdfFormField

the PdfFormField representing the pushbutton

Returns

bool

true if the field was replaced, false if the field

ReplacePushbuttonField(string, PdfFormField, int)

Replaces the designated field with a new pushbutton. The pushbutton can be created with {@link #getNewPushbuttonFromField(String,int)} from the same document or it can be a generic PdfFormField of the type pushbutton. was not a pushbutton

public bool ReplacePushbuttonField(string field, PdfFormField button, int order)

Parameters

field string

the field name

button PdfFormField

the PdfFormField representing the pushbutton

order int

the field order in fields with same name

Returns

bool

true if the field was replaced, false if the field

SetExtraMargin(float, float)

Sets extra margins in text fields to better mimic the Acrobat layout.

public void SetExtraMargin(float extraMarginLeft, float extraMarginTop)

Parameters

extraMarginLeft float

the extra marging left

extraMarginTop float

the extra margin top

SetField(string, string)

Sets the field value. @throws IOException on error @throws DocumentException on error false otherwise

public bool SetField(string name, string value)

Parameters

name string

the fully qualified field name or the partial name in the case of XFA forms

value string

the field value

Returns

bool

true if the field was found and changed,

SetField(string, string, string)

Sets the field value and the display string. The display string is used to build the appearance in the cases where the value is modified by Acrobat with JavaScript and the algorithm is known. the value parameter will be used false otherwise @throws IOException on error @throws DocumentException on error

public bool SetField(string name, string value, string display)

Parameters

name string

the fully qualified field name or the partial name in the case of XFA forms

value string

the field value

display string

the string that is used for the appearance. If null

Returns

bool

true if the field was found and changed,

SetFieldProperty(string, string, int, int[])

Sets a field property. Valid property names are: flags - a set of flags specifying various characteristics of the field�s widget annotation. The value of this entry replaces that of the F entry in the form�s corresponding annotation dictionary. setflags - a set of flags to be set (turned on) in the F entry of the form�s corresponding widget annotation dictionary. Bits equal to 1 cause the corresponding bits in F to be set to 1. clrflags - a set of flags to be cleared (turned off) in the F entry of the form�s corresponding widget annotation dictionary. Bits equal to 1 cause the corresponding bits in F to be set to 0. fflags - a set of flags specifying various characteristics of the field. The value of this entry replaces that of the Ff entry in the form�s corresponding field dictionary. setfflags - a set of flags to be set (turned on) in the Ff entry of the form�s corresponding field dictionary. Bits equal to 1 cause the corresponding bits in Ff to be set to 1. clrfflags - a set of flags to be cleared (turned off) in the Ff entry of the form�s corresponding field dictionary. Bits equal to 1 cause the corresponding bits in Ff to be set to 0. Set to null to process all

public bool SetFieldProperty(string field, string name, int value, int[] inst)

Parameters

field string

the field name

name string

the property name

value int

the property value

inst int[]

an array of int indexing into AcroField.Item.merged elements to process.

Returns

bool

true if the property exists, false otherwise

SetFieldProperty(string, string, object, int[])

Sets a field property. Valid property names are: textfont - sets the text font. The value for this entry is a BaseFont . textcolor - sets the text color. The value for this entry is a java.awt.Color . textsize - sets the text size. The value for this entry is a Float . bgcolor - sets the background color. The value for this entry is a java.awt.Color . If null removes the background. bordercolor - sets the border color. The value for this entry is a java.awt.Color . If null removes the border. Set to null to process all

public bool SetFieldProperty(string field, string name, object value, int[] inst)

Parameters

field string

the field name

name string

the property name

value object

the property value

inst int[]

an array of int indexing into AcroField.Item.merged elements to process.

Returns

bool

true if the property exists, false otherwise

SetFields(FdfReader)

Sets the fields by FDF merging. @throws IOException on error @throws DocumentException on error

public void SetFields(FdfReader fdf)

Parameters

fdf FdfReader

the FDF form

SetFields(XfdfReader)

public void SetFields(XfdfReader xfdf)

Parameters

xfdf XfdfReader

SetListOption(string, string[], string[])

Sets the option list for fields of type list or combo. One of exportValues or displayValues may be null but not both. This method will only set the list but will not set the value or appearance. For that, calling setField() is required. An example: PdfReader pdf = new PdfReader("input.pdf"); PdfStamper stp = new PdfStamper(pdf, new FileOutputStream("output.pdf")); AcroFields af = stp.GetAcroFields(); af.SetListOption("ComboBox", new String[]{"a", "b", "c"}, new String[]{"first", "second", "third"}); af.SetField("ComboBox", "b"); stp.Close();

public bool SetListOption(string fieldName, string[] exportValues, string[] displayValues)

Parameters

fieldName string

the field name

exportValues string[]

the export values

displayValues string[]

the display values

Returns

bool

true if the operation succeeded, false otherwise

SetListSelection(string, string[])

Sets different values in a list selection. No appearance is generated yet; nor does the code check if multiple select is allowed. @since 2.1.4

public bool SetListSelection(string name, string[] value)

Parameters

name string

the name of the field

value string[]

an array with values that need to be selected

Returns

bool

true only if the field value was changed

SignatureCoversWholeDocument(string)

Checks is the signature covers the entire document or just part of it. false otherwise

public bool SignatureCoversWholeDocument(string name)

Parameters

name string

the signature field name

Returns

bool

true if the signature covers the entire document,

SplitDAelements(string)

public static object[] SplitDAelements(string da)

Parameters

da string

Returns

object[]

VerifySignature(string)

Verifies a signature. An example usage is: KeyStore kall = PdfPKCS7.LoadCacertsKeyStore(); PdfReader reader = new PdfReader("my_signed_doc.pdf"); AcroFields af = reader.GetAcroFields(); ArrayList names = af.GetSignatureNames(); for (int k = 0; k < names.Size(); ++k) { String name = (String)names.Get(k); System.out.Println("Signature name: " + name); System.out.Println("Signature covers whole document: " + af.SignatureCoversWholeDocument(name)); PdfPKCS7 pk = af.VerifySignature(name); Calendar cal = pk.GetSignDate(); Certificate pkc[] = pk.GetCertificates(); System.out.Println("Subject: " + PdfPKCS7.GetSubjectFields(pk.GetSigningCertificate())); System.out.Println("Document modified: " + !pk.Verify()); Object fails[] = PdfPKCS7.VerifyCertificates(pkc, kall, null, cal); if (fails == null) System.out.Println("Certificates verified against the KeyStore"); else System.out.Println("Certificate failed: " + fails[1]); }

public PdfPkcs7 VerifySignature(string name)

Parameters

name string

the signature field name

Returns

PdfPkcs7

a PdfPKCS7 class to continue the verification