org.apache.pdfbox.pdmodel.interactive.form

## Class PDChoice

- java.lang.Object
- - org.apache.pdfbox.pdmodel.interactive.form.PDField
  - - org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField
    - - org.apache.pdfbox.pdmodel.interactive.form.PDVariableText
      - - org.apache.pdfbox.pdmodel.interactive.form.PDChoice

All Implemented Interfaces:
  COSObjectable

Direct Known Subclasses:
  PDComboBox, PDListBox

    public abstract class PDChoice
    extends PDVariableText

A choice field contains several text items, one or more of which shall be selected as the field value.

Author:
  sug, John Hewson

### Field Summary

### Fields inherited from class org.apache.pdfbox.pdmodel.interactive.form.PDVariableText

`QUADDING_CENTERED, QUADDING_LEFT, QUADDING_RIGHT`

### Constructor Summary

Constructors
Constructor and Description
`PDChoice(PDAcroForm acroForm)`

### Method Summary

All Methods Instance Methods Concrete Methods
`List<String>` `getDefaultValue()` Returns the default values, or an empty List.
`List<String>` `getOptions()` This will get the option values "Opt".
`List<String>` `getOptionsDisplayValues()` This will get the display values from the options.
`List<String>` `getOptionsExportValues()` This will get the export values from the options.
`List<Integer>` `getSelectedOptionsIndex()` This will get the indices of the selected options - the 'I' key.
`List<String>` `getValue()` Returns the selected values, or an empty List.
`String` `getValueAsString()` Returns a string representation of the "V" entry, or an empty string.
`boolean` `isCombo()` Determines if Combo is set.
`boolean` `isCommitOnSelChange()` Determines if CommitOnSelChange is set.
`boolean` `isDoNotSpellCheck()` Determines if DoNotSpellCheck is set.
`boolean` `isMultiSelect()` Determines if MultiSelect is set.
`boolean` `isSort()` Determines if Sort is set.
`void` `setCombo(boolean combo)` Set the Combo bit.
`void` `setCommitOnSelChange(boolean commitOnSelChange)` Set the CommitOnSelChange bit.
`void` `setDefaultValue(String value)` Sets the default value of this field.
`void` `setDoNotSpellCheck(boolean doNotSpellCheck)` Set the DoNotSpellCheck bit.
`void` `setMultiSelect(boolean multiSelect)` Set the MultiSelect bit.
`void` `setOptions(List<String> displayValues)` This will set the display values - the 'Opt' key.
`void` `setOptions(List<String> exportValues, List<String> displayValues)` This will set the display and export values - the 'Opt' key.
`void` `setSelectedOptionsIndex(List<Integer> values)` This will set the indices of the selected options - the 'I' key.
`void` `setSort(boolean sort)` Set the Sort bit.
`void` `setValue(List<String> values)` Sets the entry "V" to the given values.
`void` `setValue(String value)` Sets the selected value of this field.

### Methods inherited from class org.apache.pdfbox.pdmodel.interactive.form.PDVariableText

`getDefaultAppearance, getDefaultStyleString, getQ, getRichTextValue, getStringOrStream, setDefaultAppearance, setDefaultStyleString, setQ, setRichTextValue`

### Methods inherited from class org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField

`applyChange, getFieldFlags, getFieldType, getWidget, getWidgets, importFDF, setActions, setWidgets`

### Methods inherited from class org.apache.pdfbox.pdmodel.interactive.form.PDField

`getAcroForm, getActions, getAlternateFieldName, getCOSObject, getFullyQualifiedName, getInheritableAttribute, getMappingName, getParent, getPartialName, isNoExport, isReadOnly, isRequired, setAlternateFieldName, setFieldFlags, setMappingName, setNoExport, setPartialName, setReadOnly, setRequired, toString`

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

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

### Constructor Detail

#### PDChoice

    public PDChoice(PDAcroForm acroForm)

Parameters:
  `acroForm` - The acroform.
See Also:
  `PDField(PDAcroForm)`

### Method Detail

#### getOptions

    public List<String> getOptions()

This will get the option values "Opt".

For a choice field the options array can either be an array of text strings or an array of a two-element arrays.
The method always only returns either the text strings or, in case of two-element arrays, an array of the first element of the two-element arrays

Use `getOptionsExportValues()` and `getOptionsDisplayValues()` to get the entries of two-element arrays.

Returns:
  List containing the export values.

#### setOptions

    public void setOptions(List<String> displayValues)

This will set the display values - the 'Opt' key.

The Opt array specifies the list of options in the choice field either as an array of text strings representing the display value or as an array of a two-element array where the first element is the export value and the second the display value.

To set both the export and the display value use `setOptions(List, List)`

Parameters:
  `displayValues` - List containing all possible options.

#### setOptions

    public void setOptions(List<String> exportValues,
                           List<String> displayValues)

This will set the display and export values - the 'Opt' key.

This will set both, the export value and the display value of the choice field. If either one of the parameters is null or an empty list is supplied the options will be removed.

An `IllegalArgumentException` will be thrown if the number of items in the list differ.

Parameters:
  `exportValues` - List containing all possible export values.
  `displayValues` - List containing all possible display values.
See Also:
  `setOptions(List)`

#### getOptionsDisplayValues

    public List<String> getOptionsDisplayValues()

This will get the display values from the options.

For options with an array of text strings the display value and export value are the same.
For options with an array of two-element arrays the display value is the second entry in the two-element array.

Returns:
  List containing all the display values.

#### getOptionsExportValues

    public List<String> getOptionsExportValues()

This will get the export values from the options.

For options with an array of text strings the display value and export value are the same.
For options with an array of two-element arrays the export value is the first entry in the two-element array.

Returns:
  List containing all export values.

#### getSelectedOptionsIndex

    public List<Integer> getSelectedOptionsIndex()

This will get the indices of the selected options - the 'I' key.

This is only needed if a choice field allows multiple selections and two different items have the same export value or more than one values is selected.

The indices are zero-based

Returns:
  List containing the indices of all selected options.

#### setSelectedOptionsIndex

    public void setSelectedOptionsIndex(List<Integer> values)

This will set the indices of the selected options - the 'I' key.

This method is preferred over `setValue(List)` for choice fields which

- do support multiple selections
- have export values with the same value

Setting the index will set the value too.

Parameters:
  `values` - List containing the indices of all selected options.

#### isSort

    public boolean isSort()

Determines if Sort is set.

If set, the field’s option items shall be sorted alphabetically. The sorting has to be done when writing the PDF. PDF Readers are supposed to display the options in the order in which they occur in the Opt array.

Returns:
  true if the options are sorted.

#### setSort

    public void setSort(boolean sort)

Set the Sort bit.

Parameters:
  `sort` - The value for Sort.
See Also:
  `isSort()`

#### isMultiSelect

    public boolean isMultiSelect()

Determines if MultiSelect is set.

Returns:
  true if multi select is allowed.

#### setMultiSelect

    public void setMultiSelect(boolean multiSelect)

Set the MultiSelect bit.

Parameters:
  `multiSelect` - The value for MultiSelect.

#### isDoNotSpellCheck

    public boolean isDoNotSpellCheck()

Determines if DoNotSpellCheck is set.

Returns:
  true if spell checker is disabled.

#### setDoNotSpellCheck

    public void setDoNotSpellCheck(boolean doNotSpellCheck)

Set the DoNotSpellCheck bit.

Parameters:
  `doNotSpellCheck` - The value for DoNotSpellCheck.

#### isCommitOnSelChange

    public boolean isCommitOnSelChange()

Determines if CommitOnSelChange is set.

Returns:
  true if value shall be committed as soon as a selection is made.

#### setCommitOnSelChange

    public void setCommitOnSelChange(boolean commitOnSelChange)

Set the CommitOnSelChange bit.

Parameters:
  `commitOnSelChange` - The value for CommitOnSelChange.

#### isCombo

    public boolean isCombo()

Determines if Combo is set.

Returns:
  true if value the choice is a combo box..

#### setCombo

    public void setCombo(boolean combo)

Set the Combo bit.

Parameters:
  `combo` - The value for Combo.

#### setValue

    public void setValue(String value)
                  throws IOException

Sets the selected value of this field. It also tries to update the visual appearance, unless `PDAcroForm.getNeedAppearances()` is true.

Specified by:
  `setValue` in class `PDField`
Parameters:
  `value` - The name of the selected item.
Throws:
  `IOException` - if the value could not be set

#### setDefaultValue

    public void setDefaultValue(String value)
                         throws IOException

Sets the default value of this field.

Parameters:
  `value` - The name of the selected item.
Throws:
  `IOException` - if the value could not be set

#### setValue

    public void setValue(List<String> values)
                  throws IOException

Sets the entry "V" to the given values. Requires `isMultiSelect()` to be true.

Parameters:
  `values` - the list of values
Throws:
  `IOException` - if the appearance couldn't be generated.

#### getValue

    public List<String> getValue()

Returns the selected values, or an empty List. This list always contains a single item unless `isMultiSelect()` is true.

Returns:
  A non-null string.

#### getDefaultValue

    public List<String> getDefaultValue()

Returns the default values, or an empty List. This list always contains a single item unless `isMultiSelect()` is true.

Returns:
  A non-null string.

#### getValueAsString

    public String getValueAsString()

Description copied from class: `PDField`
Returns a string representation of the "V" entry, or an empty string.

Specified by:
  `getValueAsString` in class `PDField`
Returns:
  The list of widget annotations.