Table of Contents

Class PdfFormField

Namespace
iText.Forms.Fields
Assembly
itext.forms.dll

This class represents a single field or field group in an AcroForm.

public class PdfFormField : AbstractPdfFormField
Inheritance
PdfFormField
Derived
Inherited Members

Remarks

This class represents a single field or field group in an AcroForm.

To be able to be wrapped with this PdfObjectWrapper<T> the PdfObject must be indirect.

Constructors

PdfFormField(PdfWidgetAnnotation, PdfDocument)

Creates a form field as a parent of a PdfWidgetAnnotation.

protected PdfFormField(PdfWidgetAnnotation widget, PdfDocument pdfDocument)

Parameters

widget PdfWidgetAnnotation

The widget which will be a kid of the PdfFormField.

pdfDocument PdfDocument

The PdfDocument instance.

PdfFormField(PdfDictionary)

Creates a form field as a wrapper object around a PdfDictionary.

public PdfFormField(PdfDictionary pdfObject)

Parameters

pdfObject PdfDictionary

the dictionary to be wrapped, must have an indirect reference.

Remarks

Creates a form field as a wrapper object around a PdfDictionary. This PdfDictionary must be an indirect object.

PdfFormField(PdfDocument)

Creates a minimal PdfFormField.

protected PdfFormField(PdfDocument pdfDocument)

Parameters

pdfDocument PdfDocument

The PdfDocument instance.

Fields

FF_MULTILINE

Flag that designates, if set, that the field can contain multiple lines of text.

public static readonly int FF_MULTILINE

Field Value

int

FF_NO_EXPORT

The NoExport flag, which specifies whether or not exporting is forbidden.

public static readonly int FF_NO_EXPORT

Field Value

int

FF_PASSWORD

Flag that designates, if set, that the field's contents must be obfuscated.

public static readonly int FF_PASSWORD

Field Value

int

FF_READ_ONLY

The ReadOnly flag, which specifies whether or not the field can be changed.

public static readonly int FF_READ_ONLY

Field Value

int

FF_REQUIRED

The Required flag, which specifies whether or not the field must be filled in.

public static readonly int FF_REQUIRED

Field Value

int

checkType 

protected NullableContainer<CheckBoxType> checkType

Field Value

NullableContainer<CheckBoxType>

form 

protected PdfFormXObject form

Field Value

PdfFormXObject

img 

protected ImageData img

Field Value

ImageData

text 

protected string text

Field Value

string

Methods

AddKid(AbstractPdfFormField)

Adds a new kid to the Kids array property from a AbstractPdfFormField.

public virtual PdfFormField AddKid(AbstractPdfFormField kid)

Parameters

kid AbstractPdfFormField

a new AbstractPdfFormField entry for the field's Kids array property.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Adds a new kid to the Kids array property from a AbstractPdfFormField . Also sets the kid's Parent property to this object.

AddKid(AbstractPdfFormField, bool)

Adds a new kid to the Kids array property from a AbstractPdfFormField.

public virtual PdfFormField AddKid(AbstractPdfFormField kid, bool throwExceptionOnError)

Parameters

kid AbstractPdfFormField

a new AbstractPdfFormField entry for the field's Kids array property.

throwExceptionOnError bool

define whether exception (true) or log (false) is expected in case kid with the same name exists and merge of two kids failed.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Adds a new kid to the Kids array property from a AbstractPdfFormField . Also sets the kid's Parent property to this object.

AddKid(PdfWidgetAnnotation)

Adds a new kid to the Kids array property from a PdfWidgetAnnotation.

public virtual PdfFormField AddKid(PdfWidgetAnnotation kid)

Parameters

kid PdfWidgetAnnotation

a new PdfWidgetAnnotation entry for the field's Kids array property.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Adds a new kid to the Kids array property from a PdfWidgetAnnotation . Also sets the kid's Parent property to this object.

GetAdditionalAction()

Gets the currently additional action dictionary for the form field.

public virtual PdfDictionary GetAdditionalAction()

Returns

PdfDictionary

the additional action dictionary.

GetAllChildFields()

Gets all childFields of this object, including the children of the children.

public virtual IList<AbstractPdfFormField> GetAllChildFields()

Returns

IList<AbstractPdfFormField>

the children of the current field and their children.

GetAllChildFormFields()

Gets all childFields of this object, including the children of the children but not annotations.

public virtual IList<PdfFormField> GetAllChildFormFields()

Returns

IList<PdfFormField>

the children of the current field and their children.

GetAlternativeName()

Gets the current alternate name.

public virtual PdfString GetAlternativeName()

Returns

PdfString

the current alternate name, as a PdfString.

Remarks

Gets the current alternate name. The alternate is a descriptive name to be used by status messages etc.

GetAppearanceStates() 

public override string[] GetAppearanceStates()

Returns

string[]

GetChildField(string)

Gets the child field of form field.

public virtual PdfFormField GetChildField(string fieldName)

Parameters

fieldName string

a string , name of the received field.

Returns

PdfFormField

the child of the current field as a PdfFormField.

Remarks

Gets the child field of form field. If there is no child field with such name, null is returned.

GetChildFields()

Gets the childFields of this object.

public virtual IList<AbstractPdfFormField> GetChildFields()

Returns

IList<AbstractPdfFormField>

the children of the current field.

GetChildFormAnnotations()

Gets all child form field's annotations PdfFormAnnotation of this form field.

public virtual IList<PdfFormAnnotation> GetChildFormAnnotations()

Returns

IList<PdfFormAnnotation>

a list of PdfFormAnnotation.

GetChildFormFields()

Gets all child form fields of this form field.

public virtual IList<PdfFormField> GetChildFormFields()

Returns

IList<PdfFormField>

a list of PdfFormField.

Remarks

Gets all child form fields of this form field. Annotations are not returned.

GetDefaultAppearance() 

public override PdfString GetDefaultAppearance()

Returns

PdfString

GetDefaultStyle()

Gets a default style string, as described in "Rich Text Strings" section of Pdf spec.

public virtual PdfString GetDefaultStyle()

Returns

PdfString

the default style, as a PdfString.

GetDefaultValue()

Gets the default fallback value for the form field.

public virtual PdfObject GetDefaultValue()

Returns

PdfObject

the default value.

GetDisplayValue()

Gets the current display value of the form field.

public virtual string GetDisplayValue()

Returns

string

the current display value, as a string , if it exists. If not, returns the value as a string.

GetFieldFlag(int)

Checks whether a certain flag, or any of a combination of flags, is set for this form field.

public virtual bool GetFieldFlag(int flag)

Parameters

flag int

an int interpreted as a series of a binary flags.

Returns

bool

true if any of the flags specified in the parameter is also set in the form field.

GetFieldFlags()

Gets the current list of PDF form field flags.

public virtual int GetFieldFlags()

Returns

int

the current list of flags, encoded as an int.

GetFirstFormAnnotation()

Gets a single child form field's annotation PdfFormAnnotation.

public virtual PdfFormAnnotation GetFirstFormAnnotation()

Returns

PdfFormAnnotation

PdfFormAnnotation or null if there are no child annotations.

GetFormFieldKeys()

Gets a set of all possible form field keys except PdfName.Parent.

public static ICollection<PdfName> GetFormFieldKeys()

Returns

ICollection<PdfName>

a set of form field keys.

GetFormType()

Returns the type of the parent form field, or of the wrapped <PdfDictionary> object.

public virtual PdfName GetFormType()

Returns

PdfName

the form type, as a PdfName.

GetFormType(PdfDictionary)

Returns the type of the form field dictionary, or of the parent <PdfDictionary> object.

public static PdfName GetFormType(PdfDictionary fieldDict)

Parameters

fieldDict PdfDictionary

field dictionary to get its type.

Returns

PdfName

the form type, as a PdfName.

GetJustification()

Gets a code specifying the form of quadding (justification) to be used in displaying the text: 0 Left-justified 1 Centered 2 Right-justified

public virtual TextAlignment? GetJustification()

Returns

TextAlignment?

the current justification attribute.

GetKids()

Gets the kids of this object.

public virtual PdfArray GetKids()

Returns

PdfArray

contents of the dictionary's Kids property, as a PdfArray.

GetMappingName()

Gets the current mapping name.

public virtual PdfString GetMappingName()

Returns

PdfString

the current mapping name, as a PdfString.

Remarks

Gets the current mapping name. The mapping name can be used when exporting the form data in the document.

GetOptions()

Gets options for the form field.

public virtual PdfArray GetOptions()

Returns

PdfArray

the options, as an PdfArray of PdfString objects.

Remarks

Gets options for the form field. Should only return usable values for checkboxes and radio buttons.

GetPartialFieldName()

Gets the current field partial name.

public virtual PdfString GetPartialFieldName()

Returns

PdfString

the current field partial name, as a PdfString . If the field has no partial name, an empty PdfString is returned.

GetRichText()

Gets a rich text string, as described in "Rich Text Strings" section of Pdf spec.

public virtual PdfObject GetRichText()

Returns

PdfObject

the current rich text value.

Remarks

Gets a rich text string, as described in "Rich Text Strings" section of Pdf spec. May be either PdfStream or PdfString.

GetValue()

Gets the current value contained in the form field.

public virtual PdfObject GetValue()

Returns

PdfObject

the current value, as a PdfObject.

GetValueAsString()

Gets the current value contained in the form field.

public virtual string GetValueAsString()

Returns

string

the current value, as a string.

GetWidgets()

Gets all PdfWidgetAnnotation that its children refer to.

public virtual IList<PdfWidgetAnnotation> GetWidgets()

Returns

IList<PdfWidgetAnnotation>

a list of PdfWidgetAnnotation.

IsFormField(PdfDictionary)

Checks if dictionary contains any of the form field keys.

public static bool IsFormField(PdfDictionary dict)

Parameters

dict PdfDictionary

field dictionary to check.

Returns

bool

true if it is a form field dictionary, false otherwise.

IsInReadingMode()

Checks if the document that contains the field is created in reading mode.

public virtual bool IsInReadingMode()

Returns

bool

true if reading mode is used, false otherwise.

IsMultiline()

If true, the field can contain multiple lines of text; if false, the field's text is restricted to a single line.

public virtual bool IsMultiline()

Returns

bool

whether the field can span over multiple lines.

IsNoExport()

Gets the NoExport attribute.

public virtual bool IsNoExport()

Returns

bool

whether exporting the value following a form action is forbidden.

IsPassword()

If true, the field is intended for entering a secure password that should not be echoed visibly to the screen.

public virtual bool IsPassword()

Returns

bool

whether or not the contents of the field must be obfuscated.

Remarks

If true, the field is intended for entering a secure password that should not be echoed visibly to the screen. Characters typed from the keyboard should instead be echoed in some unreadable form, such as asterisks or bullet characters.

IsReadOnly()

Gets the ReadOnly flag, specifying whether or not the field can be changed.

public virtual bool IsReadOnly()

Returns

bool

true if the field cannot be changed.

IsRequired()

Gets the Required flag, specifying whether or not the field must be filled in.

public virtual bool IsRequired()

Returns

bool

true if the field must be filled in.

MakeFieldFlag(int)

Makes a field flag by bit position.

public static int MakeFieldFlag(int bitPosition)

Parameters

bitPosition int

bit position of a flag in range 1 to 32 from the pdf specification.

Returns

int

corresponding field flag.

Remarks

Makes a field flag by bit position. Bit positions are numbered 1 to 32. But position 0 corresponds to flag 1, position 3 corresponds to flag 4 etc.

MakeFormField(PdfObject, PdfDocument)

Creates a (subtype of) PdfFormField object.

public static PdfFormField MakeFormField(PdfObject pdfObject, PdfDocument document)

Parameters

pdfObject PdfObject

assumed to be either a PdfDictionary , or a PdfIndirectReference to a PdfDictionary.

document PdfDocument

the PdfDocument to create the field in.

Returns

PdfFormField

a new PdfFormField , or null if pdfObject is not a form field.

Remarks

Creates a (subtype of) PdfFormField object. The type of the object depends on the FT entry in the pdfObject parameter.

MakeFormFieldOrAnnotation(PdfObject, PdfDocument)

Creates a (subtype of) PdfFormField or PdfFormAnnotation object depending on pdfObject.

public static AbstractPdfFormField MakeFormFieldOrAnnotation(PdfObject pdfObject, PdfDocument document)

Parameters

pdfObject PdfObject

assumed to be either a PdfDictionary , or a PdfIndirectReference to a PdfDictionary.

document PdfDocument

the PdfDocument to create the field in.

Returns

AbstractPdfFormField

a new AbstractPdfFormField , or null if pdfObject is not a form field and is not a widget annotation.

RegenerateField() 

public override bool RegenerateField()

Returns

bool

Release() 

public override void Release()

RemoveChild(AbstractPdfFormField)

Removes the childField object of this field.

public virtual void RemoveChild(AbstractPdfFormField fieldName)

Parameters

fieldName AbstractPdfFormField

a PdfFormField , that needs to be removed from form field children.

RemoveChildren()

Removes all children from the current field.

public virtual void RemoveChildren()

SetAdditionalAction(PdfName, PdfAction)

Sets an additional action for the form field.

public virtual PdfFormField SetAdditionalAction(PdfName key, PdfAction action)

Parameters

key PdfName

the dictionary key to use for storing the action.

action PdfAction

the action.

Returns

PdfFormField

the edited PdfFormField.

SetAlternativeName(string)

Changes the alternate name of the field to the specified value.

public virtual PdfFormField SetAlternativeName(string name)

Parameters

name string

the new alternate name, as a String.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Changes the alternate name of the field to the specified value. The alternate is a descriptive name to be used by status messages etc.

SetCheckType(CheckBoxType)

Changes the type of graphical marker used to mark a checkbox as 'on'.

public virtual PdfFormField SetCheckType(CheckBoxType checkType)

Parameters

checkType CheckBoxType

the new checkbox marker.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Changes the type of graphical marker used to mark a checkbox as 'on'. Notice that in order to complete the change one should call regenerateField method.

SetColor(Color) 

public override AbstractPdfFormField SetColor(Color color)

Parameters

color Color

Returns

AbstractPdfFormField

SetDefaultStyle(PdfString)

Sets a default style string, as described in "Rich Text Strings" section of Pdf spec.

public virtual PdfFormField SetDefaultStyle(PdfString defaultStyleString)

Parameters

defaultStyleString PdfString

a new default style for the form field.

Returns

PdfFormField

the edited PdfFormField.

SetDefaultValue(PdfObject)

Sets the default fallback value for the form field.

public virtual PdfFormField SetDefaultValue(PdfObject value)

Parameters

value PdfObject

the default value.

Returns

PdfFormField

the edited PdfFormField.

SetFieldFlag(int)

Adds a flag, or combination of flags, for the form field.

public virtual PdfFormField SetFieldFlag(int flag)

Parameters

flag int

an int interpreted as a series of a binary flags.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Adds a flag, or combination of flags, for the form field. This method is intended to be used one flag at a time, but this is not technically enforced. To replace the current value, use SetFieldFlags(int).

SetFieldFlag(int, bool)

Adds or removes a flag, or combination of flags, for the form field.

public virtual PdfFormField SetFieldFlag(int flag, bool value)

Parameters

flag int

an int interpreted as a series of a binary flags.

value bool

if true, adds the flag(s). if false, removes the flag(s).

Returns

PdfFormField

the edited PdfFormField.

Remarks

Adds or removes a flag, or combination of flags, for the form field. This method is intended to be used one flag at a time, but this is not technically enforced. To replace the current value, use SetFieldFlags(int).

SetFieldFlags(int)

Sets a flag, or combination of flags, for the form field.

public virtual PdfFormField SetFieldFlags(int flags)

Parameters

flags int

an int interpreted as a series of a binary flags.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Sets a flag, or combination of flags, for the form field. This method replaces the previous value. Compare with SetFieldFlag(int) which adds a flag to the existing flags.

SetFieldName(string)

Changes the name of the field to the specified value.

public virtual PdfFormField SetFieldName(string name)

Parameters

name string

the new field name, as a String.

Returns

PdfFormField

the edited PdfFormField.

SetJustification(TextAlignment?)

Sets a code specifying the form of quadding (justification) to be used in displaying the text: 0 Left-justified 1 Centered 2 Right-justified

public virtual PdfFormField SetJustification(TextAlignment? justification)

Parameters

justification TextAlignment?

the value to set the justification attribute to.

Returns

PdfFormField

the edited PdfFormField.

SetMappingName(string)

Changes the mapping name of the field to the specified value.

public virtual PdfFormField SetMappingName(string name)

Parameters

name string

the new alternate name, as a String.

Returns

PdfFormField

the edited field.

Remarks

Changes the mapping name of the field to the specified value. The mapping name can be used when exporting the form data in the document.

SetNoExport(bool)

Sets the NoExport flag, specifying whether or not exporting is forbidden.

public virtual PdfFormField SetNoExport(bool noExport)

Parameters

noExport bool

if true, then exporting is forbidden

Returns

PdfFormField

the edited PdfFormField.

SetOptions(PdfArray)

Sets options for the form field.

public virtual PdfFormField SetOptions(PdfArray options)

Parameters

options PdfArray

an array of PdfString objects that each represent the 'on' state of one of the choices.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Sets options for the form field. Only to be used for checkboxes and radio buttons.

SetReadOnly(bool)

Sets the ReadOnly flag, specifying whether or not the field can be changed.

public virtual PdfFormField SetReadOnly(bool readOnly)

Parameters

readOnly bool

if true, then the field cannot be changed.

Returns

PdfFormField

the edited PdfFormField.

SetRequired(bool)

Sets the Required flag, specifying whether or not the field must be filled in.

public virtual PdfFormField SetRequired(bool required)

Parameters

required bool

if true, then the field must be filled in.

Returns

PdfFormField

the edited PdfFormField.

SetRichText(PdfObject)

Sets a rich text string, as described in "Rich Text Strings" section of Pdf spec.

public virtual PdfFormField SetRichText(PdfObject richText)

Parameters

richText PdfObject

a new rich text value.

Returns

PdfFormField

the edited PdfFormField.

Remarks

Sets a rich text string, as described in "Rich Text Strings" section of Pdf spec. May be either PdfStream or PdfString.

SetValue(string)

Sets a value to the field and generating field appearance if needed.

public virtual PdfFormField SetValue(string value)

Parameters

value string

of the field.

Returns

PdfFormField

the field.

SetValue(string, bool)

Sets a value to the field (and fields with the same names) and generates field appearance if needed.

public virtual PdfFormField SetValue(string value, bool generateAppearance)

Parameters

value string

of the field.

generateAppearance bool

if false, appearance won't be regenerated.

Returns

PdfFormField

the field.

SetValue(string, string)

Sets the field value and the display string.

public virtual PdfFormField SetValue(string value, string displayValue)

Parameters

value string

the field value.

displayValue string

the string that is used for the appearance. If null the value parameter will be used.

Returns

PdfFormField

the edited field.

Remarks

Sets the field value and the display string. The display string is used to build the appearance.

SetValue(string, PdfFont, float)

Set text field value with given font and size.

public virtual PdfFormField SetValue(string value, PdfFont font, float fontSize)

Parameters

value string

text value.

font PdfFont

a PdfFont.

fontSize float

the size of the font.

Returns

PdfFormField

the edited field.

UpdateDefaultAppearance()

Updates DA for Variable text, Push button and choice form fields.

public virtual void UpdateDefaultAppearance()

Remarks

Updates DA for Variable text, Push button and choice form fields. The resources required for DA will be put to AcroForm's DR. Note, for other form field types DA will be removed.