com.snowtide.pdf.forms

Class AcroChoiceField

java.lang.Object

com.snowtide.pdf.forms.AcroChoiceField

All Implemented Interfaces:

DocumentLocation, AcroFormField, FormField, Bounded

public class AcroChoiceField
extends java.lang.Object

Represents a multiple-choice form field in an interactive AcroForm.

getValue() will return the 'export value' set on the field being represented; this is the name of the option that was selected by the user. The display value of that option (a user-friendly representation of the export value) can be retrieved using the AcroChoiceField.getDisplayValue(String) function.

If AcroChoiceField.allowsMultipleChoices() returns true, getValue() may return a String[] instance containing export values, one for each of the options selected by the user. These values may also be used as parameters into the AcroChoiceField.getDisplayValue(String) function.

Note that if AcroChoiceField.isEditable() returns true, the String returned by getValue() may be user-entered text, and therefore would likely not have a corresponding display value provided by AcroChoiceField.getDisplayValue(String).

In addition to the standard AcroFormField.setValue(String) function, AcroChoiceField instances provide a AcroChoiceField.setValue(String[]) function, enabling the value of a multiple-selection choice field possible.

Since:

v2.1

Version:

©2004-2014 Snowtide

Field Summary

Fields

Modifier and Type	Field and Description
static int	CHOICE_TYPE_COMBO Value returned by AcroChoiceField.getWidgetType(), indicating that an AcroChoiceField is representing a drop-down combo box.
static int	CHOICE_TYPE_LIST Value returned by AcroChoiceField.getWidgetType() indicating that an AcroChoiceField is representing a list that can potentially allow multiple values to be selected.

Fields inherited from interface com.snowtide.pdf.forms.AcroFormField

FIELD_TYPE_BUTTON, FIELD_TYPE_CHOICE, FIELD_TYPE_OTHER, FIELD_TYPE_SIGNATURE, FIELD_TYPE_TEXT

Method Summary

Modifier and Type	Method and Description
boolean	allowsMultipleChoices() Returns true if this choice field's widget allows multiple selections.
boolean	canChangeValue() Always returns true.
java.lang.String	getDisplayValue(java.lang.String exportValue) Returns the display value associated with the supplied export value.
java.lang.String	getExportValue(java.lang.String displayValue)
java.util.Map	getOptions() Returns a Map containing all of the options offered by this choice field, using export values (strings that can be returned by getValue()) as keys mapped to display values (strings that are returned by AcroChoiceField.getDisplayValue(String), given a valid export value).
int	getWidgetType() Returns either AcroChoiceField.CHOICE_TYPE_COMBO (indicating that this choice widget is a dropdown, single-selection field), or AcroChoiceField.CHOICE_TYPE_LIST, indicating that this choice widget is a multiple-row, possibly multiple-selection field).
boolean	isEditable() Returns true if this field is user-editable, indicating that a user may set this field's value to a arbitrary character string.
boolean	setValue(java.lang.String value) Updates this choice field's value so that the option corresponding with the single specified String is selected.
boolean	setValue(java.lang.String[] values) Updates this choice field's value so that each of the options corresponding with the Strings in the specified array are selected.

Methods inherited from interface com.snowtide.pdf.forms.AcroFormField

getDefaultValue, getFullName, getLocalName, getMappingName, getType, getUIName, getValue, hasValueChanged, isReadOnly

Methods inherited from interface com.snowtide.pdf.forms.FormField

getName

Methods inherited from interface com.snowtide.pdf.DocumentLocation

pageNumber

Methods inherited from interface com.snowtide.pdf.layout.Bounded

bounds

Field Detail

CHOICE_TYPE_COMBO

public static final int CHOICE_TYPE_COMBO

Value returned by AcroChoiceField.getWidgetType(), indicating that an AcroChoiceField is representing a drop-down combo box.

See Also:

Constant Field Values

CHOICE_TYPE_LIST

public static final int CHOICE_TYPE_LIST

Value returned by AcroChoiceField.getWidgetType() indicating that an AcroChoiceField is representing a list that can potentially allow multiple values to be selected.

See Also:

AcroChoiceField.allowsMultipleChoices(), Constant Field Values

Method Detail

setValue

public boolean setValue(java.lang.String value)

Updates this choice field's value so that the option corresponding with the single specified String is selected.

Specified by:

setValue in interface AcroFormField

Returns:

true if this field's value changes as a result of this call, false otherwise

Throws:

java.lang.IllegalArgumentException - if the specified value is not an allowable value. To be allowable, the specified value must appear as a key in the Map returned by AcroChoiceField.getExportValue(String), or, if this field is editable, then any non-null String value is allowable.

Since:

v2.1

setValue

public boolean setValue(java.lang.String[] values)

Updates this choice field's value so that each of the options corresponding with the Strings in the specified array are selected.

Returns:

true if this field's value changes as a result of this call, false otherwise

Throws:

java.lang.IllegalArgumentException - if this field does not allow multiple choices or if any String in the provided array is not an allowable value. To be allowable, each String in the given array must be non-null, and must appear as a key in the Map returned by AcroChoiceField.getExportValue(String).

Since:

v2.1

canChangeValue

public boolean canChangeValue()

Always returns true.

Specified by:

canChangeValue in interface AcroFormField

getDisplayValue

public java.lang.String getDisplayValue(java.lang.String exportValue)

Returns the display value associated with the supplied export value.

getExportValue

public java.lang.String getExportValue(java.lang.String displayValue)

getOptions

public java.util.Map getOptions()

Returns a Map containing all of the options offered by this choice field, using export values (strings that can be returned by getValue()) as keys mapped to display values (strings that are returned by AcroChoiceField.getDisplayValue(String), given a valid export value).

isEditable

public boolean isEditable()

Returns true if this field is user-editable, indicating that a user may set this field's value to a arbitrary character string. If this happens, it is likely that this field's value will not correspond to a display value via AcroChoiceField.getDisplayValue(String).

getWidgetType

public int getWidgetType()

Returns either AcroChoiceField.CHOICE_TYPE_COMBO (indicating that this choice widget is a dropdown, single-selection field), or AcroChoiceField.CHOICE_TYPE_LIST, indicating that this choice widget is a multiple-row, possibly multiple-selection field).

allowsMultipleChoices

public boolean allowsMultipleChoices()

Returns true if this choice field's widget allows multiple selections. This will only be true if AcroChoiceField.getWidgetType() returns AcroChoiceField.CHOICE_TYPE_LIST.

This is important in that if this choice field's widget allows multiple selections, and multiple options have been selected, then the getValue() function will return an array of the selected options' values, instead of a simple String.