org.faceless.pdf2

## Class FormText

- java.lang.Object
- - org.faceless.pdf2.FormElement
  - - org.faceless.pdf2.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 Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TYPE_BARCODE` Represents the "barcode" type of text field available in XFA.
    `static int` | `TYPE_FILESELECT` Parameter to `setType(int)` to create a text box for selecting a file
    `static int` | `TYPE_MULTILINE` Parameter to `setType(int)` to create a multiline text box
    `static int` | `TYPE_NORMAL` Parameter to `setType(int)` to create a normal text box
    `static int` | `TYPE_PASSWORD` Parameter to `setType(int)` to create a text box for entering password

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FormText()` Create a new FormText object.
    `FormText(PDFPage page, float x1, float y1, float x2, float y2)` Create a new FormText object, and add an annotation at the specified location.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `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
    `String` | `getDefaultValue()` Return the default value of this field - the value it will reset to if a `PDFAction.formReset()` occurs.
    `int` | `getMaxLength()` Return the maximum size of the text field, or zero if there is no maximum
    `int` | `getNumberOfCombs()` Return the number of combs in this field as set by `setNumberOfCombs(int)`, or 0 if the field is not combed
    `int` | `getType()` Get the type of field this is, as set by `setType(int)`
    `String` | `getValue()` Get the value of this field if set, or `null` if not.
    `boolean` | `isDoNotSpellCheck()` Deprecated. call isSpellCheck instead
    `boolean` | `isScrollable()` Get whether this field is scrollable or not - horizontally for for single line text fields, vertically for multi-line
    `boolean` | `isSpellCheck()` Return the value of the "spell check" flag, as set by `setSpellCheck(boolean)`
    `void` | `rebuild()` Cause the annotation list to be rebuilt.
    `void` | `setDefaultValue(String value)` Set the default value of this field - the value it will reset to if a `PDFAction.formReset()` occurs.
    `void` | `setDoNotSpellCheck(boolean check)` Deprecated. call setSpellCheck instead
    `void` | `setMaxLength(int maxlen)` Set the maximum length of the field.
    `void` | `setNumberOfCombs(int numcombs)` Set the number of "Combs" in this field.
    `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.
    `void` | `setSpellCheck(boolean spellcheck)` Set the "spell check" flag on the field, which controls whether Acrobat will run its spell-checker on the field.
    `void` | `setType(int type)` Set the type of field - one of`TYPE_NORMAL`, `TYPE_PASSWORD`, `TYPE_MULTILINE` or `TYPE_FILESELECT`
    `void` | `setValue(String value)` Set the value of this field.
    `String` | `toString()`

    - ### Methods inherited from class org.faceless.pdf2.FormElement

      `addPropertyChangeListener, duplicate, flatten, getAction, getAnnotation, getAnnotations, getDescription, getForm, isReadOnly, isRequired, isSubmitted, removePropertyChangeListener, setAction, setDescription, setReadOnly, setRequired, setSubmitted`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE_NORMAL

          public static final int TYPE_NORMAL

      Parameter to `setType(int)` to create a normal text box
      See Also:
        Constant Field Values

    - #### TYPE_MULTILINE

          public static final int TYPE_MULTILINE

      Parameter to `setType(int)` to create a multiline text box
      See Also:
        Constant Field Values

    - #### TYPE_PASSWORD

          public static final int TYPE_PASSWORD

      Parameter to `setType(int)` to create a text box for entering password
      See Also:
        Constant Field Values

    - #### TYPE_FILESELECT

          public static final int TYPE_FILESELECT

      Parameter to `setType(int)` to create a text box for selecting a file
      See Also:
        Constant Field Values

    - #### 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()

      Create a new FormText object. Annotations must be added separately by calling the `addAnnotation(org.faceless.pdf2.PDFPage, float, float, float, float)` method.
      Since:
        1.1.26

    - #### 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

    - #### setType

          public void setType(int type)

      Set the type of field - one of`TYPE_NORMAL`, `TYPE_PASSWORD`, `TYPE_MULTILINE` or `TYPE_FILESELECT`
      Since:
        2.0

    - #### getType

          public int getType()

      Get the type of field this is, as set by `setType(int)`
      Since:
        2.0

    - #### setValue

          public void setValue(String value)

      Set the value of this field.
      Throws:
        `IllegalArgumentException` - if the field is a `TYPE_PASSWORD`, the value is longer than `getMaxLength()` or it contains newlines when the field is not `TYPE_MULTILINE`

    - #### setDefaultValue

          public void setDefaultValue(String value)

      Set the default value of this field - the value it will reset to if a `PDFAction.formReset()` occurs.
      Throws:
        `IllegalArgumentException` - if the field is a `TYPE_PASSWORD`, the value is longer than `getMaxLength()` or it contains newlines when the field is not `TYPE_MULTILINE`

    - #### 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

    - #### 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`

    - #### setDoNotSpellCheck

          @Deprecated
          public void setDoNotSpellCheck(boolean check)

      Deprecated. call setSpellCheck instead

    - #### isDoNotSpellCheck

          @Deprecated
          public boolean isDoNotSpellCheck()

      Deprecated. call isSpellCheck instead

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization