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

All Implemented Interfaces:

DocumentLocation, AcroFormField, FormField, Bounded

Direct Known Subclasses:

AcroCheckboxField, AcroRadioButtonGroupField
```
public class AcroButtonField
extends 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:
- Pushbuttons, which return BUTTON_TYPE_PUSHBUTTON from getButtonType(). These fields retain no value when an interactive form is saved, and can typically be safely ignored when extracting form data.
- Checkboxes, which return BUTTON_TYPE_CHECKBOX from getButtonType() and are represented by instances of AcroCheckboxField.
- Radio buttons, which return BUTTON_TYPE_RADIO_GROUP from getButtonType() and are represented by instances of AcroRadioButtonGroupField.
Values retained by button fields, available via 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 getExportValue(); all of a button's potential export values are available as a List of Strings via 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 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).
Version:

©2004-2024 Snowtide

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`BUTTON_TYPE_CHECKBOX`	Code returned by `getButtonType()` when a `AcroButtonField` represents a checkbox.
`static int`	`BUTTON_TYPE_PUSHBUTTON`	Code returned by `getButtonType()` when a `AcroButtonField` represents a pushbutton.
`static int`	`BUTTON_TYPE_RADIO_GROUP`	Code returned by `getButtonType()` when a `AcroButtonField` represents a group of radio buttons.
`static String`	`DEFAULT_UNSELECTED_VALUE`	This String ("/Off") is the typical value associated with the unselected appearance for both checkboxes and radio buttons.

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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Region`	`bounds()`
`boolean`	`canChangeValue()`	This function returns true only if this form field is of a subtype that supports setting its value.
`int`	`getButtonType()`	Returns an indicator of what type of button this field object represents.
`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.
`String`	`getExportValue()`	Returns the export value set on this button field.
`List`	`getExportValues()`	Returns a `List` of the possible export values of this button field, as dictated by the field dictionary's /Opt entry.
`String`	`getFullName()`	Returns the fully-qualified name of this field, which should be unique within a PDF document form.
`String`	`getLocalName()`	Returns the local name of the field, as specified in the /T entry in this field's PDF dictionary.
`String`	`getMappingName()`	Returns the 'mapping name' of this field, as specified in the /TM entry in this field's PDF dictionary.
`String`	`getName()`	Returns the canonical name of this field.
`Object`	`getType()`	Returns the type of field, as specified in the /FT entry in this field's PDF dictionary.
`String`	`getUIName()`	Returns the user-friendly name of this field, as specified in the /TU entry in this field's PDF dictionary.
`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.
`boolean`	`hasValueChanged()`	Returns true only if this field's value has been changed since being loaded from the PDF document.
`boolean`	`isReadOnly()`	Returns true only if this field is designated as read-only.
`int`	`pageNumber()`	This page number is 0-indexed, and may be used to retrieve a `Page` object representing the page's content using the `Document#getPage(int)` function.
`boolean`	`setValue(String arg0)`	Sets the value of this form field.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_UNSELECTED_VALUE
```
public static final String DEFAULT_UNSELECTED_VALUE
```
    This String ("/Off") is the typical value associated with the unselected appearance for both checkboxes and radio buttons.
    
    See Also:
    
    Constant Field Values
  - BUTTON_TYPE_PUSHBUTTON
```
public static final int BUTTON_TYPE_PUSHBUTTON
```
    Code returned by getButtonType() when a AcroButtonField represents a pushbutton. Such fields rarely retain any value.
    
    See Also:
    
    Constant Field Values
  - BUTTON_TYPE_CHECKBOX
```
public static final int BUTTON_TYPE_CHECKBOX
```
    Code returned by getButtonType() when a AcroButtonField represents a checkbox.
    
    See Also:
    
    Constant Field Values
  - BUTTON_TYPE_RADIO_GROUP
```
public static final int BUTTON_TYPE_RADIO_GROUP
```
    Code returned by getButtonType() when a AcroButtonField represents a group of radio buttons.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getExportValues
```
public 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.
  - getExportValue
```
public 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.
  - getButtonType
```
public int getButtonType()
```
    Returns an indicator of what type of button this field object represents. Will always be one of BUTTON_TYPE_PUSHBUTTON, BUTTON_TYPE_CHECKBOX, or BUTTON_TYPE_RADIO_GROUP.
  - getValue
```
public 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. See this class' main documentation for a detailed explanation of the implications of certain standard base values.
    
    Specified by:
    
    getValue in interface AcroFormField
    
    Specified by:
    
    getValue in interface FormField
  - bounds
```
public Region bounds()
```
    Specified by:
    
    bounds in interface Bounded
  - pageNumber
```
public int pageNumber()
```
    Description copied from interface: DocumentLocation
    
    This page number is 0-indexed, and may be used to retrieve a Page object representing the page's content using the Document.getPage(int) function.
    If a page number is not available for some reason, then this method will return -1.
    
    Specified by:
    
    pageNumber in interface DocumentLocation
  - 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. PDFxStream 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 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 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 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 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 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 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
  - setValue
```
public boolean setValue(String arg0)
                 throws UnsupportedOperationException
```
    Description copied from interface: AcroFormField
    
    Sets the value of this form field. Each AcroFormField implementation may specify additional varieties of setValue() to support unique functionality (such as holding multiple values). For any form field instance, this function will throw an UnsupportedOperationException if it does not support updates; such instances will return false from AcroFormField.canChangeValue(). This function will return true if the form field's value changes as a result of calling this function (i.e. the given value is different from the current value of the form field).
    
    Either AcroForm.writeUpdatedDocument(java.io.File) or AcroForm.writeUpdatedDocument(java.io.OutputStream) must be called after setting any form field values in order to persist such changes to a PDF document.
    
    Specified by:
    
    setValue in interface AcroFormField
    
    Throws:
    
    UnsupportedOperationException - if an AcroFormField implementation does not support updates.
  - 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
  - canChangeValue
```
public boolean canChangeValue()
```
    Description copied from interface: AcroFormField
    
    This function returns true only if this form field is of a subtype that supports setting its value. This includes checkboxes, radio button groups, text fields, and choice fields (lists and dropdown controls).
    
    Specified by:
    
    canChangeValue in interface AcroFormField
  - getUIName
```
public 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

Class AcroButtonField

Field Summary

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

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_UNSELECTED_VALUE

BUTTON_TYPE_PUSHBUTTON

BUTTON_TYPE_CHECKBOX

BUTTON_TYPE_RADIO_GROUP

Method Detail

getExportValues

getExportValue

getButtonType

getValue

bounds

pageNumber

isReadOnly

getDefaultValue

getFullName

getLocalName

getMappingName

getName

getType

setValue

hasValueChanged

canChangeValue

getUIName