Package com.itextpdf.forms.fields

Class PdfFormField

java.lang.Object
com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>
com.itextpdf.forms.fields.AbstractPdfFormField
com.itextpdf.forms.fields.PdfFormField
Direct Known Subclasses:
PdfButtonFormField, PdfChoiceFormField, PdfSignatureFormField, PdfTextFormField
public class PdfFormField extends AbstractPdfFormField
This class represents a single field or field group in an AcroForm.

To be able to be wrapped with this PdfObjectWrapper the PdfObject must be indirect.

  • Field Details

    • FF_MULTILINE

      public static final int FF_MULTILINE
      Flag that designates, if set, that the field can contain multiple lines of text.

    • FF_PASSWORD

      public static final int FF_PASSWORD
      Flag that designates, if set, that the field's contents must be obfuscated.

    • FF_READ_ONLY

      public static final int FF_READ_ONLY
      The ReadOnly flag, which specifies whether or not the field can be changed.

    • FF_REQUIRED

      public static final int FF_REQUIRED
      The Required flag, which specifies whether or not the field must be filled in.

    • FF_NO_EXPORT

      public static final int FF_NO_EXPORT
      The NoExport flag, which specifies whether or not exporting is forbidden.

    • text

      protected String text

    • img

      protected ImageData img

    • form

      protected PdfFormXObject form

    • checkType

      protected NullableContainer<CheckBoxType> checkType

  • Constructor Details

  • Method Details

    • makeFormField

      public static PdfFormField makeFormField (PdfObject pdfObject, PdfDocument document)
      Creates a (subtype of) PdfFormField object. The type of the object depends on the FT entry in the pdfObject parameter.
      Parameters:
      pdfObject - assumed to be either a PdfDictionary, or a PdfIndirectReference to a PdfDictionary.
      document - the PdfDocument to create the field in.
      Returns:
      a new PdfFormField, or null if pdfObject is not a form field.

    • makeFormFieldOrAnnotation

      public static AbstractPdfFormField makeFormFieldOrAnnotation (PdfObject pdfObject, PdfDocument document)
      Creates a (subtype of) PdfFormField or PdfFormAnnotation object depending on pdfObject.
      Parameters:
      pdfObject - assumed to be either a PdfDictionary, or a PdfIndirectReference to a PdfDictionary.
      document - the PdfDocument to create the field in.
      Returns:
      a new AbstractPdfFormField, or null if pdfObject is not a form field and is not a widget annotation.

    • makeFieldFlag

      public static int makeFieldFlag (int bitPosition)
      Makes a field flag by bit position. Bit positions are numbered 1 to 32. But position 0 corresponds to flag 1, position 3 corresponds to flag 4 etc.
      Parameters:
      bitPosition - bit position of a flag in range 1 to 32 from the pdf specification.
      Returns:
      corresponding field flag.

    • isFormField

      public static boolean isFormField (PdfDictionary dict)
      Checks if dictionary contains any of the form field keys.
      Parameters:
      dict - field dictionary to check.
      Returns:
      true if it is a form field dictionary, false otherwise.

    • getFormFieldKeys

      public static Collection<PdfName> getFormFieldKeys()
      Gets a set of all possible form field keys except PdfName.Parent.
      Returns:
      a set of form field keys.

    • getFormType

      public static PdfName getFormType (PdfDictionary fieldDict)
      Returns the type of the form field dictionary, or of the parent object.
      Parameters:
      fieldDict - field dictionary to get its type.
      Returns:
      the form type, as a PdfName.

    • getFormType

      public PdfName getFormType()
      Returns the type of the parent form field, or of the wrapped object.
      Returns:
      the form type, as a PdfName.

    • setValue

      public PdfFormField setValue (String value)
      Sets a value to the field and generating field appearance if needed.
      Parameters:
      value - of the field.
      Returns:
      the field.

    • setValue

      public PdfFormField setValue (String value, boolean generateAppearance)
      Sets a value to the field (and fields with the same names) and generates field appearance if needed.
      Parameters:
      value - of the field.
      generateAppearance - if false, appearance won't be regenerated.
      Returns:
      the field.

    • setValue

      public PdfFormField setValue (String value, PdfFont font, float fontSize)
      Set text field value with given font and size.
      Parameters:
      value - text value.
      font - a PdfFont.
      fontSize - the size of the font.
      Returns:
      the edited field.

    • setValue

      public PdfFormField setValue (String value, String displayValue)
      Sets the field value and the display string. The display string is used to build the appearance.
      Parameters:
      value - the field value.
      displayValue - the string that is used for the appearance. If null the value parameter will be used.
      Returns:
      the edited field.

    • removeChild

      public void removeChild (AbstractPdfFormField fieldName)
      Removes the childField object of this field.
      Parameters:
      fieldName - a PdfFormField, that needs to be removed from form field children.

    • removeChildren

      public void removeChildren()
      Removes all children from the current field.

    • getKids

      public PdfArray getKids()
      Gets the kids of this object.
      Returns:
      contents of the dictionary's Kids property, as a PdfArray.

    • getChildFields

      public List<AbstractPdfFormField> getChildFields()
      Gets the childFields of this object.
      Returns:
      the children of the current field.

    • getChildFormFields

      public List<PdfFormField> getChildFormFields()
      Gets all child form fields of this form field. Annotations are not returned.
      Returns:
      a list of PdfFormField.

    • getAllChildFormFields

      public List<PdfFormField> getAllChildFormFields()
      Gets all childFields of this object, including the children of the children but not annotations.
      Returns:
      the children of the current field and their children.

    • getAllChildFields

      public List<AbstractPdfFormField> getAllChildFields()
      Gets all childFields of this object, including the children of the children.
      Returns:
      the children of the current field and their children.

    • getChildField

      public PdfFormField getChildField (String fieldName)
      Gets the child field of form field. If there is no child field with such name, null is returned.
      Parameters:
      fieldName - a String, name of the received field.
      Returns:
      the child of the current field as a PdfFormField.

    • addKid

      public PdfFormField addKid (AbstractPdfFormField kid)
      Adds a new kid to the Kids array property from a AbstractPdfFormField. Also sets the kid's Parent property to this object.
      Parameters:
      kid - a new AbstractPdfFormField entry for the field's Kids array property.
      Returns:
      the edited PdfFormField.

    • addKid

      public PdfFormField addKid (AbstractPdfFormField kid, boolean throwExceptionOnError)
      Adds a new kid to the Kids array property from a AbstractPdfFormField. Also sets the kid's Parent property to this object.
      Parameters:
      kid - a new AbstractPdfFormField entry for the field's Kids array property.
      throwExceptionOnError - define whether exception (true) or log (false) is expected in case kid with the same name exists and merge of two kids failed.
      Returns:
      the edited PdfFormField.

    • addKid

      public PdfFormField addKid (PdfWidgetAnnotation kid)
      Adds a new kid to the Kids array property from a PdfWidgetAnnotation. Also sets the kid's Parent property to this object.
      Parameters:
      kid - a new PdfWidgetAnnotation entry for the field's Kids array property.
      Returns:
      the edited PdfFormField.

    • setFieldName

      public PdfFormField setFieldName (String name)
      Changes the name of the field to the specified value.
      Parameters:
      name - the new field name, as a String.
      Returns:
      the edited PdfFormField.

    • getPartialFieldName

      public PdfString getPartialFieldName()
      Gets the current field partial name.
      Returns:
      the current field partial name, as a PdfString. If the field has no partial name, an empty PdfString is returned.

    • setAlternativeName

      public PdfFormField setAlternativeName (String name)
      Changes the alternate name of the field to the specified value. The alternate is a descriptive name to be used by status messages etc.
      Parameters:
      name - the new alternate name, as a String.
      Returns:
      the edited PdfFormField.

    • getAlternativeName

      public PdfString getAlternativeName()
      Gets the current alternate name. The alternate is a descriptive name to be used by status messages etc.
      Returns:
      the current alternate name, as a PdfString.

    • setMappingName

      public PdfFormField setMappingName (String name)
      Changes the mapping name of the field to the specified value. The mapping name can be used when exporting the form data in the document.
      Parameters:
      name - the new alternate name, as a String.
      Returns:
      the edited field.

    • getMappingName

      public PdfString getMappingName()
      Gets the current mapping name. The mapping name can be used when exporting the form data in the document.
      Returns:
      the current mapping name, as a PdfString.

    • getFieldFlag

      public boolean getFieldFlag (int flag)
      Checks whether a certain flag, or any of a combination of flags, is set for this form field.
      Parameters:
      flag - an int interpreted as a series of a binary flags.
      Returns:
      true if any of the flags specified in the parameter is also set in the form field.

    • setFieldFlag

      public PdfFormField setFieldFlag (int flag)
      Adds a flag, or combination of flags, for the form field. This method is intended to be used one flag at a time, but this is not technically enforced. To replace the current value, use setFieldFlags(int).
      Parameters:
      flag - an int interpreted as a series of a binary flags.
      Returns:
      the edited PdfFormField.

    • setFieldFlag

      public PdfFormField setFieldFlag (int flag, boolean value)
      Adds or removes a flag, or combination of flags, for the form field. This method is intended to be used one flag at a time, but this is not technically enforced. To replace the current value, use setFieldFlags(int).
      Parameters:
      flag - an int interpreted as a series of a binary flags.
      value - if true, adds the flag(s). if false, removes the flag(s).
      Returns:
      the edited PdfFormField.

    • isMultiline

      public boolean isMultiline()
      If true, the field can contain multiple lines of text; if false, the field's text is restricted to a single line.
      Returns:
      whether the field can span over multiple lines.

    • isPassword

      public boolean isPassword()
      If true, 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.
      Returns:
      whether or not the contents of the field must be obfuscated.

    • setFieldFlags

      public PdfFormField setFieldFlags (int flags)
      Sets a flag, or combination of flags, for the form field. This method replaces the previous value. Compare with setFieldFlag(int) which adds a flag to the existing flags.
      Parameters:
      flags - an int interpreted as a series of a binary flags.
      Returns:
      the edited PdfFormField.

    • getFieldFlags

      public int getFieldFlags()
      Gets the current list of PDF form field flags.
      Returns:
      the current list of flags, encoded as an int.

    • getValue

      public PdfObject getValue()
      Gets the current value contained in the form field.
      Returns:
      the current value, as a PdfObject.

    • getValueAsString

      public String getValueAsString()
      Gets the current value contained in the form field.
      Returns:
      the current value, as a String.

    • getDisplayValue

      public String getDisplayValue()
      Gets the current display value of the form field.
      Returns:
      the current display value, as a String, if it exists. If not, returns the value as a String.

    • setDefaultValue

      public PdfFormField setDefaultValue (PdfObject value)
      Sets the default fallback value for the form field.
      Parameters:
      value - the default value.
      Returns:
      the edited PdfFormField.

    • getDefaultValue

      public PdfObject getDefaultValue()
      Gets the default fallback value for the form field.
      Returns:
      the default value.

    • setAdditionalAction

      public PdfFormField setAdditionalAction (PdfName key, PdfAction action)
      Sets an additional action for the form field.
      Parameters:
      key - the dictionary key to use for storing the action.
      action - the action.
      Returns:
      the edited PdfFormField.

    • getAdditionalAction

      public PdfDictionary getAdditionalAction()
      Gets the currently additional action dictionary for the form field.
      Returns:
      the additional action dictionary.

    • setOptions

      public PdfFormField setOptions (PdfArray options)
      Sets options for the form field. Only to be used for checkboxes and radio buttons.
      Parameters:
      options - an array of PdfString objects that each represent the 'on' state of one of the choices.
      Returns:
      the edited PdfFormField.

    • getOptions

      public PdfArray getOptions()
      Gets options for the form field. Should only return usable values for checkboxes and radio buttons.
      Returns:
      the options, as an PdfArray of PdfString objects.

    • getWidgets

      public List<PdfWidgetAnnotation> getWidgets()
      Gets all PdfWidgetAnnotation that its children refer to.
      Returns:
      a list of PdfWidgetAnnotation.

    • getChildFormAnnotations

      public List<PdfFormAnnotation> getChildFormAnnotations()
      Gets all child form field's annotations PdfFormAnnotation of this form field.
      Returns:
      a list of PdfFormAnnotation.

    • getFirstFormAnnotation

      public PdfFormAnnotation getFirstFormAnnotation()
      Gets a single child form field's annotation PdfFormAnnotation.
      Returns:
      PdfFormAnnotation or null if there are no child annotations.

    • getDefaultAppearance

      public PdfString getDefaultAppearance()
      Gets default appearance string containing a sequence of valid page-content graphics or text state operators that define such properties as the field's text size and color.
      Specified by:
      getDefaultAppearance in class AbstractPdfFormField
      Returns:
      the default appearance graphics, as a PdfString.

    • updateDefaultAppearance

      public void updateDefaultAppearance()
      Updates DA for Variable text, Push button and choice form fields. The resources required for DA will be put to AcroForm's DR. Note, for other form field types DA will be removed.

    • getJustification

      public TextAlignment getJustification()
      Gets a code specifying the form of quadding (justification) to be used in displaying the text: 0 Left-justified 1 Centered 2 Right-justified
      Returns:
      the current justification attribute.

    • setJustification

      public PdfFormField setJustification (TextAlignment justification)
      Sets a code specifying the form of quadding (justification) to be used in displaying the text: 0 Left-justified 1 Centered 2 Right-justified
      Parameters:
      justification - the value to set the justification attribute to.
      Returns:
      the edited PdfFormField.

    • getDefaultStyle

      public PdfString getDefaultStyle()
      Gets a default style string, as described in "Rich Text Strings" section of Pdf spec.
      Returns:
      the default style, as a PdfString.

    • setDefaultStyle

      public PdfFormField setDefaultStyle (PdfString defaultStyleString)
      Sets a default style string, as described in "Rich Text Strings" section of Pdf spec.
      Parameters:
      defaultStyleString - a new default style for the form field.
      Returns:
      the edited PdfFormField.

    • getRichText

      public PdfObject getRichText()
      Gets a rich text string, as described in "Rich Text Strings" section of Pdf spec. May be either PdfStream or PdfString.
      Returns:
      the current rich text value.

    • setRichText

      public PdfFormField setRichText (PdfObject richText)
      Sets a rich text string, as described in "Rich Text Strings" section of Pdf spec. May be either PdfStream or PdfString.
      Parameters:
      richText - a new rich text value.
      Returns:
      the edited PdfFormField.

    • setCheckType

      public PdfFormField setCheckType (CheckBoxType checkType)
      Changes the type of graphical marker used to mark a checkbox as 'on'. Notice that in order to complete the change one should call regenerateField method.
      Parameters:
      checkType - the new checkbox marker.
      Returns:
      the edited PdfFormField.

    • regenerateField

      public boolean regenerateField()
      This method regenerates appearance stream of the field. Use it if you changed any field parameters and didn't use setValue method which generates appearance by itself.
      Specified by:
      regenerateField in class AbstractPdfFormField
      Returns:
      whether or not the regeneration was successful.

    • setReadOnly

      public PdfFormField setReadOnly (boolean readOnly)
      Sets the ReadOnly flag, specifying whether or not the field can be changed.
      Parameters:
      readOnly - if true, then the field cannot be changed.
      Returns:
      the edited PdfFormField.

    • isReadOnly

      public boolean isReadOnly()
      Gets the ReadOnly flag, specifying whether or not the field can be changed.
      Returns:
      true if the field cannot be changed.

    • setRequired

      public PdfFormField setRequired (boolean required)
      Sets the Required flag, specifying whether or not the field must be filled in.
      Parameters:
      required - if true, then the field must be filled in.
      Returns:
      the edited PdfFormField.

    • isRequired

      public boolean isRequired()
      Gets the Required flag, specifying whether or not the field must be filled in.
      Returns:
      true if the field must be filled in.

    • setNoExport

      public PdfFormField setNoExport (boolean noExport)
      Sets the NoExport flag, specifying whether or not exporting is forbidden.
      Parameters:
      noExport - if true, then exporting is forbidden
      Returns:
      the edited PdfFormField.

    • isNoExport

      public boolean isNoExport()
      Gets the NoExport attribute.
      Returns:
      whether exporting the value following a form action is forbidden.

    • isInReadingMode

      public boolean isInReadingMode()
      Checks if the document that contains the field is created in reading mode.
      Returns:
      true if reading mode is used, false otherwise.

    • getAppearanceStates

      public String[] getAppearanceStates()
      Gets the appearance state names.
      Specified by:
      getAppearanceStates in class AbstractPdfFormField
      Returns:
      an array of Strings containing the names of the appearance states.

    • release

      public void release()
      Releases underlying pdf object and other pdf entities used by wrapper. This method should be called instead of direct call to PdfObject.release() if the wrapper is used.
      Overrides:
      release in class AbstractPdfFormField

    • setColor

      public AbstractPdfFormField setColor (Color color)
      Sets the text color and regenerates appearance stream.
      Overrides:
      setColor in class AbstractPdfFormField
      Parameters:
      color - the new value for the Color.
      Returns:
      the edited AbstractPdfFormField.