FieldDictionary (ICEpdf API)

java.lang.Object
- org.icepdf.core.pobjects.Dictionary
- - org.icepdf.core.pobjects.acroform.FieldDictionary

Direct Known Subclasses:

SignatureFieldDictionary, VariableTextFieldDictionary
```
public class FieldDictionary
extends Dictionary
```
Each field in a document’s interactive form shall be defined by a field dictionary, which shall be an indirect object. The field dictionaries may be organized hierarchically into one or more tree structures. Many field attributes are inheritable, meaning that if they are not explicitly specified for a given field, their values are taken from those of its parent in the field hierarchy. Such inheritable attributes shall be designated as such in the Tables 220 and 221. The designation (Required; inheritable) means that an attribute shall be defined for every field, whether explicitly in its own field dictionary or by inheritance from an ancestor in the hierarchy. Table 220 shows those entries that are common to all field dictionaries, regardless of type. Entries that pertain only to a particular type of field are described in the relevant sub-clauses in Table 220.

Since:

5.0

Field Summary

Fields
Modifier and Type	Field and Description
`static Name`	`AA_KEY` (Optional; PDF 1.2) An additional-actions dictionary defining the field’s behaviour in response to various trigger events (see 12.6.3, “Trigger Events”).
`protected AdditionalActionsDictionary`	`additionalActionsDictionary`
`protected java.lang.String`	`alternativeFieldName`
`protected java.lang.Object`	`defaultFieldValue`
`static Name`	`DV_KEY` (Optional; inheritable) The default value to which the field reverts when a reset-form action is executed (see 12.7.5.3, “Reset-Form Action”).
`protected java.lang.String`	`exportMappingName`
`static Name`	`Ff_KEY` (Optional; inheritable) A set of flags specifying various characteristics of the field (see Table 221).
`protected Name`	`fieldType`
`protected java.lang.Object`	`fieldValue`
`static Name`	`FT_KEY` Required for terminal fields; inheritable) The type of field that this dictionary describes: Button -> Button (see 12.7.4.2, “Button Fields”) Text -> Text (see 12.7.4.3, “Text Fields”) Choice -> Choice (see 12.7.4.4, “Choice Fields”) Signature(PDF 1.3) -> Signature (see 12.7.4.5, “Signature Fields”) This entry may be present in a non-terminal field (one whose descendants are fields) to provide an inheritable FT value.
`protected java.util.ArrayList<java.lang.Object>`	`kids`
`static Name`	`KIDS_KEY` (Sometimes required, as described below) An array of indirect references to the immediate children of this field.
`static int`	`NO_EXPORT_BIT_FLAG` If set, the field shall not be exported by a submit-form action (see 12.7.5.2, “Submit-Form Action”).
`static Name`	`PARENT_KEY` (Required if this field is the child of another in the field hierarchy; absent otherwise) The field that is the immediate parent of this one (the field, if any, whose Kids array includes this field).
`protected FieldDictionary`	`parentField`
`protected java.lang.String`	`partialFieldName`
`static int`	`READ_ONLY_BIT_FLAG` If set, the user may not change the value of the field.
`static int`	`REQUIRED_BIT_FLAG` If set, the field shall have a value at the time it is exported by a submit-form action (see 12.7.5.2, “Submit-Form Action”).
`static Name`	`T_KEY` (Optional) The partial field name (see 12.7.3.2, “Field Names”).
`static Name`	`TM_KEY` (Optional; PDF 1.3) The mapping name that shall be used when exporting interactive form field data from the document.
`static Name`	`TU_KEY` (Optional; PDF 1.3) An alternate field name that 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).
`static Name`	`V_KEY` (Optional; inheritable) The field’s value, whose format varies depending on the field type.

Fields inherited from class org.icepdf.core.pobjects.Dictionary
entries, FORM_TYPE_KEY, inited, isDeleted, isNew, LENGTH_KEY, library, SUBTYPE_KEY, TYPE_KEY

Constructor Summary

Constructors
Constructor and Description

FieldDictionary(Library library, java.util.HashMap entries)

Constructors
Constructor and Description
`FieldDictionary(Library library, java.util.HashMap entries)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`AdditionalActionsDictionary`	`getAdditionalActionsDictionary()`
`java.lang.String`	`getAlternativeFieldName()`
`java.lang.Object`	`getDefaultFieldValue()`
`java.lang.String`	`getExportMappingName()`
`Name`	`getFieldType()`
`java.lang.Object`	`getFieldValue()`
`int`	`getFlags()`
`java.lang.String`	`getFullyQualifiedFieldName()` The T entry in the field dictionary (see Table 220) holds a text string defining the field’s partial field name.
`java.util.ArrayList<java.lang.Object>`	`getKids()` Gets the kids of of terminal and non terminal fields.
`FieldDictionary`	`getParent()`
`java.lang.String`	`getPartialFieldName()`
`boolean`	`hasDefaultValue()`
`boolean`	`hasFieldValue()`
`boolean`	`isNoExport()` If set, the field shall not be exported by a submit-form action.
`boolean`	`isReadOnly()` If set, the user may not change the value of the field.
`boolean`	`isRequired()` If set, the field shall have a value at the time it is exported by a submit-form action
`void`	`setFieldValue(java.lang.Object fieldValue, Reference parentReference)` Set the value field of the field dictionary (/V).

Methods inherited from class org.icepdf.core.pobjects.Dictionary
getEntries, getFloat, getInt, getLibrary, getNumber, getObject, getPObjectReference, init, isDeleted, isNew, setDeleted, setNew, setPObjectReference, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FT_KEY
```
public static final Name FT_KEY
```
    Required for terminal fields; inheritable) The type of field that this dictionary describes:
    Button -> Button (see 12.7.4.2, “Button Fields”)
    Text -> Text (see 12.7.4.3, “Text Fields”)
    Choice -> Choice (see 12.7.4.4, “Choice Fields”)
    Signature(PDF 1.3) -> Signature (see 12.7.4.5, “Signature Fields”)
    This entry may be present in a non-terminal field (one whose descendants are fields) to provide an inheritable FT value. However, a non-terminal field does not logically have a type of its own; it is merely a container for inheritable attributes that are intended for descendant terminal fields of any type.
  - KIDS_KEY
```
public static final Name KIDS_KEY
```
    (Sometimes required, as described below) An array of indirect references to the immediate children of this field.
    In a non-terminal field, the Kids array shall refer to field dictionaries that are immediate descendants of this field. In a terminal field, the Kids array ordinarily shall refer to one or more separate widget annotations that are associated with this field. However, if there is only one associated widget annotation, and its contents have been merged into the field dictionary, Kids shall be omitted.
  - PARENT_KEY
```
public static final Name PARENT_KEY
```
    (Required if this field is the child of another in the field hierarchy; absent otherwise) The field that is the immediate parent of this one (the field, if any, whose Kids array includes this field). A field can have at most one parent; that is, it can be included in the Kids array of at most one other field.
  - T_KEY
```
public static final Name T_KEY
```
    (Optional) The partial field name (see 12.7.3.2, “Field Names”).
  - TU_KEY
```
public static final Name TU_KEY
```
    (Optional; PDF 1.3) An alternate field name that 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). This text is also useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, “Alternate Descriptions”).
  - TM_KEY
```
public static final Name TM_KEY
```
    (Optional; PDF 1.3) The mapping name that shall be used when exporting interactive form field data from the document.
  - Ff_KEY
```
public static final Name Ff_KEY
```
    (Optional; inheritable) A set of flags specifying various characteristics of the field (see Table 221). Default value: 0.
  - V_KEY
```
public static final Name V_KEY
```
    (Optional; inheritable) The field’s value, whose format varies depending on the field type. See the descriptions of individual field types for further information.
  - DV_KEY
```
public static final Name DV_KEY
```
    (Optional; inheritable) The default value to which the field reverts when a reset-form action is executed (see 12.7.5.3, “Reset-Form Action”). The format of this value is the same as that of V.
  - AA_KEY
```
public static final Name AA_KEY
```
    (Optional; PDF 1.2) An additional-actions dictionary defining the field’s behaviour in response to various trigger events (see 12.6.3, “Trigger Events”). This entry has exactly the same meaning as the AA entry in an annotation dictionary (see 12.5.2, “Annotation Dictionaries”).
  - READ_ONLY_BIT_FLAG
```
public static final int READ_ONLY_BIT_FLAG
```
    If 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.
    
    See Also:
    
    Constant Field Values
  - REQUIRED_BIT_FLAG
```
public static final int REQUIRED_BIT_FLAG
```
    If set, the field shall have a value at the time it is exported by a submit-form action (see 12.7.5.2, “Submit-Form Action”).
    
    See Also:
    
    Constant Field Values
  - NO_EXPORT_BIT_FLAG
```
public static final int NO_EXPORT_BIT_FLAG
```
    If set, the field shall not be exported by a submit-form action (see 12.7.5.2, “Submit-Form Action”).
    
    See Also:
    
    Constant Field Values
  - fieldType
```
protected Name fieldType
```
  - parentField
```
protected FieldDictionary parentField
```
  - kids
```
protected java.util.ArrayList<java.lang.Object> kids
```
  - partialFieldName
```
protected java.lang.String partialFieldName
```
  - alternativeFieldName
```
protected java.lang.String alternativeFieldName
```
  - exportMappingName
```
protected java.lang.String exportMappingName
```
  - fieldValue
```
protected java.lang.Object fieldValue
```
  - defaultFieldValue
```
protected java.lang.Object defaultFieldValue
```
  - additionalActionsDictionary
```
protected AdditionalActionsDictionary additionalActionsDictionary
```
- Constructor Detail
  - FieldDictionary
```
public FieldDictionary(Library library,
                       java.util.HashMap entries)
```
- Method Detail
  - getKids
```
public java.util.ArrayList<java.lang.Object> getKids()
```
    Gets the kids of of terminal and non terminal fields. For non-terminal this can be a mix of field data and widget annotations. And for terminal notes the array will only contain widget annotations.
    
    Returns:
    
    list of child elements.
  - getParent
```
public FieldDictionary getParent()
```
  - getFieldType
```
public Name getFieldType()
```
  - getFlags
```
public int getFlags()
```
  - getPartialFieldName
```
public java.lang.String getPartialFieldName()
```
  - getAlternativeFieldName
```
public java.lang.String getAlternativeFieldName()
```
  - getExportMappingName
```
public java.lang.String getExportMappingName()
```
  - isReadOnly
```
public boolean isReadOnly()
```
    If 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.
    
    Returns:
    
    true if read only, otherwise false.
  - isRequired
```
public boolean isRequired()
```
    If set, the field shall have a value at the time it is exported by a submit-form action
    
    Returns:
    
    true if value is required, otherwise false.
  - isNoExport
```
public boolean isNoExport()
```
    If set, the field shall not be exported by a submit-form action.
    
    Returns:
    
    true if no value should be exported, otherwise false.
  - getFullyQualifiedFieldName
```
public java.lang.String getFullyQualifiedFieldName()
```
    The T entry in the field dictionary (see Table 220) holds a text string defining the field’s partial field name. The fully qualified field name is not explicitly defined but shall be constructed from the partial field names of the field and all of its ancestors.
    This method will climb back up the inheritance tree to build the name.
    
    Returns:
    
    fully quality name of the field.
  - getFieldValue
```
public java.lang.Object getFieldValue()
```
  - hasFieldValue
```
public boolean hasFieldValue()
```
  - hasDefaultValue
```
public boolean hasDefaultValue()
```
  - setFieldValue
```
public void setFieldValue(java.lang.Object fieldValue,
                          Reference parentReference)
```
    Set the value field of the field dictionary (/V). The value can be anything but special attention is given to Strings especially if the document is already encrypted. We need to stored String in an Encrypted environment as encrypted so that we can write it correctly later.
    
    Parameters:
    
    fieldValue - value to write.
    
    parentReference - parent reference.
  - getDefaultFieldValue
```
public java.lang.Object getDefaultFieldValue()
```
  - getAdditionalActionsDictionary
```
public AdditionalActionsDictionary getAdditionalActionsDictionary()
```

Class FieldDictionary

Field Summary

Fields inherited from class org.icepdf.core.pobjects.Dictionary

Constructor Summary

Method Summary

Methods inherited from class org.icepdf.core.pobjects.Dictionary

Methods inherited from class java.lang.Object

Field Detail

FT_KEY

KIDS_KEY

PARENT_KEY

T_KEY

TU_KEY

TM_KEY

Ff_KEY

V_KEY

DV_KEY

AA_KEY

READ_ONLY_BIT_FLAG

REQUIRED_BIT_FLAG

NO_EXPORT_BIT_FLAG

fieldType

parentField

kids

partialFieldName

alternativeFieldName

exportMappingName

fieldValue

defaultFieldValue

additionalActionsDictionary

Constructor Detail

FieldDictionary

Method Detail

getKids

getParent

getFieldType

getFlags

getPartialFieldName

getAlternativeFieldName

getExportMappingName

isReadOnly

isRequired

isNoExport

getFullyQualifiedFieldName

getFieldValue

hasFieldValue

hasDefaultValue

setFieldValue

getDefaultFieldValue

getAdditionalActionsDictionary