Package com.itextpdf.forms.fields

Class PdfFormField

    • Field Detail

      • 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.

      • FORM_FIELD_KEYS

        private static final java.util.Set<PdfName> FORM_FIELD_KEYS
        List of all allowable keys in form fields.

      • LOGGER

        private static final org.slf4j.Logger LOGGER

      • text

        protected java.lang.String text

      • displayValue

        private java.lang.String displayValue

    • Method Detail

      • createKids

        private void createKids​(PdfDictionary pdfObject)

      • 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 java.util.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 <PdfDictionary> object.
        Parameters:
        fieldDict - field dictionary to get its type.
        Returns:
        the form type, as a PdfName.

      • getStringValue

        public static java.lang.String getStringValue​(PdfObject value)
        Retrieves string value from PdfObject representing text string or text stream.
        Parameters:
        value - PdfObject representing text string or text stream
        Returns:
        String value

      • applyAccessibilityProperties

        public static void applyAccessibilityProperties​(PdfFormField formField,
                                                IAccessibleElement modelElement,
                                                PdfDocument pdfDocument)
        Applies AccessibilityProperties for provided form field and its annotation children.
        Parameters:
        formField - PdfFormField the form field to which the accessibility properties should be applied
        modelElement - IAccessibleElement the form field layout element with accessibility properties
        pdfDocument - PdfDocument the document to which the form field belongs

      • getFormType

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

      • setValue

        public PdfFormField setValue​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String value,
                             java.lang.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 java.util.List<AbstractPdfFormField> getChildFields()
        Gets the childFields of this object.
        Returns:
        the children of the current field.

      • getChildFormFields

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

      • getAllChildFormFields

        public java.util.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 java.util.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​(java.lang.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,
                           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.

      • setFieldName

        public PdfFormField setFieldName​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.String getValueAsString()
        Gets the current value contained in the form field.
        Returns:
        the current value, as a String.

      • getDisplayValue

        public java.lang.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.

      • 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. It 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 java.lang.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

      • optionsArrayToString

        static java.lang.String optionsArrayToString​(PdfArray options)

      • setChildField

        AbstractPdfFormField setChildField​(AbstractPdfFormField kid)
        Adds a field to the children of the current field.
        Parameters:
        kid - the field, which should become a child.
        Returns:
        the kid itself.

      • replaceKids

        void replaceKids​(java.util.Collection<AbstractPdfFormField> kids)
        Replaces /Kids value with passed kids dictionaries, and keeps old flashed fields there. Also updates childFields array for PdfFormField.
        Parameters:
        kids - collection of new kids.

      • generateDefaultAppearance

        private static PdfString generateDefaultAppearance​(PdfName font,
                                                   float fontSize,
                                                   Color textColor)

      • numberToHorizontalAlignment

        private static TextAlignment numberToHorizontalAlignment​(int alignment)

      • setFieldValue

        private PdfFormField setFieldValue​(java.lang.String value,
                                   boolean generateAppearance)

      • tryGenerateCheckboxAppearance

        private boolean tryGenerateCheckboxAppearance​(java.lang.String value)
        Distinguish mutually exclusive and regular checkboxes: check all the on states of the widgets, if they are not all equal, then consider that this checkbox is mutually exclusive and do nothing, otherwise regenerate normal appearance with value as on appearance state for all the widgets.
        Parameters:
        value - not empty value different from "Off".

      • mergeKidsIfKidWithSuchNameExists

        private boolean mergeKidsIfKidWithSuchNameExists​(AbstractPdfFormField newKid,
                                                 boolean throwExceptionOnError)

      • hasDefaultAppearance

        private boolean hasDefaultAppearance()

      • addAcroFormToCatalog

        private void addAcroFormToCatalog()