Top Description Fields Constructors Methods
org.apache.pdfbox.pdmodel.interactive.form

public abstract Class PDChoice

extends PDVariableText
Class Inheritance
Known Direct Subclasses
org.apache.pdfbox.pdmodel.interactive.form.PDComboBox, org.apache.pdfbox.pdmodel.interactive.form.PDListBox
Imports
java.io.IOException, java.util.ArrayList, .Arrays, .Collections, .List, org.apache.pdfbox.cos.COSArray, .COSBase, .COSDictionary, .COSName, .COSString, org.apache.pdfbox.pdmodel.interactive.form.FieldUtils.KeyValue
A choice field contains several text items, one or more of which shall be selected as the field value.
Authors
sug, John Hewson

Field Summary

Modifier and TypeField and Description
pack-priv static final int
FLAG_COMBO

private static final int
FLAG_COMMIT_ON_SEL_CHANGE

private static final int
FLAG_DO_NOT_SPELL_CHECK

private static final int
FLAG_MULTI_SELECT

private static final int
FLAG_SORT

Inherited from org.apache.pdfbox.pdmodel.interactive.form.PDVariableText:
QUADDING_CENTEREDQUADDING_LEFTQUADDING_RIGHT

Constructor Summary

AccessConstructor and Description
public
PDChoice(PDAcroForm
The acroform.
acroForm)

pack-priv
PDChoice(PDAcroForm
The form that this field is part of.
acroForm, COSDictionary
the PDF object to represent as a field.
field, PDNonTerminalField
the parent node of the node
parent)

Constructor.

Method Summary

Modifier and TypeMethod and Description
pack-priv abstract void
constructAppearances()

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField.constructAppearances.

Constructs appearance streams and appearance dictionaries for all widget annotations.

public List<String>

Returns:

A non-null string.
getDefaultValue()

Returns the default values, or an empty List.

public List<String>

Returns:

List containing the export values.
getOptions()

This will get the option values "Opt".

public List<String>

Returns:

List containing all the display values.
getOptionsDisplayValues()

This will get the display values from the options.

public List<String>

Returns:

List containing all export values.
getOptionsExportValues()

This will get the export values from the options.

public List<Integer>

Returns:

List containing the indices of all selected options.
getSelectedOptionsIndex()

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

public List<String>

Returns:

A non-null string.
getValue()

Returns the selected values, or an empty List.

public String
getValueAsString()

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDField.getValueAsString.

Returns a string representation of the "V" entry, or an empty string.

private List<String>
getValueFor(COSName name)

Returns the selected values, or an empty List, for the given key.

public boolean

Returns:

true if value the choice is a combo box..
isCombo()

Determines if Combo is set.

public boolean

Returns:

true if value shall be committed as soon as a selection is made.
isCommitOnSelChange()

Determines if CommitOnSelChange is set.

public boolean

Returns:

true if spell checker is disabled.
isDoNotSpellCheck()

Determines if DoNotSpellCheck is set.

public boolean

Returns:

true if multi select is allowed.
isMultiSelect()

Determines if MultiSelect is set.

public boolean

Returns:

true if the options are sorted.
isSort()

Determines if Sort is set.

public void
setCombo(boolean
The value for Combo.
combo)

Set the Combo bit.

public void
setCommitOnSelChange(boolean
The value for CommitOnSelChange.
commitOnSelChange)

Set the CommitOnSelChange bit.

public void
setDefaultValue(String
The name of the selected item.
value)

Sets the default value of this field.

public void
setDoNotSpellCheck(boolean
The value for DoNotSpellCheck.
doNotSpellCheck)

Set the DoNotSpellCheck bit.

public void
setMultiSelect(boolean
The value for MultiSelect.
multiSelect)

Set the MultiSelect bit.

public void
setOptions(List<String>
List containing all possible options.
displayValues)

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

public void
setOptions(List<String>
List containing all possible export values.
exportValues, List<String>
List containing all possible display values.
displayValues)

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

public void
setSelectedOptionsIndex(List<Integer>
List containing the indices of all selected options.
values)

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

public void
setSort(boolean
The value for Sort.
sort)

Set the Sort bit.

public void
setValue(String
The name of the selected item.
value)

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDField.setValue.

Set the selected value of this field, and try to update the visual appearance.

public void
setValue(List<String>
the list of values
values)

Sets the entry "V" to the given values.

private void
updateSelectedOptionsIndex(List<String> values, List<String> options)

Update the 'I' key based on values set.

Inherited from org.apache.pdfbox.pdmodel.interactive.form.PDVariableText:
getDefaultAppearancegetDefaultAppearanceStringgetDefaultStyleStringgetQgetRichTextValuegetStringOrStreamsetDefaultAppearancesetDefaultStyleStringsetQsetRichTextValue

Field Detail

FLAG_COMBOback to summary
pack-priv static final int FLAG_COMBO
FLAG_COMMIT_ON_SEL_CHANGEback to summary
private static final int FLAG_COMMIT_ON_SEL_CHANGE
FLAG_DO_NOT_SPELL_CHECKback to summary
private static final int FLAG_DO_NOT_SPELL_CHECK
FLAG_MULTI_SELECTback to summary
private static final int FLAG_MULTI_SELECT
FLAG_SORTback to summary
private static final int FLAG_SORT

Constructor Detail

PDChoiceback to summary
public PDChoice(PDAcroForm acroForm)
Parameters
acroForm:PDAcroForm

The acroform.

See Also
PDField#PDField(PDAcroForm)
PDChoiceback to summary
pack-priv PDChoice(PDAcroForm acroForm, COSDictionary field, PDNonTerminalField parent)

Constructor.

Parameters
acroForm:PDAcroForm

The form that this field is part of.

field:COSDictionary

the PDF object to represent as a field.

parent:PDNonTerminalField

the parent node of the node

Method Detail

constructAppearancesback to summary
pack-priv abstract void constructAppearances() throws IOException

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField.constructAppearances.

Doc from org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField.constructAppearances.

Constructs appearance streams and appearance dictionaries for all widget annotations. Subclasses should not call this method directly but via applyChange().

Annotations
@Override
Exceptions
IOException:
if the appearance couldn't be generated
getDefaultValueback to summary
public List<String> getDefaultValue()

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

Returns:List<String>

A non-null string.

getOptionsback to summary
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<String>

List containing the export values.

getOptionsDisplayValuesback to summary
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<String>

List containing all the display values.

getOptionsExportValuesback to summary
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<String>

List containing all export values.

getSelectedOptionsIndexback to summary
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<Integer>

List containing the indices of all selected options.

getValueback to summary
public List<String> getValue()

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

Returns:List<String>

A non-null string.

getValueAsStringback to summary
public String getValueAsString()

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDField.getValueAsString.

Doc from org.apache.pdfbox.pdmodel.interactive.form.PDField.getValueAsString.

Returns a string representation of the "V" entry, or an empty string.

Returns:String

The list of widget annotations.

Annotations
@Override
getValueForback to summary
private List<String> getValueFor(COSName name)

Returns the selected values, or an empty List, for the given key.

isComboback to summary
public boolean isCombo()

Determines if Combo is set.

Returns:boolean

true if value the choice is a combo box..

isCommitOnSelChangeback to summary
public boolean isCommitOnSelChange()

Determines if CommitOnSelChange is set.

Returns:boolean

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

isDoNotSpellCheckback to summary
public boolean isDoNotSpellCheck()

Determines if DoNotSpellCheck is set.

Returns:boolean

true if spell checker is disabled.

isMultiSelectback to summary
public boolean isMultiSelect()

Determines if MultiSelect is set.

Returns:boolean

true if multi select is allowed.

isSortback to summary
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:boolean

true if the options are sorted.

setComboback to summary
public void setCombo(boolean combo)

Set the Combo bit.

Parameters
combo:boolean

The value for Combo.

setCommitOnSelChangeback to summary
public void setCommitOnSelChange(boolean commitOnSelChange)

Set the CommitOnSelChange bit.

Parameters
commitOnSelChange:boolean

The value for CommitOnSelChange.

setDefaultValueback to summary
public void setDefaultValue(String value)

Sets the default value of this field.

Parameters
value:String

The name of the selected item.

setDoNotSpellCheckback to summary
public void setDoNotSpellCheck(boolean doNotSpellCheck)

Set the DoNotSpellCheck bit.

Parameters
doNotSpellCheck:boolean

The value for DoNotSpellCheck.

setMultiSelectback to summary
public void setMultiSelect(boolean multiSelect)

Set the MultiSelect bit.

Parameters
multiSelect:boolean

The value for MultiSelect.

setOptionsback to summary
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<String>

List containing all possible options.

setOptionsback to summary
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<String>

List containing all possible export values.

displayValues:List<String>

List containing all possible display values.

See Also
setOptions(List)
setSelectedOptionsIndexback to summary
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<Integer>

List containing the indices of all selected options.

setSortback to summary
public void setSort(boolean sort)

Set the Sort bit.

Parameters
sort:boolean

The value for Sort.

See Also
isSort()
setValueback to summary
public void setValue(String value) throws IOException

Implements abstract org.apache.pdfbox.pdmodel.interactive.form.PDField.setValue.

Set the selected value of this field, and try to update the visual appearance.

Parameters
value:String

The name of the selected item.

Annotations
@Override
Exceptions
IOException:
if the value could not be set
setValueback to summary
public void setValue(List<String> values) throws IOException

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

Parameters
values:List<String>

the list of values

Exceptions
IOException:
if the appearance couldn't be generated.
updateSelectedOptionsIndexback to summary
private void updateSelectedOptionsIndex(List<String> values, List<String> options)

Update the 'I' key based on values set.