Show / Hide Table of Contents

# Class Field

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of Fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

PDFNet fully supports reading, writing, and editing PDF forms and provides many utility methods so that work with forms is simple and efficient. Using PDFNet forms API arbitrary subsets of form fields can be imported or exported from the document, new forms can be created from scratch, and the appearance of existing forms can be modified.

In PDFNet Fields are accessed through FieldIterator-s. For a full sample, please refer to 'InteractiveForms' sample project. The list of all Fields present in the document can be traversed as follows:

    for(FieldIterator itr = doc.getFieldIterator(); itr.hasNext();) {
    Field current=(Field)(itr.next());
    System.out.println("Field name: " + current.getName());
    System.out.println("Field partial name: " + current.getPartialName());
    }

To search field by name use GetFieldIterator method. For example:

    // Search for a specific field
    FieldIterator itr = doc.GetFieldIterator("employee.name.first");
    if (itr.hasNext()) System.out.println("Field search for " + ((Field)(itr.next())).getName() + " was successful");
    else System.out.println("Field search failed");

If a given field name was not found or if the end of the field list was reached the iterator `HasNext()` will return false.

If you have a valid iterator you can access the Field using `Current()` method. For example:

    Field field = itr.Current();

Using `Flatten(...)` method it is possible to merge field appearances with the page content. Form 'flattening' refers to the operation that changes active form fields into a static area that is
part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

##### Inheritance

object
Field

##### Implements

IDisposable

##### Inherited Members

object.Equals(object)
object.Equals(object, object)
object.GetHashCode()
object.MemberwiseClone()
object.ReferenceEquals(object, object)
object.ToString()

###### Namespace: pdftron.PDF

###### Assembly: PDFTronDotNet.dll

##### Syntax

    public class Field : IDisposable

### Constructors

#### Field(Obj)

Construct a Field from a SDF dictionary representing a terminal field node.

##### Declaration

    public Field(Obj field_dict)

##### Parameters

Type | Name | Description
--- | --- | ---
Obj | field_dict | the field_dict

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

### Methods

#### Destroy()

##### Declaration

    public void Destroy()

#### Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

##### Declaration

    public void Dispose()

#### Dispose(bool)

##### Declaration

    protected virtual void Dispose(bool disposing)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | disposing |

#### EraseAppearance()

Removes any appearances associated with the field.

##### Declaration

    public void EraseAppearance()

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### ~Field()

Releases all resources used by the Field

##### Declaration

    protected ~Field()

#### FindInheritedAttribute(string)

Some of the Field attributes are designated as inheritable. If such an attribute is omitted from a Field object, its value is inherited from an ancestor node in the Field tree. If the attribute is a required one, a value must be supplied in an ancestor node; if it is optional and no inherited value is specified, the default value should be used.

The function walks up the Field inhritance tree in search for specified attribute.

##### Declaration

    public Obj FindInheritedAttribute(string attrib)

##### Parameters

Type | Name | Description
--- | --- | ---
string | attrib | the attrib

##### Returns

Type | Description
--- | ---
Obj | The attribute value if the given attribute name was found or a NULL object if the given attribute name was not found. Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Flatten(Page)

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form 'flattening' refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

##### Declaration

    public void Flatten(Page page)

##### Parameters

Type | Name | Description
--- | --- | ---
Page | page | the page

##### Remarks

an alternative approach to set the field as read only is using `Field.SetFlag(Field::e_read_only, true)` method. Unlike `Field.SetFlag(...)`, the result of `Flatten()` operation can not be programatically reversed.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetDefaultAppearance()

Gets the default graphics state.

##### Declaration

    public GState GetDefaultAppearance()

##### Returns

Type | Description
--- | ---
GState | The default graphics state that should be used in formatting the text. The state corresponds to /DA entry in the field dictionary.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetDefaultValue()

Gets the default value.

##### Declaration

    public Obj GetDefaultValue()

##### Returns

Type | Description
--- | ---
Obj | The default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified. The format of field's value varies depending on the field type.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetDefaultValueAsString()

Gets the default value as string.

##### Declaration

    public string GetDefaultValueAsString()

##### Returns

Type | Description
--- | ---
string | the default value as string

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetFlag(Flag)

Gets the flag.

##### Declaration

    public bool GetFlag(Field.Flag flag)

##### Parameters

Type | Name | Description
--- | --- | ---
Field.Flag | flag | the flag

##### Returns

Type | Description
--- | ---
bool | the value of given field flag

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetJustification()

Gets the justification.

##### Declaration

    public Field.TextJustification GetJustification()

##### Returns

Type | Description
--- | ---
Field.TextJustification | the form of quadding (justification) to be used in displaying the text fields.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetMaxLen()

Gets the maximum length.

##### Declaration

    public int GetMaxLen()

##### Returns

Type | Description
--- | ---
int | The maximum length of the field's text, in characters, or a negative number if the length is not limited.

##### Remarks

This method is specific to a text field.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetName()

Gets the name.

##### Declaration

    public string GetName()

##### Returns

Type | Description
--- | ---
string | a string representing the fully qualified name of the field (e.g. "employee.name.first").

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetOpt(int)

##### Declaration

    public string GetOpt(int index)

##### Parameters

Type | Name | Description
--- | --- | ---
int | index |

##### Returns

Type | Description
--- | ---
string |

#### GetOptCount()

##### Declaration

    public int GetOptCount()

##### Returns

Type | Description
--- | ---
int |

#### GetPartialName()

Gets the partial name.

##### Declaration

    public string GetPartialName()

##### Returns

Type | Description
--- | ---
string | a string representing the partial name of the field (e.g. "first" when "employee.name.first" is fully qualified name).

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetSDFObj()

Gets the SDFObj.

##### Declaration

    public Obj GetSDFObj()

##### Returns

Type | Description
--- | ---
Obj | the underlying SDF/Cos object.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetTriggerAction(EventType)

Get the Action associated with the selected Field Trigger event

##### Declaration

    public Obj GetTriggerAction(Field.EventType trigger)

##### Parameters

Type | Name | Description
--- | --- | ---
Field.EventType | trigger | the type of trigger event to get

##### Returns

Type | Description
--- | ---
Obj | The action Obj if present, otherwise NULL

#### GetType()

Gets the type.

##### Declaration

    public Field.Type GetType()

##### Returns

Type | Description
--- | ---
Field.Type | The field's value, whose type/format varies depending on the field type. See the descriptions of individual field types for further information.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetUpdateRect()

Return the rectangle that should be refreshed after changing a field.

##### Declaration

    public Rect GetUpdateRect()

##### Returns

Type | Description
--- | ---
Rect |

#### GetValue()

Gets the value.

##### Declaration

    public Obj GetValue()

##### Returns

Type | Description
--- | ---
Obj | the value of the Field (the value of its /V key) or NULL if the value is not specified. The format of field's value varies depending on the field type.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetValueAsBool()

Gets the value as bool.

##### Declaration

    public bool GetValueAsBool()

##### Returns

Type | Description
--- | ---
bool | the value as bool

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### GetValueAsString()

Gets the value as string.

##### Declaration

    public string GetValueAsString()

##### Returns

Type | Description
--- | ---
string | the value as string

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### IsAnnot()

Checks if is annot.

##### Declaration

    public bool IsAnnot()

##### Returns

Type | Description
--- | ---
bool | true if this Field is a Widget Annotation Determines whether or not this Field is an Annotation.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### IsLockedByDigitalSignature()

Returns whether modifying this field would invalidate a digital signature in the document

##### Declaration

    public bool IsLockedByDigitalSignature()

##### Returns

Type | Description
--- | ---
bool | whether modifying this field would invalidate a digital signature in the document

#### IsValid()

Checks if current field is valid.

##### Declaration

    public bool IsValid()

##### Returns

Type | Description
--- | ---
bool | whether this is a valid (non-null) Field. If the function returns false the underlying SDF/Cos object is null and the Field object should be treated as null as well.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### RefreshAppearance()

Regenerates the appearance stream for the Widget Annotation containing variable text. Call this method if you modified field's value and would like to update field's appearance.

##### Declaration

    public void RefreshAppearance()

##### Remarks

If this field contains text, and has been added to a rotated page, the text in the field may be rotated. If RefreshAppearance is called after the field is added to a rotated page, then any text will be rotated in the opposite direction of the page rotation. If this method is called before the field is added to any rotated page, then no counter rotation will be applied. If you wish to call RefreshAppearance on a field already added to a rotated page, but you don't want the text to be rotated, you can do one of the following; temporarily un-rotate the page, or, temporarily remove the "P" object from the field.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Rename(string)

Modifies the field name.

##### Declaration

    public void Rename(string field_name)

##### Parameters

Type | Name | Description
--- | --- | ---
string | field_name | a string representing the fully qualified name of the field (e.g. "employee.name.first").

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Set(Field)

Sets to given `Field` object

##### Declaration

    public void Set(Field p)

##### Parameters

Type | Name | Description
--- | --- | ---
Field | p | a `Field` object

#### SetFlag(Flag, bool)

Set the value of given FieldFlag.

##### Declaration

    public void SetFlag(Field.Flag flag, bool value)

##### Parameters

Type | Name | Description
--- | --- | ---
Field.Flag | flag | the flag
bool | value | the value

##### Remarks

You can use this method to set the field as read-only. An alternative approach to set the field as read only is using `Page.Flatten(...)` method. Unlike `Flatten(...)`, the result of `SetFlag(...)` can be programatically reversed.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### SetJustification(TextJustification)

Sets the justification to be used in displaying the text field.

##### Declaration

    public void SetJustification(Field.TextJustification j)

##### Parameters

Type | Name | Description
--- | --- | ---
Field.TextJustification | j | the new justification

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### SetMaxLen(int)

Sets the maximum length of the field's text, in characters.

##### Declaration

    public void SetMaxLen(int max_len)

##### Parameters

Type | Name | Description
--- | --- | ---
int | max_len | the new maximum length

##### Remarks

This method is specific to a text field.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### SetValue(bool)

Sets the value.

##### Declaration

    public ViewChangeCollection SetValue(bool is_checked)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | is_checked | the new value

##### Returns

Type | Description
--- | ---
ViewChangeCollection |

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### SetValue(string)

Sets the value.

##### Declaration

    public ViewChangeCollection SetValue(string value)

##### Parameters

Type | Name | Description
--- | --- | ---
string | value | the new value

##### Returns

Type | Description
--- | ---
ViewChangeCollection |

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### SetValue(Obj)

Sets the value of the Field (i.e. the value of the field's /V key). The format of field's value varies depending on the field type.

##### Declaration

    public ViewChangeCollection SetValue(Obj value)

##### Parameters

Type | Name | Description
--- | --- | ---
Obj | value | the new value

##### Returns

Type | Description
--- | ---
ViewChangeCollection |

##### Remarks

in order to remove/erase the existing value use pass a `SDF::Null` object to `SetValue()`. In PDF, Field's value is separate from its annotation (i.e. how the field appears on the page). After you modify Field's value you need to refresh Field's appearance using RefreshAppearance() method.

Alternatively, you can delete "AP" entry from the Widget annotation and set "NeedAppearances" flag in AcroForm dictionary (i.e. doc.GetAcroForm().Put("NeedAppearances", Obj.CreateBool(true)); ) This will force viewer application to auto-generate new field appearances every time the document is opened.

Yet another option is to generate a custom annotation appearance using ElementBuilder and ElementWriter and then set the "AP" entry in the widget dictionary to the new appearance stream. This functionality is useful in applications that need advanced control over how the form fields are rendered.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### UseSignatureHandler(SignatureHandlerId)

Sets the signature handler to use for adding a signature to this field. If the signature handler is not found in PDFDoc's signature handlers list, this field will not be signed. To add signature handlers, use PDFDoc.AddSignatureHandler method. If a signature handler is already assigned to this field and this method is called once again, the associate signature handler for this field will be updated with the new handler.

##### Declaration

    public Obj UseSignatureHandler(SignatureHandlerId signature_handler_id)

##### Parameters

Type | Name | Description
--- | --- | ---
SignatureHandlerId | signature_handler_id | The unique id of the SignatureHandler to use for adding signature in this field.

##### Returns

Type | Description
--- | ---
Obj | The signature dictionary created using the SignatureHandler, or null if the signature handler is not found.

#### op_Assign(Field)

Assignment operator

##### Declaration

    public Field op_Assign(Field r)

##### Parameters

Type | Name | Description
--- | --- | ---
Field | r | a `Field` object

##### Returns

Type | Description
--- | ---
Field | a `Field` object equals to given object

### Implements

IDisposable