org.faceless.pdf2

## Class FormCheckbox

- java.lang.Object
- - org.faceless.pdf2.FormElement
  - - org.faceless.pdf2.FormCheckbox

- All Implemented Interfaces:
    Cloneable

      public final class FormCheckbox
      extends FormElement

  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 separately.

         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

    Constructors
    Constructor and Description
    `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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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<String,WidgetAnnotation>` | `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` | `rebuild()` Cause the annotation list to be rebuilt.
    `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.
    `String` | `toString()`

    - ### Methods inherited from class org.faceless.pdf2.FormElement

      `addPropertyChangeListener, duplicate, flatten, getAction, getAnnotation, getAnnotations, getDescription, getForm, isReadOnly, isRequired, isSubmitted, removePropertyChangeListener, setAction, setDescription, setReadOnly, setRequired, setSubmitted`

    - ### Methods inherited from class java.lang.Object

      `equals, 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 `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:

            FormCheckbox 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

    - #### setValue

          public void setValue(String value)

      Mark the specified annotation for the Checkbox/RadioButton as selected, and unselect any others. The specified value must be the the `value` of one of this field's `WidgetAnnotation` objects, otherwise an an `IllegalArgumentException` is thrown.
      Parameters:
        `value` - the value of the annotation to select, or `null` to turn them all off

    - #### 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. See `setValue(java.lang.String, java.lang.String)` for a discussion of which values are valid.
      Parameters:
        `value` - the value of the annotation to select, or `null` to turn them all off

    - #### 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.
      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<String,WidgetAnnotation> 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.

    - #### rebuild

          public void rebuild()

      Description copied from class: `FormElement`
      Cause the annotation list to be rebuilt. Unless you're rendering the annotation using the viewer, it's not necessary to call this method.

    - #### 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 `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

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization