org.faceless.pdf2

## Class FormChoice

- java.lang.Object
- - org.faceless.pdf2.FormElement
  - - org.faceless.pdf2.FormChoice

- All Implemented Interfaces:
    Cloneable

      public final class FormChoice
      extends FormElement

  A "ListBox" type of form element, where the user can select an entry off a list of several predefined options.

  Several variations of this type of field are available:

  `TYPE_DROPDOWN` | A dropdown list, where a single item can be selected
  `TYPE_COMBO` | Identical to a dropdown list, but the user can type in their own value as well as select one off a list
  `TYPE_SCROLLABLE` | A scrollable list, where the user can see several options on the screen at once but select only one
  `TYPE_MULTISCROLLABLE` | Identical to a SCROLLABLE list, but mutiple options can be selected at once

  For all these lists, the options are specified by adding values to the `Map` returned by `getOptions()`. The values are displayed in the order they're added to the Map.

  Here's an example creating a simple list of values:

         Form form = pdf.getForm();
         FormChoice colors = new FormChoice(FormChoice.TYPE_SCROLLABLE, page, 100,100,300,300);
         Map vals = colors.getOptions();
         vals.put("Red", null);
         vals.put("Green", null);
         vals.put("Blue", null);
         colors.setValue("Green");
         form.addElement("FavoriteColor", colors);

  and here's an example showing how to retrieve the value of an element

         Form form = pdf.getForm();
         FormChoice choice = (FormChoice)form.getElement("FavoriteColor");
         String value = choice.getValue();  // May be null

  Since:
    1.1.23

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TYPE_COMBO` A type passed to the constructor representing a dropdown list where the value can also be edited like a text field.
    `static int` | `TYPE_DROPDOWN` A type passed to the constructor representing a dropdown list, similar to a drop-down menu
    `static int` | `TYPE_MULTISCROLLABLE` A type passed to the constructor representing a scollable list, which displays one or more lines at once.
    `static int` | `TYPE_SCROLLABLE` A type passed to the constructor representing a scollable list, which displays one or more lines at once.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FormChoice(int type)` Create a new `FormChoice` element with no annotations.
    `FormChoice(int type, PDFPage page, float x1, float y1, float x2, float y2)` Create a new `FormChoice` element with an annotation at the specified location.

  - ### Method Summary

    All Methods Instance Methods Concrete 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 value this choice field resets to when a `PDFAction.formReset()` occurs.
    `Map<String,String>` | `getOptions()` Return a `Map` containing the options for this choice field A Map contains keys and their corresponding values, which is the way the choice fields are done in PDF (and HTML too).
    `int[]` | `getSelectedIndices()` Return an array of integers showing which entries in the `getOptions()` map are selected.
    `int` | `getType()` Return the type of choice field this object represents - one of `TYPE_SCROLLABLE`, `TYPE_MULTISCROLLABLE`, `TYPE_DROPDOWN` or `TYPE_COMBO`
    `String` | `getValue()` Return the current value of the choice field.
    `boolean` | `isImmediatelyCommitted()` Return whether the field is immediatley committed, as set by `setImmediatelyCommitted(boolean)`
    `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 choice field.
    `void` | `setImmediatelyCommitted(boolean update)` Set whether changes to this Choice field are made immediately the new item is chosen (true) or whether the change is made when the field loses focus (false).
    `void` | `setSelectedIndices(int[] vals)` Set which entries in the `getOptions()` map are selected.
    `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` | `setValue(String value)` Set the value of this choice 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_DROPDOWN

          public static final int TYPE_DROPDOWN

      A type passed to the constructor representing a dropdown list, similar to a drop-down menu
      See Also:
        Constant Field Values

    - #### TYPE_SCROLLABLE

          public static final int TYPE_SCROLLABLE

      A type passed to the constructor representing a scollable list, which displays one or more lines at once.
      See Also:
        Constant Field Values

    - #### TYPE_MULTISCROLLABLE

          public static final int TYPE_MULTISCROLLABLE

      A type passed to the constructor representing a scollable list, which displays one or more lines at once. Multiple items can be selected
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### TYPE_COMBO

          public static final int TYPE_COMBO

      A type passed to the constructor representing a dropdown list where the value can also be edited like a text field.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FormChoice

          public FormChoice(int type)

      Create a new `FormChoice` element with no annotations. Annotations should be added via the `addAnnotation` method.
      Since:
        1.1.26

    - #### FormChoice

          public FormChoice(int type,
                            PDFPage page,
                            float x1,
                            float y1,
                            float x2,
                            float y2)

      Create a new `FormChoice` element with an annotation at the specified location. Identical to calling

             FormChoice choice = new FormChoice(type);
             choice.addAnnotation(page, x1, y1, x2, y2);

      Parameters:
        `type` - the type of annotation
        `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 (a similar constructor existed from 1.1.26, but with the first two arguments swapped)

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

      Return the type of choice field this object represents - one of `TYPE_SCROLLABLE`, `TYPE_MULTISCROLLABLE`, `TYPE_DROPDOWN` or `TYPE_COMBO`
      Returns:
        the type of choice field

    - #### getOptions

          public Map<String,String> getOptions()

      Return a `Map` containing the options for this choice field

      A Map contains keys and their corresponding values, which is the way the choice fields are done in PDF (and HTML too). They key is displayed to the user, and the value, if specified, is what's included when the form is submitted. So, for example, the line `choice.getOptions().put("Red","1")` will display the value "Red" on screen, but send the value of "1" when the form is submitted. If the submitted value should be the same as the displayed value, just do `choice.getOptions().put("Red", null)` or `choice.getOptions().put("Red", "Red")`.

      Values are displayed in the field in the order that they are added to the Map, `key` may not be null, and both `key` and `value` must be `String` objects.

    - #### setImmediatelyCommitted

          public void setImmediatelyCommitted(boolean update)

      Set whether changes to this Choice field are made immediately the new item is chosen (true) or whether the change is made when the field loses focus (false). Only makes a difference in Acrobat 6 or later, although can safely be used with earlier viewers.
      Since:
        2.0

    - #### isImmediatelyCommitted

          public boolean isImmediatelyCommitted()

      Return whether the field is immediatley committed, as set by `setImmediatelyCommitted(boolean)`
      Since:
        2.0

    - #### getSelectedIndices

          public int[] getSelectedIndices()

      Return an array of integers showing which entries in the `getOptions()` map are selected. The returned array will have a length of zero if no value is selected or a `TYPE_COMBO` field has a custom value, otherwise the returned array will typically have a single element - the exception being `TYPE_MULTISCROLLABLE` fields.
      Since:
        2.9

    - #### setSelectedIndices

          public void setSelectedIndices(int[] vals)

      Set which entries in the `getOptions()` map are selected. Unless the list is a `TYPE_MULTISCROLLABLE` then the array must have either zero or one elements - multi-scrollable lists may have more.
      Parameters:
        `vals` - an array of zero or more indices which are to be marked as selected
      Since:
        2.9

    - #### setValue

          public void setValue(String value)

      Set the value of this choice field. For `TYPE_COMBO` fields, the value may be anything, otherwise the value must exist in the `getOptions().values()` set. For `TYPE_MULTISCROLLABLE` lists, multiple items can be selected by separating them with a newline, eg. "Tuesday\nWednesday\nThursday"
      Parameters:
        `value` - the value to set the field to

    - #### setDefaultValue

          public void setDefaultValue(String value)

      Set the default value of this choice field. Identical to `setValue(java.lang.String, java.lang.String)` except this is the value the field reverts to when a `PDFAction.formReset()` action is called.
      Parameters:
        `value` - the value to set the field to when the form is reset

    - #### getValue

          public String getValue()

      Return the current value of the choice field. See `setValue(java.lang.String, java.lang.String)` for a description of the value that is returned by this method
      Specified by:
        `getValue` in class `FormElement`
      Returns:
        the value of this choice field

    - #### getDefaultValue

          public String getDefaultValue()

      Return the value this choice field resets to when a `PDFAction.formReset()` occurs. See `setValue(java.lang.String, java.lang.String)` for a description of the value that is returned by this method
      Returns:
        the value this choice field reverts to when the form is reset

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

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

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization