com.lowagie.text.pdf

## Class TextField

- java.lang.Object
- - com.lowagie.text.pdf.BaseField
  - - com.lowagie.text.pdf.TextField

-     public class TextField
      extends BaseField

  Supports text, combo and list fields generating the correct appearances. All the option in the Acrobat GUI are supported in an easy to use API.
  Author:
    Paulo Soares (psoares@consiste.pt)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.lang.String[]` | `choiceExports` Holds value of property choiceExports.
    `private java.lang.String[]` | `choices` Holds value of property choices.
    `private java.util.ArrayList` | `choiceSelections` Holds value of property choiceSelection.
    `private java.lang.String` | `defaultText` Holds value of property defaultText.
    `private BaseFont` | `extensionFont` Holds value of property extensionFont.
    `private float` | `extraMarginLeft`
    `private float` | `extraMarginTop`
    `private java.util.ArrayList` | `substitutionFonts` Holds value of property substitutionFonts.
    `private int` | `topFirst`

    - ### Fields inherited from class com.lowagie.text.pdf.BaseField

      `alignment, backgroundColor, BORDER_WIDTH_MEDIUM, BORDER_WIDTH_THICK, BORDER_WIDTH_THIN, borderColor, borderStyle, borderWidth, box, COMB, DO_NOT_SCROLL, DO_NOT_SPELL_CHECK, EDIT, fieldName, FILE_SELECTION, font, fontSize, HIDDEN, HIDDEN_BUT_PRINTABLE, maxCharacterLength, MULTILINE, MULTISELECT, options, PASSWORD, READ_ONLY, REQUIRED, rotation, text, textColor, visibility, VISIBLE, VISIBLE_BUT_DOES_NOT_PRINT, writer`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextField(PdfWriter writer, Rectangle box, java.lang.String fieldName)` Creates a new `TextField`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChoiceSelection(int selection)` adds another (or a first I suppose) selection to a MULTISELECT list.
    `private static void` | `changeFontSize(Phrase p, float size)`
    `private static boolean` | `checkRTL(java.lang.String text)`
    `private Phrase` | `composePhrase(java.lang.String text, BaseFont ufont, java.awt.Color color, float fontSize)`
    `PdfAppearance` | `getAppearance()` Get the `PdfAppearance` of a text or combo field
    `java.lang.String[]` | `getChoiceExports()` Gets the export values in list/combo fields.
    `protected PdfFormField` | `getChoiceField(boolean isList)`
    `java.lang.String[]` | `getChoices()` Gets the choices to be presented to the user in list/combo fields.
    `int` | `getChoiceSelection()` Gets the zero based index of the selected item.
    `PdfFormField` | `getComboField()` Gets a new combo field.
    `java.lang.String` | `getDefaultText()` Gets the default text.
    `BaseFont` | `getExtensionFont()` Gets the extensionFont.
    `(package private) PdfAppearance` | `getListAppearance()` Get the `PdfAppearance` of a list field
    `PdfFormField` | `getListField()` Gets a new list field.
    `java.util.ArrayList` | `getSubstitutionFonts()` Gets the list of substitution fonts.
    `PdfFormField` | `getTextField()` Gets a new text field.
    `private int` | `getTopChoice()`
    `(package private) int` | `getTopFirst()`
    `java.util.ArrayList` | `gteChoiceSelections()`
    `static java.lang.String` | `obfuscatePassword(java.lang.String text)` Obfuscates a password `String`.
    `static java.lang.String` | `removeCRLF(java.lang.String text)` Removes CRLF from a `String`.
    `void` | `setChoiceExports(java.lang.String[] choiceExports)` Sets the export values in list/combo fields.
    `void` | `setChoices(java.lang.String[] choices)` Sets the choices to be presented to the user in list/combo fields.
    `void` | `setChoiceSelection(int choiceSelection)` Sets the zero based index of the selected item.
    `void` | `setChoiceSelections(java.util.ArrayList selections)` replaces the existing selections with the param.
    `void` | `setDefaultText(java.lang.String defaultText)` Sets the default text.
    `void` | `setExtensionFont(BaseFont extensionFont)` Sets the extensionFont.
    `void` | `setExtraMargin(float extraMarginLeft, float extraMarginTop)` Sets extra margins in text fields to better mimic the Acrobat layout.
    `void` | `setSubstitutionFonts(java.util.ArrayList substitutionFonts)` Sets a list of substitution fonts.
    `private void` | `writeMultipleValues(PdfFormField field, java.lang.String[][] mix)`

    - ### Methods inherited from class com.lowagie.text.pdf.BaseField

      `breakLines, getAlignment, getBackgroundColor, getBorderAppearance, getBorderColor, getBorderStyle, getBorderWidth, getBox, getFieldName, getFont, getFontSize, getHardBreaks, getMaxCharacterLength, getOptions, getRealFont, getRotation, getText, getTextColor, getVisibility, getWriter, moveFields, setAlignment, setBackgroundColor, setBorderColor, setBorderStyle, setBorderWidth, setBox, setFieldName, setFont, setFontSize, setMaxCharacterLength, setOptions, setRotation, setRotationFromPage, setText, setTextColor, setVisibility, setWriter, trimRight`

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### defaultText

          private java.lang.String defaultText

      Holds value of property defaultText.

    - #### choices

          private java.lang.String[] choices

      Holds value of property choices.

    - #### choiceExports

          private java.lang.String[] choiceExports

      Holds value of property choiceExports.

    - #### choiceSelections

          private java.util.ArrayList choiceSelections

      Holds value of property choiceSelection.

    - #### topFirst

          private int topFirst

    - #### extraMarginLeft

          private float extraMarginLeft

    - #### extraMarginTop

          private float extraMarginTop

    - #### substitutionFonts

          private java.util.ArrayList substitutionFonts

      Holds value of property substitutionFonts.

    - #### extensionFont

          private BaseFont extensionFont

      Holds value of property extensionFont.

  - ### Constructor Detail

    - #### TextField

          public TextField(PdfWriter writer,
                   Rectangle box,
                   java.lang.String fieldName)

      Creates a new `TextField`.
      Parameters:
        `writer` - the document `PdfWriter`
        `box` - the field location and dimensions
        `fieldName` - the field name. If `null` only the widget keys will be included in the field allowing it to be used as a kid field.

  - ### Method Detail

    - #### checkRTL

          private static boolean checkRTL(java.lang.String text)

    - #### changeFontSize

          private static void changeFontSize(Phrase p,
                            float size)

    - #### composePhrase

          private Phrase composePhrase(java.lang.String text,
                             BaseFont ufont,
                             java.awt.Color color,
                             float fontSize)

    - #### removeCRLF

          public static java.lang.String removeCRLF(java.lang.String text)

      Removes CRLF from a `String`.
      Parameters:
        `text` -
      Returns:
        String
      Since:
        2.1.5

    - #### obfuscatePassword

          public static java.lang.String obfuscatePassword(java.lang.String text)

      Obfuscates a password `String`. Every character is replaced by an asterisk (*).
      Parameters:
        `text` -
      Returns:
        String
      Since:
        2.1.5

    - #### getAppearance

          public PdfAppearance getAppearance()
                                      throws java.io.IOException,
                                             DocumentException

      Get the `PdfAppearance` of a text or combo field
      Returns:
        A `PdfAppearance`
      Throws:
        `java.io.IOException` - on error
        `DocumentException` - on error

    - #### getListAppearance

          PdfAppearance getListAppearance()
                                    throws java.io.IOException,
                                           DocumentException

      Get the `PdfAppearance` of a list field
      Returns:
        A `PdfAppearance`
      Throws:
        `java.io.IOException` - on error
        `DocumentException` - on error

    - #### getTextField

          public PdfFormField getTextField()
                                    throws java.io.IOException,
                                           DocumentException

      Gets a new text field.
      Returns:
        a new text field
      Throws:
        `java.io.IOException` - on error
        `DocumentException` - on error

    - #### getComboField

          public PdfFormField getComboField()
                                     throws java.io.IOException,
                                            DocumentException

      Gets a new combo field.
      Returns:
        a new combo field
      Throws:
        `java.io.IOException` - on error
        `DocumentException` - on error

    - #### getListField

          public PdfFormField getListField()
                                    throws java.io.IOException,
                                           DocumentException

      Gets a new list field.
      Returns:
        a new list field
      Throws:
        `java.io.IOException` - on error
        `DocumentException` - on error

    - #### getTopChoice

          private int getTopChoice()

    - #### getChoiceField

          protected PdfFormField getChoiceField(boolean isList)
                                         throws java.io.IOException,
                                                DocumentException

      Throws:
        `java.io.IOException`
        `DocumentException`

    - #### writeMultipleValues

          private void writeMultipleValues(PdfFormField field,
                                 java.lang.String[][] mix)

    - #### getDefaultText

          public java.lang.String getDefaultText()

      Gets the default text.
      Returns:
        the default text

    - #### setDefaultText

          public void setDefaultText(java.lang.String defaultText)

      Sets the default text. It is only meaningful for text fields.
      Parameters:
        `defaultText` - the default text

    - #### getChoices

          public java.lang.String[] getChoices()

      Gets the choices to be presented to the user in list/combo fields.
      Returns:
        the choices to be presented to the user

    - #### setChoices

          public void setChoices(java.lang.String[] choices)

      Sets the choices to be presented to the user in list/combo fields.
      Parameters:
        `choices` - the choices to be presented to the user

    - #### getChoiceExports

          public java.lang.String[] getChoiceExports()

      Gets the export values in list/combo fields.
      Returns:
        the export values in list/combo fields

    - #### setChoiceExports

          public void setChoiceExports(java.lang.String[] choiceExports)

      Sets the export values in list/combo fields. If this array is `null` then the choice values will also be used as the export values.
      Parameters:
        `choiceExports` - the export values in list/combo fields

    - #### getChoiceSelection

          public int getChoiceSelection()

      Gets the zero based index of the selected item.
      Returns:
        the zero based index of the selected item

    - #### gteChoiceSelections

          public java.util.ArrayList gteChoiceSelections()

    - #### setChoiceSelection

          public void setChoiceSelection(int choiceSelection)

      Sets the zero based index of the selected item.
      Parameters:
        `choiceSelection` - the zero based index of the selected item

    - #### addChoiceSelection

          public void addChoiceSelection(int selection)

      adds another (or a first I suppose) selection to a MULTISELECT list. This doesn't do anything unless this.options & MUTLISELECT != 0
      Parameters:
        `selection` - new selection

    - #### setChoiceSelections

          public void setChoiceSelections(java.util.ArrayList selections)

      replaces the existing selections with the param. If this field isn't a MULTISELECT list, all but the first element will be removed.
      Parameters:
        `selections` - new selections. If null, it clear()s the underlying ArrayList.

    - #### getTopFirst

          int getTopFirst()

    - #### setExtraMargin

          public void setExtraMargin(float extraMarginLeft,
                            float extraMarginTop)

      Sets extra margins in text fields to better mimic the Acrobat layout.
      Parameters:
        `extraMarginLeft` - the extra margin left
        `extraMarginTop` - the extra margin top

    - #### getSubstitutionFonts

          public java.util.ArrayList getSubstitutionFonts()

      Gets the list of substitution fonts. The list is composed of `BaseFont` and can be `null`. The fonts in this list will be used if the original font doesn't contain the needed glyphs.
      Returns:
        the list

    - #### setSubstitutionFonts

          public void setSubstitutionFonts(java.util.ArrayList substitutionFonts)

      Sets a list of substitution fonts. The list is composed of `BaseFont` and can also be `null`. The fonts in this list will be used if the original font doesn't contain the needed glyphs.
      Parameters:
        `substitutionFonts` - the list

    - #### getExtensionFont

          public BaseFont getExtensionFont()

      Gets the extensionFont. This font will be searched before the substitution fonts. It may be `null`.
      Returns:
        the extensionFont

    - #### setExtensionFont

          public void setExtensionFont(BaseFont extensionFont)

      Sets the extensionFont. This font will be searched before the substitution fonts. It may be `null`.
      Parameters:
        `extensionFont` - New value of property extensionFont.