Class PDField
- java.lang.Object
-
- org.apache.pdfbox.pdmodel.interactive.form.PDField
-
- All Implemented Interfaces:
COSObjectable
- Direct Known Subclasses:
PDNonTerminalField
,PDTerminalField
public abstract class PDField extends java.lang.Object implements COSObjectable
A field in an interactive form.
-
-
Field Summary
Fields Modifier and Type Field Description private PDAcroForm
acroForm
private COSDictionary
dictionary
private static int
FLAG_NO_EXPORT
private static int
FLAG_READ_ONLY
private static int
FLAG_REQUIRED
private PDNonTerminalField
parent
-
Constructor Summary
Constructors Constructor Description PDField(PDAcroForm acroForm)
Constructor.PDField(PDAcroForm acroForm, COSDictionary field, PDNonTerminalField parent)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description (package private) abstract FDFField
exportFDF()
Exports this field and its children as FDF.(package private) PDField
findKid(java.lang.String[] name, int nameIndex)
This will find one of the child elements.(package private) static PDField
fromDictionary(PDAcroForm form, COSDictionary field, PDNonTerminalField parent)
Creates a COSField subclass from the given COS field.PDAcroForm
getAcroForm()
This will get the acroform that this field is part of.PDFormFieldAdditionalActions
getActions()
Get the additional actions for this field.java.lang.String
getAlternateFieldName()
Gets the alternate name of the field ("shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field)").COSDictionary
getCOSObject()
This will get the dictionary associated with this field.abstract int
getFieldFlags()
This will get the flags for this field.abstract java.lang.String
getFieldType()
Get the FT entry of the field.java.lang.String
getFullyQualifiedName()
Returns the fully qualified name of the field, which is a concatenation of the names of all the parents fields.protected COSBase
getInheritableAttribute(COSName key)
Returns the given attribute, inheriting from parent nodes if necessary.java.lang.String
getMappingName()
Gets the mapping name of the field.PDNonTerminalField
getParent()
Get the parent field to this field, or null if none exists.java.lang.String
getPartialName()
Returns the partial name of the field.abstract java.lang.String
getValueAsString()
Returns a string representation of the "V" entry, or an empty string.abstract java.util.List<PDAnnotationWidget>
getWidgets()
Returns the widget annotations associated with this field.(package private) void
importFDF(FDFField fdfField)
This will import a fdf field from a fdf document.boolean
isNoExport()
boolean
isReadOnly()
boolean
isRequired()
void
setAlternateFieldName(java.lang.String alternateFieldName)
This will set the alternate name of the field ("shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field)").void
setFieldFlags(int flags)
This will set the flags for this field.void
setMappingName(java.lang.String mappingName)
This will set the mapping name of the field.void
setNoExport(boolean noExport)
sets the field to be not exported.void
setPartialName(java.lang.String name)
This will set the partial name of the field.void
setReadOnly(boolean readonly)
sets the field to be read-only.void
setRequired(boolean required)
sets the flag whether the field is to be required to have a value at the time it is exported by a submit-form action.abstract void
setValue(java.lang.String value)
Sets the value of the field.java.lang.String
toString()
-
-
-
Field Detail
-
FLAG_READ_ONLY
private static final int FLAG_READ_ONLY
- See Also:
- Constant Field Values
-
FLAG_REQUIRED
private static final int FLAG_REQUIRED
- See Also:
- Constant Field Values
-
FLAG_NO_EXPORT
private static final int FLAG_NO_EXPORT
- See Also:
- Constant Field Values
-
acroForm
private final PDAcroForm acroForm
-
parent
private final PDNonTerminalField parent
-
dictionary
private final COSDictionary dictionary
-
-
Constructor Detail
-
PDField
PDField(PDAcroForm acroForm)
Constructor.- Parameters:
acroForm
- The form that this field is part of.
-
PDField
PDField(PDAcroForm acroForm, COSDictionary field, PDNonTerminalField parent)
Constructor.- Parameters:
acroForm
- The form that this field is part of.field
- the PDF object to represent as a field.parent
- the parent node of the node
-
-
Method Detail
-
fromDictionary
static PDField fromDictionary(PDAcroForm form, COSDictionary field, PDNonTerminalField parent)
Creates a COSField subclass from the given COS field. This is for reading fields from PDFs.- Parameters:
form
- the form that the field is part offield
- the dictionary representing a field elementparent
- the parent node of the node to be created, or null if root.- Returns:
- a new PDField instance
-
getInheritableAttribute
protected COSBase getInheritableAttribute(COSName key)
Returns the given attribute, inheriting from parent nodes if necessary.- Parameters:
key
- the key to look up- Returns:
- COS value for the given key
-
getFieldType
public abstract java.lang.String getFieldType()
Get the FT entry of the field. This is a read only field and is set depending on the actual type. The field type is an inheritable attribute.- Returns:
- The Field type.
-
getValueAsString
public abstract java.lang.String getValueAsString()
Returns a string representation of the "V" entry, or an empty string.- Returns:
- The list of widget annotations.
-
setValue
public abstract void setValue(java.lang.String value) throws java.io.IOException
Sets the value of the field.- Parameters:
value
- the new field value.- Throws:
java.io.IOException
- if the value could not be set
-
getWidgets
public abstract java.util.List<PDAnnotationWidget> getWidgets()
Returns the widget annotations associated with this field. ForPDNonTerminalField
the list will be empty as non terminal fields have no visual representation in the form.- Returns:
- a List of
PDAnnotationWidget
annotations. Be aware that this list is not backed by the actual widget collection of the field, so adding or deleting has no effect on the PDF document. ForPDTerminalField
you'd have to callsetWidgets()
with the modified list.
-
setReadOnly
public void setReadOnly(boolean readonly)
sets the field to be read-only.- Parameters:
readonly
- The new flag for readonly.
-
isReadOnly
public boolean isReadOnly()
- Returns:
- true if the field is readonly
-
setRequired
public void setRequired(boolean required)
sets the flag whether the field is to be required to have a value at the time it is exported by a submit-form action.- Parameters:
required
- The new flag for required.
-
isRequired
public boolean isRequired()
- Returns:
- true if the field is required to have a value at the time it is exported by a submit-form action.
-
setNoExport
public void setNoExport(boolean noExport)
sets the field to be not exported.- Parameters:
noExport
- The new flag for noExport.
-
isNoExport
public boolean isNoExport()
- Returns:
- true if the field is not to be exported.
-
getFieldFlags
public abstract int getFieldFlags()
This will get the flags for this field.- Returns:
- flags The set of flags.
-
setFieldFlags
public void setFieldFlags(int flags)
This will set the flags for this field.- Parameters:
flags
- The new flags.
-
getActions
public PDFormFieldAdditionalActions getActions()
Get the additional actions for this field. This will return null if there are no additional actions for this field.- Returns:
- The actions of the field.
-
importFDF
void importFDF(FDFField fdfField) throws java.io.IOException
This will import a fdf field from a fdf document.- Parameters:
fdfField
- The fdf field to import.- Throws:
java.io.IOException
- If there is an error importing the data for this field.
-
exportFDF
abstract FDFField exportFDF() throws java.io.IOException
Exports this field and its children as FDF.- Throws:
java.io.IOException
-
getParent
public PDNonTerminalField getParent()
Get the parent field to this field, or null if none exists.- Returns:
- The parent field.
-
findKid
PDField findKid(java.lang.String[] name, int nameIndex)
This will find one of the child elements. The name array are the components of the name to search down the tree of names. The nameIndex is where to start in that array. This method is called recursively until it finds the end point based on the name array.- Parameters:
name
- An array that picks the path to the field.nameIndex
- The index into the array.- Returns:
- The field at the endpoint or null if none is found.
-
getAcroForm
public PDAcroForm getAcroForm()
This will get the acroform that this field is part of.- Returns:
- The form this field is on.
-
getCOSObject
public COSDictionary getCOSObject()
This will get the dictionary associated with this field.- Specified by:
getCOSObject
in interfaceCOSObjectable
- Returns:
- the dictionary that this class wraps.
-
getPartialName
public java.lang.String getPartialName()
Returns the partial name of the field.- Returns:
- the name of the field
-
setPartialName
public void setPartialName(java.lang.String name)
This will set the partial name of the field.- Parameters:
name
- The new name for the field.- Throws:
java.lang.IllegalArgumentException
- If the name contains a period character.
-
getFullyQualifiedName
public java.lang.String getFullyQualifiedName()
Returns the fully qualified name of the field, which is a concatenation of the names of all the parents fields.- Returns:
- the name of the field
-
getAlternateFieldName
public java.lang.String getAlternateFieldName()
Gets the alternate name of the field ("shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field)").- Returns:
- the alternate name of the field
-
setAlternateFieldName
public void setAlternateFieldName(java.lang.String alternateFieldName)
This will set the alternate name of the field ("shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field)"). The text appears as a tool tip in Adobe Reader. Because of the usage for error or status messages, it should be different for each field.- Parameters:
alternateFieldName
- the alternate name of the field.
-
getMappingName
public java.lang.String getMappingName()
Gets the mapping name of the field. The mapping name shall be used when exporting interactive form field data from the document.- Returns:
- the mapping name of the field
-
setMappingName
public void setMappingName(java.lang.String mappingName)
This will set the mapping name of the field.- Parameters:
mappingName
- the mapping name of the field
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-