com.snowtide.pdf.forms
Class AcroCheckboxField

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

All Implemented Interfaces:

AcroFormField, FormField

public class AcroCheckboxField
extends AcroButtonField

Instances of this class represent individual checkboxes in an interactive forms. Refer to AcroButtonField and AcroFormField for overview documentation.

In addition to the standard AcroFormField.setValue(String) function, AcroCheckboxField instances provide a setValue(boolean) function, making it easy to set the state of a checkbox form field without the extra indirection of having to determine what String value needs to be used to set it to the "checked" state.

Since:

v2.1

Version:

©2004-2012 Snowtide Informatics Systems, Inc.

Field Summary

protected com.snowtide.pdf.PDFTextStreamCallback

callback

Fields inherited from class com.snowtide.pdf.forms.AcroButtonField

BUTTON_TYPE_CHECKBOX, BUTTON_TYPE_PUSHBUTTON, BUTTON_TYPE_RADIO_GROUP, DEFAULT_UNSELECTED_VALUE

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

boolean	canChangeValue() This function always returns true.
java.lang.String	getCheckedValue() Returns the value that represents the checked state for this checkbox.
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	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.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.
boolean	hasValueChanged() Returns true only if this field's value has been changed since being loaded from the PDF document.
boolean	isChecked() Returns true only if this checkbox is checked (i.e.
boolean	isReadOnly() Returns true only if this field is designated as read-only.
boolean	setValue(boolean checked) Sets the value of this checkbox field to be checked (true) or unchecked (false).
boolean	setValue(java.lang.String value) Sets the value of this checkbox directly.

Methods inherited from class com.snowtide.pdf.forms.AcroButtonField

getButtonType, getExportValue, getExportValues, getValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

callback

protected final com.snowtide.pdf.PDFTextStreamCallback callback

Method Detail

getCheckedValue

public java.lang.String getCheckedValue()

Returns the value that represents the checked state for this checkbox. (The string "/Off" represents the unchecked state for all checkboxes.) If this is null, then the name of the checked state for this checkbox could not be determined.

setValue

public boolean setValue(boolean checked)

Sets the value of this checkbox field to be checked (true) or unchecked (false). If this function call results in the actual value of the checkbox changing, then true will be returned. False will be returned only if:

• The checkbox field is already in the specified state.
• The name of the checked state for this checkbox could not be determined. This is rare, and can be checked for using getCheckedValue().

isChecked

public boolean isChecked()

Returns true only if this checkbox is checked (i.e. AcroButtonField.getValue().equals(getCheckedValue())).

setValue

public boolean setValue(java.lang.String value)
                 throws java.lang.IllegalArgumentException

Sets the value of this checkbox directly. The provided value must be one of: null (unchecks the checkbox), AcroButtonField.DEFAULT_UNSELECTED_VALUE (unchecks the checkbox), or the checked value for this checkbox (which will check the checkbox). Using the setValue(boolean) function instead of this one is recommended.

If this function call results in the actual value of the checkbox changing, then true will be returned. False will be returned only if the checkbox field already has the specified value.

Specified by:

setValue in interface AcroFormField

Throws:

java.lang.IllegalArgumentException - - if an invalid value is provided as described above.

canChangeValue

public boolean canChangeValue()

This function always returns true.

Specified by:

canChangeValue in interface AcroFormField

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