public class

Field

extends Object
implements __Delete
java.lang.Object
   ↳ com.pdftron.pdf.Field

Class Overview

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. 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());
   
 }
 
For a full sample, please refer to 'InteractiveForms' sample project. To search field by name use FieldFind method. For example:
 // Search for a specific field
   FieldIterator itr = doc.fieldFind("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.

Summary

Constants
int e_action_trigger_calculate Triggered when field is recalculated due to a change in another field
int e_action_trigger_format Triggered before a field value is displayed.
int e_action_trigger_keystroke Triggered when user modifies text, or selection, in a text, combo or list field
int e_action_trigger_validate Triggered when a field value is changed
int e_button Interactive forms support the following field types: - Button fields represent interactive controls on the screen that the user can manipulate with the mouse.
int e_centered The Constant e_centered.
int e_check The Constant e_check.
int e_choice The Constant e_choice.
int e_comb The Constant e_comb.
int e_combo The Constant e_combo.
int e_commit_on_sel_change The Constant e_commit_on_sel_change.
int e_edit The Constant e_edit.
int e_file_select The Constant e_file_select.
int e_left_justified The Constant e_left_justified.
int e_multiline The Constant e_multiline.
int e_multiselect The Constant e_multiselect.
int e_no_export The Constant e_no_export.
int e_no_scroll The Constant e_no_scroll.
int e_no_spellcheck The Constant e_no_spellcheck.
int e_null The Constant e_null.
int e_password The Constant e_password.
int e_pushbutton_flag The Constant e_pushbutton_flag.
int e_radio The Constant e_radio.
int e_radio_flag The Constant e_radio_flag.
int e_radios_in_unison The Constant e_radios_in_unison.
int e_read_only Flags specifying various characteristics of the fields.
int e_required The Constant e_required.
int e_rich_text The Constant e_rich_text.
int e_right_justified The Constant e_right_justified.
int e_signature The Constant e_signature.
int e_sort The Constant e_sort.
int e_text The Constant e_text.
int e_toggle_to_off The Constant e_toggle_to_off.
Public Constructors
Field(Obj field_dict)
Construct a Field from a SDF dictionary representing a terminal field node.
Public Methods
static Field __Create(long impl, Object ref)
long __GetHandle()
Object __GetRefHandle()
void destroy()
Frees the native memory of the object.
void eraseAppearance()
Removes any appearances associated with the field.
Obj findInheritedAttribute(String attrib)
Some of the Field attributes are designated as inheritable.
void flatten(Page page)
Flatten/Merge existing form field appearances with the page content and remove widget annotation.
GState getDefaultAppearance()
Get the default graphics state that should be used in formatting the text.
Obj getDefaultValue()
Get the default value.
String getDefaultValueAsString()
Get the default value as string.
boolean getFlag(int flag)
Get the value of the given flag.
int getJustification()
Get the quadding (justification).
int getMaxLen()
Get the maximum length

Note: This method is specific to a text field.

String getName()
Get the field name
String getOpt(int opt_idx)
Get name of the option specified by the given index.
int getOptCount()
Get the number of options.
String getPartialName()
Get the partial name.
Obj getSDFObj()
Get the SDFObj.
Obj getTriggerAction(int trigger)
Get the Action associated with the selected Field Trigger event.
int getType()
Get the field type.
Rect getUpdateRect()
Return the rectangle that should be refreshed after changing a field.
Obj getValue()
Get the field value.
boolean getValueAsBool()
Get the value as boolean.
String getValueAsString()
Get the value as string.
boolean isAnnot()
Check if current field is an Annotation
boolean isValid()
Checks if current field is valid.
void refreshAppearance()
Regenerates the appearance stream for the Widget Annotation containing variable text.
void rename(String field_name)
Modify the field name.
void setFlag(int flag, boolean value)
Set the value of given field flag.
void setJustification(int j)
Set the justification to be used in displaying the text field.
void setMaxLen(int max_len)
Set the maximum length of the field's text, in characters.
ViewChangeCollection setValue(Obj value)
Set the value of the Field (i.e.
ViewChangeCollection setValue(String value)
Set the string value.
ViewChangeCollection setValue(boolean is_checked)
Set the boolean value.
Obj useSignatureHandler(long signature_handler_id)
Sets the signature handler to use for adding a signature to this field.
Protected Methods
void clearList()
Clear list.
void finalize()
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.pdftron.pdf.__Delete

Constants

public static final int e_action_trigger_calculate

Triggered when field is recalculated due to a change in another field

Constant Value: 16 (0x00000010)

public static final int e_action_trigger_format

Triggered before a field value is displayed.

Constant Value: 14 (0x0000000e)

public static final int e_action_trigger_keystroke

Triggered when user modifies text, or selection, in a text, combo or list field

Constant Value: 13 (0x0000000d)

public static final int e_action_trigger_validate

Triggered when a field value is changed

Constant Value: 15 (0x0000000f)

public static final int e_button

Interactive forms support the following field types: - Button fields represent interactive controls on the screen that the user can manipulate with the mouse. They include pushbuttons, check-boxes, and radio buttons. - Text fields are boxes or spaces in which the user can enter text from the keyboard. - Choice fields contain several text items, at most one of which may be selected as the field value. They include scrollable list boxes and combo boxes. - Signature fields represent electronic 'signatures' for authenticating the identity of a user and the validity of the document's contents.

Constant Value: 0 (0x00000000)

public static final int e_centered

The Constant e_centered.

Constant Value: 1 (0x00000001)

public static final int e_check

The Constant e_check.

Constant Value: 1 (0x00000001)

public static final int e_choice

The Constant e_choice.

Constant Value: 4 (0x00000004)

public static final int e_comb

The Constant e_comb.

Constant Value: 12 (0x0000000c)

public static final int e_combo

The Constant e_combo.

Constant Value: 14 (0x0000000e)

public static final int e_commit_on_sel_change

The Constant e_commit_on_sel_change.

Constant Value: 18 (0x00000012)

public static final int e_edit

The Constant e_edit.

Constant Value: 15 (0x0000000f)

public static final int e_file_select

The Constant e_file_select.

Constant Value: 9 (0x00000009)

public static final int e_left_justified

The Constant e_left_justified.

Constant Value: 0 (0x00000000)

public static final int e_multiline

The Constant e_multiline.

Constant Value: 7 (0x00000007)

public static final int e_multiselect

The Constant e_multiselect.

Constant Value: 17 (0x00000011)

public static final int e_no_export

The Constant e_no_export.

Constant Value: 2 (0x00000002)

public static final int e_no_scroll

The Constant e_no_scroll.

Constant Value: 11 (0x0000000b)

public static final int e_no_spellcheck

The Constant e_no_spellcheck.

Constant Value: 10 (0x0000000a)

public static final int e_null

The Constant e_null.

Constant Value: 6 (0x00000006)

public static final int e_password

The Constant e_password.

Constant Value: 8 (0x00000008)

public static final int e_pushbutton_flag

The Constant e_pushbutton_flag.

Constant Value: 3 (0x00000003)

public static final int e_radio

The Constant e_radio.

Constant Value: 2 (0x00000002)

public static final int e_radio_flag

The Constant e_radio_flag.

Constant Value: 4 (0x00000004)

public static final int e_radios_in_unison

The Constant e_radios_in_unison.

Constant Value: 6 (0x00000006)

public static final int e_read_only

Flags specifying various characteristics of the fields. Field flags common to all field types: ---------------------------------------------- - If e_read_only flag is set the user may not change the value of the field. Any associated widget annotations will not interact with the user; that is, they will not respond to mouse clicks or change their appearance in response to mouse motions. This flag is useful for fields whose values are computed or imported from a database. - If e_required flag is set, the field must have a value at the time it is exported by a submit-form action. - If e_no_export flag is set, the field must not be exported by a submit-form action. Field flags specific to radio buttons: ---------------------------------------------- - If e_toggle_to_off is clear, exactly one radio button must be selected at all times; clicking the currently selected button has no effect. If set, clicking the selected button deselects it, leaving no button selected. - If e_radios_in_unison is set, a group of radio buttons within a radio button field that use the same value for the on state will turn on and off in unison; that is if one is checked, they are all checked. If clear, the buttons are mutually exclusive (the same behavior as HTML radio buttons). Field flags specific to text fields: ---------------------------------------------- - If e_multiline is set, the field can contain multiple lines of text; if clear, the field's text is restricted to a single line. - If e_password If set, 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. The value is not stored if this flag is set. - If e_file_select is set, the text entered in the field represents the pathname of a file whose contents are to be submitted as the value of the field. - If e_no_spellcheck is set, text entered in the field is not spell-checked. - If e_no_scroll is set, the field does not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than fits within its annotation rectangle. Once the field is full, no further text is accepted. - If e_comb is set, the field is automatically divided into as many equally spaced positions, or combs, as the value of MaxLen, and the text is laid out into those combs. Meaningful only if the MaxLen entry is present in the text field and if the Multiline, Password, and FileSelect flags are clear. - If e_rich_text is set, the value of this field should be represented as a rich text string. If the field has a value, the RV entry of the field dictionary specifies the rich text string. Field flags specific to choice fields: ---------------------------------------------- - If e_combo is set, the field is a combo box; if clear, the field is a list box. - If e_edit is set, the combo box includes an editable text box as well as a dropdown list; if clear, it includes only a drop-down list. This flag is meaningful only if the e_combo flag is set. - If e_sort is set, the field's option items should be sorted alphabetically. This flag is intended for use by form authoring tools, not by PDF viewer applications. Viewers should simply display the options in the order in which they occur in the Opt array. - If e_multiselect is set, more than one of the field's option items may be selected simultaneously; if clear, no more than one item at a time may be selected. - If e_commit_on_sel_change is set, the new value is committed as soon as a selection is made with the pointing device. This option enables applications to perform an action once a selection is made, without requiring the user to exit the field. If clear, the new value is not committed until the user exits the field.

Constant Value: 0 (0x00000000)

public static final int e_required

The Constant e_required.

Constant Value: 1 (0x00000001)

public static final int e_rich_text

The Constant e_rich_text.

Constant Value: 13 (0x0000000d)

public static final int e_right_justified

The Constant e_right_justified.

Constant Value: 2 (0x00000002)

public static final int e_signature

The Constant e_signature.

Constant Value: 5 (0x00000005)

public static final int e_sort

The Constant e_sort.

Constant Value: 16 (0x00000010)

public static final int e_text

The Constant e_text.

Constant Value: 3 (0x00000003)

public static final int e_toggle_to_off

The Constant e_toggle_to_off.

Constant Value: 5 (0x00000005)

Public Constructors

public Field (Obj field_dict)

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

Parameters
field_dict the field_dict

Public Methods

public static Field __Create (long impl, Object ref)

public long __GetHandle ()

public Object __GetRefHandle ()

public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

public void eraseAppearance ()

Removes any appearances associated with the field.

public Obj findInheritedAttribute (String attrib)

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 inheritance tree in search for specified attribute.

Parameters
attrib the attributes to be found
Returns
  • 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)

public void flatten (Page 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.

Note: 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.

Parameters
page the page content

public GState getDefaultAppearance ()

Get the default graphics state that should be used in formatting the text. The state corresponds to /DA entry in the field dictionary.

public Obj getDefaultValue ()

Get the default value.

Returns
  • 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.

public String getDefaultValueAsString ()

Get the default value as string.

Returns
  • the default value as string

public boolean getFlag (int flag)

Get the value of the given flag.

Parameters
flag the given flag
Returns
  • the value of given field flag

public int getJustification ()

Get the quadding (justification).

Returns
  • the form of quadding (justification) to be used in displaying the text fields.

public int getMaxLen ()

Get the maximum length

Note: This method is specific to a text field.

Returns
  • The maximum length of the field's text, in characters, or a negative number if the length is not limited.

public String getName ()

Get the field name

Returns
  • a string representing the fully qualified name of the field (e.g. "employee.name.first").

public String getOpt (int opt_idx)

Get name of the option specified by the given index.

Note: The index must be less than the value returned by GetOptCount().

Returns
  • The string of the option at the givent index.

public int getOptCount ()

Get the number of options.

Returns
  • The total number of options in a list or combo box.

public String getPartialName ()

Get the partial name.

Returns
  • a string representing the partial name of the field (e.g. "first" when "employee.name.first" is fully qualified name).

public Obj getSDFObj ()

Get the SDFObj.

Returns
  • the underlying SDF/Cos object.

public Obj getTriggerAction (int trigger)

Get the Action associated with the selected Field Trigger event.

Parameters
trigger the type of trigger event to get
Returns
  • the Action Obj if present, otherwise NULL

public int getType ()

Get the field type.

Returns
  • The field's value, whose type/format varies depending on the field type. See the descriptions of individual field types for further information.

public Rect getUpdateRect ()

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

public Obj getValue ()

Get the field value.

Returns
  • 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.

public boolean getValueAsBool ()

Get the value as boolean.

Returns
  • the value as boolean

public String getValueAsString ()

Get the value as string.

Returns
  • the value as string

public boolean isAnnot ()

Check if current field is an Annotation

Returns
  • true if this Field is a Widget Annotation Determines whether or not this Field is an Annotation.

public boolean isValid ()

Checks if current field is valid.

Returns
  • 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.

public void 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.

Note: 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.

public void rename (String field_name)

Modify the field name.

Parameters
field_name a string representing the fully qualified name of the field (e.g. "employee.name.first").

public void setFlag (int flag, boolean value)

Set the value of given field flag.

Note: 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.

Parameters
flag the given field flag
value the value of the field flag

public void setJustification (int j)

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

Parameters
j the new justification

public void setMaxLen (int max_len)

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

Note: This method is specific to a text field.

Parameters
max_len the new maximum length

public ViewChangeCollection setValue (Obj value)

Set 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.

Note: in order to remove/erase the existing value use pass a SDF::Null object to SetValue().

Note: 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.

Parameters
value the new value
Returns
  • object containing modified content.

public ViewChangeCollection setValue (String value)

Set the string value.

Parameters
value the new value as String
Returns
  • object containing modified content.

public ViewChangeCollection setValue (boolean is_checked)

Set the boolean value.

Parameters
is_checked the new boolean value
Returns
  • object containing modified content.

public Obj useSignatureHandler (long signature_handler_id)

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.

Parameters
signature_handler_id The unique id of the SignatureHandler to use for adding signature in this field.
Returns
  • The signature dictionary created using the SignatureHandler, or NULL pointer if the signature handler is not found.

Protected Methods

protected void clearList ()

Clear list.

protected void finalize ()

Throws
Throwable