org.faceless.pdf2
Class FormCheckbox

java.lang.Object
  extended byorg.faceless.pdf2.PDFObject
      extended byorg.faceless.pdf2.PDFMap
          extended byorg.faceless.pdf2.FormElement
              extended byorg.faceless.pdf2.FormRadioBox
                  extended byorg.faceless.pdf2.FormCheckbox
All Implemented Interfaces:
Cloneable

public final class FormCheckbox
extends org.faceless.pdf2.FormRadioBox

A type of form element representing a Check Box, which can be either "checked" or "cleared" (on or off), in the same way as the HTML "checkbox" input type. In PDF, Checkboxes are almost identical to Radio Buttons - the only difference is that radio buttons require at least one annotation to be selected, whereas checkboxes don't.

Here's an example showing how to add a set of checkboxes to the form. Each one of these boxes may be turned on or off seperately.

   FormCheckbox check1 = new FormCheckbox(page, 100,100,110,110);
   form.addElement("PowerSteering", check1);
   FormCheckbox check2 = new FormCheckbox(page, 100,120,110,130);
   form.addElement("ElectricWindows", check2);
   FormCheckbox check3 = new FormCheckbox(page, 100,140,110,150);
   form.addElement("AirConditioning", check3);
 

and here's how to determine which of those values is checked

   Form form = pdf.getForm();
   FormCheckbox check;
   check = (FormCheckbox)form.getElement("PowerSteering");
   boolean powersteering = check.getValue()!=null;
   check = (FormCheckbox)form.getElement("ElectricWindows");
   boolean electricwindows = check.getValue()!=null;
   etc.
 
Multiple checkboxes with the same name can be created - these will function like radio buttons except for the fact that none of the boxes has to be set.

Since:
1.1.23

Constructor Summary
FormCheckbox()
          Create a new FormCheckbox element.
FormCheckbox(PDFPage page, float x1, float y1, float x2, float y2)
          Create a new FormCheckbox with a single annotation at the specified position.
 
Method Summary
 WidgetAnnotation addAnnotation(String value, PDFPage page, float x1, float y1, float x2, float y2)
          Add an annotation to the Checkbox or RadioButton.
 String getDefaultValue()
          Return the default value of this field, or null if no default value exists.
 Map getOptions()
          Return a read-only Map containing the values (annotations) that can be selected in this RadioButton or Checkbox.
 String getValue()
          Get the value of this field.
 void setDefaultValue(String value)
          Set the default value for this field.
 void setValue(String value)
          Mark the specified annotation for the Checkbox/RadioButton as selected, and unselect any others.
 
Methods inherited from class org.faceless.pdf2.FormElement
equals, flatten, getAction, getAnnotation, getAnnotations, getDescription, getForm, isReadOnly, isRequired, isSubmitted, setAction, setDescription, setReadOnly, setRequired, setSubmitted, toString
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FormCheckbox

public FormCheckbox()
Create a new FormCheckbox element. With this constructor any annotations must be positioned explicitly by calling the FormRadioBox.addAnnotation(java.lang.String, org.faceless.pdf2.PDFPage, float, float, float, float) method

Since:
1.1.26

FormCheckbox

public FormCheckbox(PDFPage page,
                    float x1,
                    float y1,
                    float x2,
                    float y2)
Create a new FormCheckbox with a single annotation at the specified position. The annotation has the value of "Yes" when selected. Equivalent to calling:
  FormChecbox box = new FormCheckbox();
  box.addAnnotation("Yes", page, x1, y1, x2, y2);
 

Parameters:
page - the page to place the annotation on
x1 - the left-most X co-ordinate of the annotation
y1 - the top-most Y co-ordinate of the annotation
x2 - the right-most X co-ordinate of the annotation
y2 - the bottom-most Y co-ordinate of the annotation
Method Detail

addAnnotation

public WidgetAnnotation addAnnotation(String value,
                                      PDFPage page,
                                      float x1,
                                      float y1,
                                      float x2,
                                      float y2)
Add an annotation to the Checkbox or RadioButton.

Parameters:
value - the value of the annotation - this will be the value returned by FormRadioBox.getValue() if this annotation is selected. Note that "Off" is not allowed as an annotation name.
page - the page to place the annotation on
x1 - the left-most X co-ordinate of the annotation
y1 - the top-most Y co-ordinate of the annotation
x2 - the right-most X co-ordinate of the annotation
y2 - the bottom-most Y co-ordinate of the annotation

setValue

public void setValue(String value)
Mark the specified annotation for the Checkbox/RadioButton as selected, and unselect any others. If an annotation with the specified value does not exist, throw an IllegalArgumentException

Parameters:
value - the value of the annotation to select, or null to turn them all off
Throws:
IllegalArgumentException - if no such annotation exists

setDefaultValue

public void setDefaultValue(String value)
Set the default value for this field. Fields revert to their default value when the PDFAction.formReset() action is invoked.

Parameters:
value - the value of the annotation to select, or null to turn them all off
Throws:
IllegalArgumentException - if no such annotation exists

getValue

public String getValue()
Get the value of this field. This will be the value of the selected RadioButton/Checkbox annotation, or null if no annotation is selected.

Specified by:
getValue in class FormElement
Returns:
the value of the selected annotation, or null if none is selected

getDefaultValue

public String getDefaultValue()
Return the default value of this field, or null if no default value exists.

Returns:
the default value of this field, or null if none is specified

getOptions

public Map getOptions()
Return a read-only Map containing the values (annotations) that can be selected in this RadioButton or Checkbox. As each annotation's value can be checked by iterating through the list returned from FormElement.getAnnotations(), this method is not strictly necessary, but it's a little more convenient and intuitive so we've left it in.

Since:
1.1.26 for RadioButtons, 2.0 for Checkboxes


Copyright © 2001-2004 Big Faceless Organization