Class FormText

  • All Implemented Interfaces:
    Cloneable

    public final class FormText
    extends FormElement

    A type of form element representing a Text Field. Text fields may be single or multi-line, or may represent a password or (in Acrobat 5.0) a filename.

    Here's an example showing how to create a new single-line text field in a form.

       Form form = pdf.getForm();
       FormText text = new FormText(pdf.getLastPage(), 100,100,300,120);
       form.addElement("AccountNumber", text);
     

    And here's how to extract the value from an existing text field in a form

       Form form = pdf.getForm();
       FormText text = (FormText)form.getElement("AccountNumber");
       String account = text.getValue();  // May be null
     

    To add validation to a field isn't difficult either - here's how to use two of the built-in JavaScript methods in Adobe Acrobat to limit the keypresses in the field to digits only, and to limit the final value to between 1930 and 1985.

       FormText text = new FormText(pdf.getLastPage(), 100,100,300,120);
       WidgetAnnotation annot = text.getAnnotation(0);
       PDFAction onkey = PDFAction.formJavaScript("AFNumber_Keystroke(0,1,1,0,'',true);");
       PDFAction onchg = PDFAction.formJavaScript("AFRange_Validate(true,1930,true,1985);");
       annot.setAction(Event.KEYPRESS, onkey);
       annot.setAction(Event.CHANGE, onchg);
     
    Since:
    1.1.23
    • Field Detail

      • TYPE_BARCODE

        public static final int TYPE_BARCODE
        Represents the "barcode" type of text field available in XFA. Unlike the other types, new fields cannot be created using this type - this value may only be returned from getType().
        Since:
        2.7.2
        See Also:
        Constant Field Values
    • Constructor Detail

      • FormText

        public FormText​(PDFPage page,
                        float x1,
                        float y1,
                        float x2,
                        float y2)
        Create a new FormText object, and add an annotation at the specified location. Identical to calling:
           FormText text = new FormText();
           text.addAnnotation(page, x1, y1, x2, y2);
         
        Parameters:
        page - the PDFPage to place the annotation on
        x1 - the left-most X co-ordinate of the annotation
        y1 - the bottom-most Y co-ordinate of the annotation
        x2 - the right-most X co-ordinate of the annotation
        y2 - the top-most Y co-ordinate of the annotation
        Since:
        1.1.23
    • Method Detail

      • addAnnotation

        public WidgetAnnotation addAnnotation​(PDFPage page,
                                              float x1,
                                              float y1,
                                              float x2,
                                              float y2)
        Add an annotation for this element at the specified location on the page
        Parameters:
        page - the PDFPage to place the annotation on
        x1 - the left-most X co-ordinate of the annotation
        y1 - the bottom-most Y co-ordinate of the annotation
        x2 - the right-most X co-ordinate of the annotation
        y2 - the top-most Y co-ordinate of the annotation
        Since:
        2.0
      • getType

        public int getType()
        Get the type of field this is, as set by setType(int)
        Since:
        2.0
      • getValue

        public String getValue()
        Get the value of this field if set, or null if not.
        Specified by:
        getValue in class FormElement
      • getDefaultValue

        public String getDefaultValue()
        Return the default value of this field - the value it will reset to if a PDFAction.formReset() occurs.
      • setScrollable

        public void setScrollable​(boolean scrollable)
        Set whether the field can be scrolled (horizontally for single line fields, vertically for multi-line fields) to enter more text than can be displayed in the form. The default value is true.
        Since:
        2.0
        See Also:
        isScrollable()
      • isScrollable

        public boolean isScrollable()
        Get whether this field is scrollable or not - horizontally for for single line text fields, vertically for multi-line
        Since:
        2.0
        See Also:
        setScrollable(boolean)
      • setSpellCheck

        public void setSpellCheck​(boolean spellcheck)
        Set the "spell check" flag on the field, which controls whether Acrobat will run its spell-checker on the field. This flag has no other effect.
        Parameters:
        spellcheck - whether to spell-check the field (true, the default) or not (false)
        Since:
        2.11.14
      • isSpellCheck

        public boolean isSpellCheck()
        Return the value of the "spell check" flag, as set by setSpellCheck(boolean)
        Since:
        2.11.14
      • setNumberOfCombs

        public void setNumberOfCombs​(int numcombs)

        Set the number of "Combs" in this field. A comb can be used when a fixed number of digits are to be entered into the field - the digits will be spaced evenly along the field, so that they appear to be entered into a box. This is an Acrobat 6.0 feature, and although it can be used with documents intended for earlier versions of the viewers, if the text is changed in an earlier viewer the "comb" will be lost.

        A field cannot have a maximum length and a number of combs at the same time, so setting this will also call setMaxLength(0)

        Parameters:
        numcombs - the number of combs in this field.
        Since:
        2.0
      • getNumberOfCombs

        public int getNumberOfCombs()
        Return the number of combs in this field as set by setNumberOfCombs(int), or 0 if the field is not combed
        Since:
        2.0
      • setMaxLength

        public void setMaxLength​(int maxlen)
        Set the maximum length of the field. Passing in a value of zero sets the field to have no maximum length, which is the default. A field cannot have a maximum length and a number of combs at the same time, so setting this will also call setNumberOfCombs(0)
        Parameters:
        maxlen - the maximum number of characters in the field, or zero for no maximum
      • getMaxLength

        public int getMaxLength()
        Return the maximum size of the text field, or zero if there is no maximum
        Returns:
        the maximum length of the text field, or zero for no maximum
      • isRTL

        public boolean isRTL()
        Return true if this text field is marked as right-to-left. This is an undocumented and non-standard flag, but is used by Acrobat to create RTL fields.
        Since:
        2.20.3
      • setRTL

        public void setRTL​(boolean rtl)
        Set the field to be right-to-left. This is an undocumented and non-standard flag, but is used by Acrobat to create RTL fields.
        Since:
        2.20.3
      • rebuild

        public void rebuild()
        Description copied from class: FormElement
        Cause the annotation list to be rebuilt. Unless you're rendering the annotation using the viewer, it's not necessary to call this method.
        Overrides:
        rebuild in class FormElement
      • toString

        public String toString()
      • putLiteral

        public void putLiteral​(String key,
                               String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.