AcroChoiceField (PDFTextStream API Reference)

java.lang.Object
- com.snowtide.pdf.forms.AcroChoiceField

All Implemented Interfaces:

AcroFormField, FormField
```
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 getDisplayValue(String) function.

If 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 getDisplayValue(String) function.

Note that if 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 getDisplayValue(String).

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

Since:

v2.1

Version:

©2004-2012 Snowtide Informatics Systems, Inc.

Field Summary

Fields
Modifier and Type	Field and Description
`protected com.snowtide.pdf.PDFTextStreamCallback`	`callback`
`static int`	`CHOICE_TYPE_COMBO` Value returned by `getWidgetType()`, indicating that an `AcroChoiceField` is representing a drop-down combo box.
`static int`	`CHOICE_TYPE_LIST` Value returned by `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

Methods
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.Object`	`getDefaultValue()` Returns the default value to which the field reverts when a reset-form action is executed, as specified in the /DV entry in this field's PDF dictionary.
`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.lang.String`	`getFullName()` Returns the fully-qualified name of this field, which should be unique within a PDF document form.
`java.lang.String`	`getLocalName()` Returns the local name of the field, as specified in the /T entry in this field's PDF dictionary.
`java.lang.String`	`getMappingName()` Returns the 'mapping name' of this field, as specified in the /TM entry in this field's PDF dictionary.
`java.lang.String`	`getName()` Returns the canonical name of this field.
`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 `getDisplayValue(String)`, given a valid export value).
`java.lang.Object`	`getType()` Returns the type of field, as specified in the /FT entry in this field's PDF dictionary.
`java.lang.String`	`getUIName()` Returns the user-friendly name of this field, as specified in the /TU entry in this field's PDF dictionary.
`java.lang.Object`	`getValue()` Returns the value of this field, as specified in the /V entry in this field's PDF dictionary.
`int`	`getWidgetType()` Returns either `CHOICE_TYPE_COMBO` (indicating that this choice widget is a dropdown, single-selection field), or `CHOICE_TYPE_LIST`, indicating that this choice widget is a multiple-row, possibly multiple-selection field).
`boolean`	`hasValueChanged()` Returns true only if this field's value has been changed since being loaded from the PDF document.
`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`	`isReadOnly()` Returns true only if this field is designated as read-only.
`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 class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CHOICE_TYPE_COMBO
```
public static final int CHOICE_TYPE_COMBO
```
    Value returned by 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 getWidgetType() indicating that an AcroChoiceField is representing a list that can potentially allow multiple values to be selected.
    
    See Also:
    allowsMultipleChoices(), Constant Field Values
  - callback
```
protected final com.snowtide.pdf.PDFTextStreamCallback callback
```
- Method Detail
  - setValue
```
public boolean setValue(java.lang.String value)
                 throws java.lang.IllegalArgumentException
```
    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 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)
                 throws java.lang.IllegalArgumentException
```
    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 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 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 getDisplayValue(String).
  - getWidgetType
```
public int getWidgetType()
```
    Returns either CHOICE_TYPE_COMBO (indicating that this choice widget is a dropdown, single-selection field), or 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 getWidgetType() returns 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.
  - isReadOnly
```
public boolean isReadOnly()
```
    Description copied from interface: AcroFormField
    
    Returns true only if this field is designated as read-only. Note that this is just a hint, provided for the benefit of end-user tools. PDFTextStream does not enforce the read-only state of a form field; i.e. it will allow a field's value to be set even if it is designated as read-only.
    
    Specified by:
    
    isReadOnly in interface AcroFormField
  - getDefaultValue
```
public java.lang.Object getDefaultValue()
```
    Description copied from interface: AcroFormField
    
    Returns the default value to which the field reverts when a reset-form action is executed, as specified in the /DV entry in this field's PDF dictionary. The type of the returned object will be the same as the type of object returned by the AcroFormField.getValue() function, and depends upon the type of this field.
    
    Specified by:
    
    getDefaultValue in interface AcroFormField
  - getFullName
```
public java.lang.String getFullName()
```
    Description copied from interface: AcroFormField
    
    Returns the fully-qualified name of this field, which should be unique within a PDF document form. Details of how full names are constructed are specified in Section 8.6.2 (Field Names) of the PDF Document Specification.
    
    It suffices to say here that form fields in an interactive AcroForm are defined in a hierarchical manner, and that their local names are used to derive a period-delimited full name that guarantees each name's uniqueness within the parent AcroForm.
    
    Specified by:
    
    getFullName in interface AcroFormField
  - getLocalName
```
public java.lang.String getLocalName()
```
    Description copied from interface: AcroFormField
    
    Returns the local name of the field, as specified in the /T entry in this field's PDF dictionary. This name is also used as the value returned by the FormField.getName() implementation.
    
    Specified by:
    
    getLocalName in interface AcroFormField
  - getMappingName
```
public java.lang.String getMappingName()
```
    Description copied from interface: AcroFormField
    
    Returns the 'mapping name' of this field, as specified in the /TM entry in this field's PDF dictionary. The mapping name is used to identify the field in exported form data formats. This function can return null if no mapping name is defined.
    
    Specified by:
    
    getMappingName in interface AcroFormField
  - getName
```
public java.lang.String getName()
```
    Description copied from interface: FormField
    
    Returns the canonical name of this field. Only one FormField instance with a particular name should be available from a Form instance.
    
    Specified by:
    
    getName in interface FormField
  - getType
```
public java.lang.Object getType()
```
    Description copied from interface: AcroFormField
    Returns the type of field, as specified in the /FT entry in this field's PDF dictionary. This is an indication of the subtype of this AcroFormField instance:
    - If the return value is FIELD_TYPE_BUTTON, then this AcroFormField is an instance of AcroButtonField
    - If the return value is FIELD_TYPE_TEXT, then this AcroFormField is an instance of AcroTextField
    - If the return value is FIELD_TYPE_CHOICE, then this AcroFormField is an instance of AcroChoiceField
    - If the return value is FIELD_TYPE_SIGNATURE, then this AcroFormField is an instance of AcroSignatureField
    - If the return value is FIELD_TYPE_OTHER, then this AcroFormField has no specific concrete implementation. This case is reserved for form fields with new type indicators that may be introduced by Adobe in the future.
    Specified by:
    
    getType in interface AcroFormField
  - hasValueChanged
```
public boolean hasValueChanged()
```
    Description copied from interface: AcroFormField
    
    Returns true only if this field's value has been changed since being loaded from the PDF document.
    
    Specified by:
    
    hasValueChanged in interface AcroFormField
  - getUIName
```
public java.lang.String getUIName()
```
    Description copied from interface: AcroFormField
    
    Returns the user-friendly name of this field, as specified in the /TU entry in this field's PDF dictionary. This function can return null if no user-friendly field name is defined.
    
    Specified by:
    
    getUIName in interface AcroFormField
    
    Specified by:
    
    getUIName in interface FormField
  - getValue
```
public java.lang.Object getValue()
```
    Description copied from interface: AcroFormField
    
    Returns the value of this field, as specified in the /V entry in this field's PDF dictionary. The type of the returned object depends upon the type of this field.
    
    Specified by:
    
    getValue in interface AcroFormField
    
    Specified by:
    
    getValue in interface FormField

Class AcroChoiceField

Field Summary

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

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CHOICE_TYPE_COMBO

CHOICE_TYPE_LIST

callback

Method Detail

setValue

setValue

canChangeValue

getDisplayValue

getExportValue

getOptions

isEditable

getWidgetType

allowsMultipleChoices

isReadOnly

getDefaultValue

getFullName

getLocalName

getMappingName

getName

getType

hasValueChanged

getUIName

getValue