public class AcroButtonField
extends java.lang.Object
Represents a button form field in an interactive AcroForm.
This is the superclass of AcroCheckboxField and AcroRadioButtonGroupField.
There are three possible types of button fields:
AcroButtonField.BUTTON_TYPE_PUSHBUTTON from
AcroButtonField.getButtonType(). These fields retain no value when an interactive form is saved,
and can typically be safely ignored when extracting form data.AcroButtonField.BUTTON_TYPE_CHECKBOX from
AcroButtonField.getButtonType() and are represented by instances of AcroCheckboxField.AcroButtonField.BUTTON_TYPE_RADIO_GROUP from
AcroButtonField.getButtonType() and are represented by instances of AcroRadioButtonGroupField.
Values retained by button fields, available via AcroButtonField.getValue(),
typically have no semantic value related to the context of the form.
Intead, they are simple codes used by a PDF viewer to select how to display the field's widget.
Developers should therefore not expect button field values to be meaningful or useful
within an end-user context. User-friendly values are sometimes specified by button fields; see
the section on export values below for details.
If a checkbox is unselected (i.e. visually unchecked), its value will be null, or the String '/Off'. Common base values for checked checkboxes include '/On' and '/Yes'.
Radio Button Groups
AcroRadioButtonGroupField instances represent groups of radio button widgets.
The value returned by such fields is therefore the
one associated with the radio button widget that is selected -- all other
options in the group are necessarily unselected.
A typical example would be a radio button group indicating payment options (Mastercard, Visa, AMEX, etc).
There would be one widget shown in the PDF form for each option; PDFxStream would represent
the group of widgets as a single AcroRadioButtonGroupField instance. That form field instance
would retain a value indicating the selected widget (one of the Strings '/Mastercard', '/Visa', or '/AMEX',
perhaps), or the String '/Off', or null (both of which would indicate that none of the widgets in the radio
button group are selected).
Export Values
Buttons can specify export values as well as base values. A button's retained export value is available via
AcroButtonField.getExportValue(); all of a button's potential export values are available as a List
of Strings via AcroButtonField.getExportValues(). PDFxStream automatically determines a button's export value,
so there is no need for applications to attempt to derive a button's export value using its retained value.
When export values are used, a button's potential retained values are just codes. Continuing with the
payment options example from above, a radio button group might specify a set of possible export values
like [ "Mastercard", "Visa", "AMEX" ]. It might therefore retain a base value of '/1' or '/Visa' as a code indicating
that the "Visa" widget was selected; the export value reported by AcroButtonField.getExportValue() would return
the String "Visa" in this example.
Note that checkbox fields can also have export values, although they are restricted to having only two
potential export values (one for the selected state, one for the unselected state).
| Modifier and Type | Field and Description |
|---|---|
static int |
BUTTON_TYPE_CHECKBOX
Code returned by
AcroButtonField.getButtonType() when a AcroButtonField represents
a checkbox. |
static int |
BUTTON_TYPE_PUSHBUTTON
Code returned by
AcroButtonField.getButtonType() when a AcroButtonField represents
a pushbutton. |
static int |
BUTTON_TYPE_RADIO_GROUP
Code returned by
AcroButtonField.getButtonType() when a AcroButtonField represents
a group of radio buttons. |
static java.lang.String |
DEFAULT_UNSELECTED_VALUE
This String ("/Off") is the typical value associated with the unselected appearance for both
checkboxes and radio buttons.
|
FIELD_TYPE_BUTTON, FIELD_TYPE_CHOICE, FIELD_TYPE_OTHER, FIELD_TYPE_SIGNATURE, FIELD_TYPE_TEXT| Modifier and Type | Method and Description |
|---|---|
int |
getButtonType()
Returns an indicator of what type of button this field object represents.
|
java.lang.String |
getExportValue()
Returns the export value set on this button field.
|
java.util.List |
getExportValues()
Returns a
List of the possible export values of this button field, as dictated by the
field dictionary's /Opt entry. |
java.lang.Object |
getValue()
Returns this button's 'base value', which is actually a code used by a PDF viewer to determine how to draw
a button's widget.
|
canChangeValue, getDefaultValue, getFullName, getLocalName, getMappingName, getType, getUIName, hasValueChanged, isReadOnly, setValuepageNumberpublic static final java.lang.String DEFAULT_UNSELECTED_VALUE
public static final int BUTTON_TYPE_PUSHBUTTON
AcroButtonField.getButtonType() when a AcroButtonField represents
a pushbutton. Such fields rarely retain any value.public static final int BUTTON_TYPE_CHECKBOX
AcroButtonField.getButtonType() when a AcroButtonField represents
a checkbox.public static final int BUTTON_TYPE_RADIO_GROUP
AcroButtonField.getButtonType() when a AcroButtonField represents
a group of radio buttons.public java.util.List getExportValues()
Returns a List of the possible export values of this button field, as dictated by the
field dictionary's /Opt entry. Each member of the returned list is a String.
If no export values are defined by this button field, then this function will return null.
This function is irrelevant for pushbutton fields.
NOTE: In some cases, export values may be defined, but misleading and/or not useful.
For example, some checkboxes define two identical export values (one for when the checkbox is checked, the
other for when it is not). In such circumstances, it is therefore better to rely upon the
base value provided by the button field, which is guaranteed to be
distinct for each button state.
public java.lang.String getExportValue()
Returns the export value set on this button field. This is distinct from the field's
base value, in that the export value is typically designed to
either integrate smoothly with external tools, systems, etc., or to be user friendly.
This function is irrelevant for pushbutton fields.
If this button field does not specify any export values, then this
function will return null.
NOTE: In some cases, export values may be defined, but misleading and/or not useful.
For example, some checkboxes define two identical export values (one for when the checkbox is checked, the
other for when it is not). In such circumstances, it is therefore better to rely upon the
base value provided by the button field, which is guaranteed to be
distinct for each button state.
public int getButtonType()
AcroButtonField.BUTTON_TYPE_PUSHBUTTON, AcroButtonField.BUTTON_TYPE_CHECKBOX, or AcroButtonField.BUTTON_TYPE_RADIO_GROUP.public java.lang.Object getValue()
getValue in interface AcroFormFieldgetValue in interface FormField