public class PDFFormField
extends java.lang.Object
PDFFormField
represents the PDF FormField which compose
the PDF Form.
This class offers mostly get/set method of the form field's entry.
Before call all methods in this package, please note to call
at first.PDFDocument.loadForm()
For a form field associated with signature, this class can support to get the form field properties,
but not support to set the form field properties of a signature.
PDFDocument
Modifier and Type | Class and Description |
---|---|
static class |
PDFFormField.ChoiceOption
Object for list box and combo box option only.
|
static class |
PDFFormField.KeyStrokeEvent
Object indicate the key stroke event.
|
Modifier and Type | Field and Description |
---|---|
static int |
ALIGNMENT_CENTER
Center alignment.
|
static int |
ALIGNMENT_LEFT
Left alignment.
|
static int |
ALIGNMENT_RIGHT
Right alignment.
|
static int |
FLAG_BUTTON_NOTOGGLETOOFF
Not to toggle the radio button off
|
static int |
FLAG_BUTTON_RADIOSINUNISON
Put radio buttons with same value in unison
|
static int |
FLAG_CHOICE_MULTISELECT
If set, more than one items can be selected.
|
static int |
FLAG_COMBO_EDIT
Combo box style.
|
static int |
FLAG_NOEXPORT
The field must not be exported by a submit-form action.
|
static int |
FLAG_READONLY
The field is read only and no editing is allowed.
|
static int |
FLAG_REQUIRED
The field will be exported by a submit-form action.
|
static int |
FLAG_TEXT_COMB
Use combs.
|
static int |
FLAG_TEXT_DONOTSCROLL
Never show scroll bar.
|
static int |
FLAG_TEXT_MULTILINE
Multiple lines.
|
static int |
FLAG_TEXT_PASSWORD
This is a password field.
|
static int |
TRIGGER_FORMFIELD_FC
A JavaScript action to be performed to recalculate the value of this
field when that of another field changes.
|
static int |
TRIGGER_FORMFIELD_KS
A JavaScript action to be performed when the user types a keystroke into
a text field or combo box or modifies the selection in a scrollable list
box.
|
static int |
TRIGGER_FORMFIELD_WF
A JavaScript action to be performed before the field is formatted to
display its current value.
|
static int |
TRIGGER_FORMFIELD_WV
A JavaScript action to be performed when the field's value is changed.
|
static int |
TYPE_CHECKBOX
Check box type.
|
static int |
TYPE_COMBOBOX
Combo box type.
|
static int |
TYPE_LISTBOX
List box type.
|
static int |
TYPE_PUSHBUTTON
Push button type.
|
static int |
TYPE_RADIOBUTTON
Radio button type.
|
static int |
TYPE_TEXTFIELD
Single line or multi-line texts.
|
static int |
TYPE_UNKNOWN
Unknown type.
|
static int |
TYPE_UNSPECIFIED
Unspecified type.
|
Constructor and Description |
---|
PDFFormField(java.lang.String fieldName,
int fieldType)
Construct a
PDFFormField object. |
Modifier and Type | Method and Description |
---|---|
void |
calculate()
Perform the form field javascript to calculate the values of form fields.
|
int |
countActions(int trigger)
Retrieve count of actions associated with a field and a trigger type in a form.
|
int |
countControls(PDFPage page)
Get count of controls which belongs to specified fields.
|
boolean |
format()
Perform the form field javascript to format the values of form fields.
|
PDFAction |
getAction(int trigger,
int index)
Retrieve action associated with a field and a trigger type at a specified
index in a form.
|
int |
getAlignment()
Get alignment type of a field's text.
|
java.lang.String |
getAlternateName()
Get alternate name to be used in place of actual field name.
|
PDFFormControl |
getControl(PDFPage page,
int index)
Get a form control which belongs to the specified fields in the specified page.
|
DefaultAppearance |
getDefaultAppearance()
Get default appearance of specified fields.
|
java.lang.String |
getDefaultValue()
Get default value of a field, not suitable for PushButton fields.
|
int |
getFlags()
Get flags specifying various characteristics of the field.
|
java.lang.String |
getMappingName()
Get mapping name to be used when exporting interactive form field data
from the document.
|
int |
getMaxLen()
Get maximum length of the field's text, by characters.
|
java.lang.String |
getName()
Get field name from form control.
|
PDFFormField.ChoiceOption[] |
getOptions()
Get list box or combo box's options.
|
int |
getTopVisibleIndex()
Get top index for scrollable list boxes.
|
int |
getType()
Get type of a field.
|
java.lang.String |
getValue()
Get value of a field, not suitable for PushButton fields.
|
boolean |
insertAction(int trigger,
int index,
PDFAction action)
Insert an action associated with current field and a trigger type at a
specified index in a form.
|
boolean |
removeAction(int trigger,
int index)
Remove an action associated with current field and a trigger type by index in a form.
|
boolean |
removeAllActions(int trigger)
Remove all actions associated with current field and a trigger type in a form.
|
void |
removeControl(PDFFormControl control)
Remove a form control from current form field.
|
boolean |
setAction(int trigger,
int index,
PDFAction action)
Update an action associated with current field and a trigger type at a
specified index in a form.
|
boolean |
setAlignment(int alignment)
Set alignment property of current field's text, only useful for text field and list box.
|
boolean |
setAlternateName(java.lang.String alternateName)
Set alternate name to be used in place of actual field name.
|
boolean |
setDefaultAppearance(DefaultAppearance appearance)
Set default appearance of current field.
|
boolean |
setDefaultValue(java.lang.String value)
Set default value of a field, except PushButton fields.
|
boolean |
setFlags(int flags)
Set flags specifying various characteristics of the field.
|
boolean |
setMappingName(java.lang.String mappingName)
Set mapping name to be used when exporting interactive form field data
from the document.
|
boolean |
setMaxLen(int maxlen)
Set maximum length of the field's text, in characters.
|
boolean |
setOption(PDFFormField.ChoiceOption[] options)
Set list box or combo box's options.
|
boolean |
setTopVisibleIndex(int index)
Set top index for scrollable list boxes.
|
boolean |
setValue(java.lang.String value)
Set value of a field.
|
boolean |
validateKeyStrokeEvent(PDFFormField.KeyStrokeEvent event)
Perform the form field javascript to validate whether the part of a
field's current value can be replaced by a new value.
|
boolean |
validateValue(java.lang.String value)
Perform the form field javascript to validate whether the user input
value is valid.
|
public static final int TRIGGER_FORMFIELD_KS
This action can check the keystroke for validity and reject or modify it.
public static final int TRIGGER_FORMFIELD_WF
This action can modify the field's value before formatting.
public static final int TRIGGER_FORMFIELD_WV
This action can check the new value for validity.
public static final int TRIGGER_FORMFIELD_FC
public static final int FLAG_READONLY
public static final int FLAG_REQUIRED
public static final int FLAG_NOEXPORT
public static final int TYPE_UNKNOWN
public static final int TYPE_PUSHBUTTON
public static final int TYPE_CHECKBOX
public static final int TYPE_RADIOBUTTON
public static final int TYPE_COMBOBOX
public static final int TYPE_LISTBOX
public static final int TYPE_TEXTFIELD
public static final int TYPE_UNSPECIFIED
public static final int FLAG_BUTTON_NOTOGGLETOOFF
(Radio buttons only) If set, exactly one radio button must be selected at all times; clicking the currently selected button has no effect. If clear, clicking the selected button deselects it, leaving no button selected.
public static final int FLAG_BUTTON_RADIOSINUNISON
If set, radio buttons with same value in a field will be turned on or off in unison (either all one, or all off). If cleared, all buttons are mutually exclusive.
public static final int FLAG_TEXT_MULTILINE
public static final int FLAG_TEXT_PASSWORD
public static final int FLAG_TEXT_DONOTSCROLL
Do not scroll (vertically for multiple-line fields, or horizontally for single-line fields). If the field is full, no further text is accepted.
public static final int FLAG_TEXT_COMB
If set, the field is automatically divided into as many equally spaced positions, or combs, as the value of maximum length of a field's text, and the text is laid out into those combs.
public static final int FLAG_COMBO_EDIT
If set, the combo box includes an editable text control, otherwise, it's only a drop list.
public static final int FLAG_CHOICE_MULTISELECT
public static final int ALIGNMENT_LEFT
public static final int ALIGNMENT_CENTER
public static final int ALIGNMENT_RIGHT
public PDFFormField(java.lang.String fieldName, int fieldType) throws PDFException
PDFFormField
object.
Note: This Constructed PDFFormField
object is not related
with acro form in document until called function
.PDFForm.addField(PDFPage, PDFFormField, RectF)
fieldName
- The name of form field, it should be valid.fieldType
- Which specifies the type of form field. Please refer to
constant definitions PDFFormField.TYPE_XXX
and this should be one of these
constants.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
PDFForm
public java.lang.String getName()
public int countActions(int trigger) throws PDFException
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these constants.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public PDFAction getAction(int trigger, int index) throws PDFException
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these
constants.index
- Which represents the index of the action.PDFAction
object to receives the action associated
a field and a trigger type.null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
PDFAction
public int getAlignment() throws PDFException
PDFFormField.ALIGNMENT_XXX
.
It must be one of them.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public int getFlags() throws PDFException
PDFFormField.FLAG_XXX
and this can be one or a combination of these constants.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public int getType()
PDFFormField#TYPE_XXX
If not found, it will return TYPE_UNKNOWN
.public java.lang.String getDefaultValue() throws PDFException
PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public java.lang.String getValue() throws PDFException
PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public int countControls(PDFPage page) throws PDFException
page
- Which is a PDFPage
object.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
PDFPage
public PDFFormControl getControl(PDFPage page, int index) throws PDFException
page
- Which is a PDFPage
object.index
- The zero-based index in the matched form controls.PDFFormControl
object to receives the form control
handle. If the index don't exist or not found, it will return null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
PDFPage
,
PDFFormControl
public void removeControl(PDFFormControl control) throws PDFException
If the form field has only one control, the field itself will be removed
at the same time, then current PDFFormField
object is not
related with acro form in document any more.
control
- Which is a PDFFormControl
object to be removed.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
PDFFormControl
public DefaultAppearance getDefaultAppearance() throws PDFException
DefaultAppearance
object of the specified fields.null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
,
DefaultAppearance
public java.lang.String getAlternateName() throws PDFException
null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public java.lang.String getMappingName() throws PDFException
null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public int getMaxLen() throws PDFException
PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public PDFFormField.ChoiceOption[] getOptions() throws PDFException
ChoiceOption
objects array.null
.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public int getTopVisibleIndex() throws PDFException
PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public boolean setAction(int trigger, int index, PDFAction action) throws PDFException
This function doesn't support to be used for a signature field.
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these constants.index
- Which represents the index of the action.action
- A PDFAction
object which to be set.true
if set the specified action successfully, else
return false
for the parameter index
is
out of range.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
,
PDFAction
public boolean insertAction(int trigger, int index, PDFAction action) throws PDFException
This function doesn't support to be used for a signature field.
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these constants.index
- Which represents the index of the action. Range: 0 to
(actionCount-1). actionCount
is returned by
function countActions(int)
.action
will be inserted to the last.action
- A PDFAction
object which to be inserted.true
if inserted action successfully, else return
false
for the index
is out of range.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
,
PDFAction
public boolean removeAction(int trigger, int index) throws PDFException
This function doesn't support to be used for a signature field.
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these constants.index
- Which represents the index of the action.true
if removed the specified action successfully,
else return false
for not found the specified action.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean removeAllActions(int trigger) throws PDFException
This function doesn't support to be used for a signature field.
trigger
- Which represents a trigger type. Please refer to constant
definitions TRIGGER_FORMFIELD_XXX
and this should be one of these
constants.true
if removed successfully, else return
false
for not found the action specified by
parameter trigger
.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean validateValue(java.lang.String value) throws PDFException
This function only works correctly while
return true.validateKeyStrokeEvent(KeyStrokeEvent)
value
- Which specify the input value of form field.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public boolean validateKeyStrokeEvent(PDFFormField.KeyStrokeEvent event) throws PDFException
event
- Which specify information of a key stroke event.PDFFormField.KeyStrokeEvent.currentValue
will be the value merged sometimes,PDFFormField.KeyStrokeEvent.currentValue
will be null.PDFException
- When event.start and event.end is out of range or event.start is greater than event.end,
it will throw a exception with PDFException.ERRCODE_PARAM
.
For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public void calculate() throws PDFException
PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public boolean format() throws PDFException
boolean
value indicating whether the value of
form fields is formated.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public boolean setAlignment(int alignment) throws PDFException
Alignment is a property of variable text. It can be set to any kind of form field, but only useful for text field and list box, which may contain variable text as their content.
This function doesn't support to be used for a signature field.
alignment
- The new alignment type of field's variable text. It should be one of the
following:
true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setFlags(int flags) throws PDFException
This function doesn't support to be used for a signature field.
flags
- The flags of the field. Please refer to constant definitions
FLAG_XXX
and this can be
one or a combination of these constants.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setDefaultValue(java.lang.String value) throws PDFException
This function doesn't support to be used for a signature field.
value
- The default value of the field.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setValue(java.lang.String value) throws PDFException
This function doesn't support to be used for a signature field.
value
- The value of the field.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setDefaultAppearance(DefaultAppearance appearance) throws PDFException
This function doesn't support to be used for a signature field, and textMatrix doesn't work when widget annotation has "MK" dictionary.
appearance
- A DefaultAppearance
object of the specified fields.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
,
DefaultAppearance
public boolean setAlternateName(java.lang.String alternateName) throws PDFException
This function doesn't support to be used for a signature field.
alternateName
- The alternate name string.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setMappingName(java.lang.String mappingName) throws PDFException
This function doesn't support to be used for a signature field.
mappingName
- Which specifies the mapping name.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setMaxLen(int maxlen) throws PDFException
This function doesn't support to be used for a signature field.
maxlen
- The maximum length of the field's text to be set.true
if set successfully, else return
false
for any errors.PDFException
- PDFException.ERRCODE_UNSUPPORTED
will be thrown
if current form field represents a signature field.
PDFException.ERRCODE_XXX
.PDFException
public boolean setOption(PDFFormField.ChoiceOption[] options) throws PDFException
options
- A ChoiceOption
objects array.true
if set successfully, else return
false
for any errors.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException
public boolean setTopVisibleIndex(int index) throws PDFException
index
- The index of the first visible item to be set.true
if set successfully, else return
false
for any errors.PDFException
- For more exception information please see definitions
PDFException.ERRCODE_XXX
.PDFException