com.snowtide.pdf.forms

Interface AcroFormField

All Superinterfaces:

Bounded, DocumentLocation, FormField

All Known Implementing Classes:

AcroButtonField, AcroCheckboxField, AcroChoiceField, AcroRadioButtonGroupField, AcroSignatureField, AcroTextField

public interface AcroFormField
extends FormField, DocumentLocation

Interface implmented by all form fields held by AcroForm instances.

Version:

©2004-2024 Snowtide

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Object	FIELD_TYPE_BUTTON
static java.lang.Object	FIELD_TYPE_CHOICE
static java.lang.Object	FIELD_TYPE_OTHER
static java.lang.Object	FIELD_TYPE_SIGNATURE
static java.lang.Object	FIELD_TYPE_TEXT

Method Summary

Modifier and Type	Method and Description
boolean	canChangeValue() This function returns true only if this form field is of a subtype that supports setting its value.
java.lang.Object	getDefaultValue() Returns the default value to which the field reverts when a reset-form action is executed, as specified in the /DV entry in this field's PDF dictionary.
java.lang.String	getFullName() Returns the fully-qualified name of this field, which should be unique within a PDF document form.
java.lang.String	getLocalName() Returns the local name of the field, as specified in the /T entry in this field's PDF dictionary.
java.lang.String	getMappingName() Returns the 'mapping name' of this field, as specified in the /TM entry in this field's PDF dictionary.
java.lang.Object	getType() Returns the type of field, as specified in the /FT entry in this field's PDF dictionary.
java.lang.String	getUIName() Returns the user-friendly name of this field, as specified in the /TU entry in this field's PDF dictionary.
java.lang.Object	getValue() Returns the value of this field, as specified in the /V entry in this field's PDF dictionary.
boolean	hasValueChanged() Returns true only if this field's value has been changed since being loaded from the PDF document.
boolean	isReadOnly() Returns true only if this field is designated as read-only.
boolean	setValue(java.lang.String value) Sets the value of this form field.

Methods inherited from interface com.snowtide.pdf.forms.FormField

getName

Methods inherited from interface com.snowtide.pdf.DocumentLocation

pageNumber

Methods inherited from interface com.snowtide.pdf.layout.Bounded

bounds

Field Detail

FIELD_TYPE_BUTTON

static final java.lang.Object FIELD_TYPE_BUTTON

FIELD_TYPE_TEXT

static final java.lang.Object FIELD_TYPE_TEXT

FIELD_TYPE_CHOICE

static final java.lang.Object FIELD_TYPE_CHOICE

FIELD_TYPE_SIGNATURE

static final java.lang.Object FIELD_TYPE_SIGNATURE

FIELD_TYPE_OTHER

static final java.lang.Object FIELD_TYPE_OTHER

Method Detail

getType

java.lang.Object getType()

Returns the type of field, as specified in the /FT entry in this field's PDF dictionary. This is an indication of the subtype of this AcroFormField instance:

• If the return value is FIELD_TYPE_BUTTON, then this AcroFormField is an instance of AcroButtonField
• If the return value is FIELD_TYPE_TEXT, then this AcroFormField is an instance of AcroTextField
• If the return value is FIELD_TYPE_CHOICE, then this AcroFormField is an instance of AcroChoiceField
• If the return value is FIELD_TYPE_SIGNATURE, then this AcroFormField is an instance of AcroSignatureField
• If the return value is FIELD_TYPE_OTHER, then this AcroFormField has no specific concrete implementation. This case is reserved for form fields with new type indicators that may be introduced by Adobe in the future.

getLocalName

java.lang.String getLocalName()

Returns the local name of the field, as specified in the /T entry in this field's PDF dictionary. This name is also used as the value returned by the FormField.getName() implementation.

getFullName

java.lang.String getFullName()

Returns the fully-qualified name of this field, which should be unique within a PDF document form. Details of how full names are constructed are specified in Section 8.6.2 (Field Names) of the PDF Document Specification.

It suffices to say here that form fields in an interactive AcroForm are defined in a hierarchical manner, and that their local names are used to derive a period-delimited full name that guarantees each name's uniqueness within the parent AcroForm.

getUIName

java.lang.String getUIName()

Returns the user-friendly name of this field, as specified in the /TU entry in this field's PDF dictionary. This function can return null if no user-friendly field name is defined.

Specified by:

getUIName in interface FormField

getMappingName

java.lang.String getMappingName()

Returns the 'mapping name' of this field, as specified in the /TM entry in this field's PDF dictionary. The mapping name is used to identify the field in exported form data formats. This function can return null if no mapping name is defined.

getValue

java.lang.Object getValue()

Returns the value of this field, as specified in the /V entry in this field's PDF dictionary. The type of the returned object depends upon the type of this field.

Specified by:

getValue in interface FormField

getDefaultValue

java.lang.Object getDefaultValue()

Returns the default value to which the field reverts when a reset-form action is executed, as specified in the /DV entry in this field's PDF dictionary. The type of the returned object will be the same as the type of object returned by the AcroFormField.getValue() function, and depends upon the type of this field.

hasValueChanged

boolean hasValueChanged()

Returns true only if this field's value has been changed since being loaded from the PDF document.

Since:

v2.1

canChangeValue

boolean canChangeValue()

This function returns true only if this form field is of a subtype that supports setting its value. This includes checkboxes, radio button groups, text fields, and choice fields (lists and dropdown controls).

Since:

v2.1

setValue

boolean setValue(java.lang.String value)

Sets the value of this form field. Each AcroFormField implementation may specify additional varieties of setValue() to support unique functionality (such as holding multiple values). For any form field instance, this function will throw an UnsupportedOperationException if it does not support updates; such instances will return false from AcroFormField.canChangeValue(). This function will return true if the form field's value changes as a result of calling this function (i.e. the given value is different from the current value of the form field).

Either AcroForm.writeUpdatedDocument(java.io.File) or AcroForm.writeUpdatedDocument(java.io.OutputStream) must be called after setting any form field values in order to persist such changes to a PDF document.

Throws:

java.lang.UnsupportedOperationException - if an AcroFormField implementation does not support updates.

java.lang.IllegalArgumentException - if the provided value is invalid for the particular field or field type at hand. Refer to each field type's class javadoc for details on how and when a field value parameter is considered invalid.

Since:

v2.1

isReadOnly

boolean isReadOnly()

Returns true only if this field is designated as read-only. Note that this is just a hint, provided for the benefit of end-user tools. PDFxStream does not enforce the read-only state of a form field; i.e. it will allow a field's value to be set even if it is designated as read-only.

Since:

v2.1