org.faceless.pdf2

## Class FormElement

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

- All Implemented Interfaces:
    Cloneable
  Direct Known Subclasses:
    FormBarCode, FormButton, FormCheckbox, FormChoice, FormRadioButton, FormSignature, FormText

      public abstract class FormElement
      extends Object

  The `FormElement` class is the baseclass for all elements which may be added to a `Form`.
  Since:
    1.1.13

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPropertyChangeListener(PropertyChangeListener l)` Add a PropertyChangeListener to this FormElement.
    `FormElement` | `duplicate()` Create an exact copy of this FormElement, but with no annotations
    `void` | `flatten()` Flatten the form field so that the contents of it's annotation are permanently stamped on the page.
    `PDFAction` | `getAction(Event event)` Get the action that's performed when the specified event takes place on this field.
    `WidgetAnnotation` | `getAnnotation(int annot)` Return the specified annotation.
    `List<WidgetAnnotation>` | `getAnnotations()` Return a list of all the annotations associated with this form element.
    `String` | `getDescription()` Return the text description of this field if specified, or `null` if no description is supplied.
    `Form` | `getForm()` Return the form this form element belongs to
    `abstract String` | `getValue()` Return the value for this element.
    `boolean` | `isReadOnly()` Get whether the field is read-only or not.
    `boolean` | `isRequired()` Get whether the field is required before the form is submitted.
    `boolean` | `isSubmitted()` Get whether the field is submitted or not.
    `void` | `rebuild()` Cause the annotation list to be rebuilt.
    `void` | `removePropertyChangeListener(PropertyChangeListener l)` Remove a previously added PropertyChangeListener form this FormElement.
    `void` | `setAction(Event event, PDFAction action)` Set the action to perform when the specified event takes place on this field.
    `void` | `setDescription(String s)` Set the text description of this field.
    `void` | `setReadOnly(boolean readonly)` Set whether the field is read-only or not.
    `void` | `setRequired(boolean required)` Set whether the field is required before the form is submitted.
    `void` | `setSubmitted(boolean submit)` Set whether the field is submitted or not.
    `String` | `toString()`

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### duplicate

          public FormElement duplicate()

      Create an exact copy of this FormElement, but with no annotations
      Since:
        2.10.6

    - #### getForm

          public Form getForm()

      Return the form this form element belongs to
      Since:
        2.0

    - #### getAnnotations

          public List<WidgetAnnotation> getAnnotations()

      Return a list of all the annotations associated with this form element. The list contains zero or more `WidgetAnnotation` objects, which may be accessed from this list or via the convenience method `getAnnotation(int)`. The resulting list may have elements removed or reordered, although adding non-widget annotations, null objects or widgets from a different field will result in an Exception.
      Since:
        2.0 (prior to 2.0, this method returned an array of `PDFAnnotation` objects.

    - #### getAnnotation

          public WidgetAnnotation getAnnotation(int annot)

      Return the specified annotation. Identical to `getAnnotations().get(annot)`
      Since:
        2.0

    - #### getValue

          public abstract String getValue()

      Return the value for this element. Not all elements have a value returned by this method - for example, both `FormButton` and `FormSignature` return `null` from this method. See the method contract in each subclass for more detail.
      Since:
        2.0

    - #### getDescription

          public String getDescription()

      Return the text description of this field if specified, or `null` if no description is supplied.
      Since:
        2.0

    - #### setDescription

          public void setDescription(String s)

      Set the text description of this field. Value may be `null` to remove it.
      Since:
        2.0

    - #### setAction

          public void setAction(Event event,
                                PDFAction action)

      Set the action to perform when the specified event takes place on this field. Value events are `Event.KEYPRESS`, `Event.FORMAT`, `Event.CHANGE` and `Event.OTHERCHANGE`, which are the types of event that can take place on a FormElement. You may also want to check `setAction` in the `WidgetAnnotation` class to see events that are triggered on the fields annotation, rather than the field itself.
      Parameters:
        `event` - the event to place the action on
        `action` - the action to invoke when the specified event takes place, or `null` to remove the event.
      Throws:
        `IllegalArgumentException` - if the wrong type of event is set.
      Since:
        2.0
      See Also:
        `WidgetAnnotation.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction)`, `Event`

    - #### getAction

          public PDFAction getAction(Event event)

      Get the action that's performed when the specified event takes place on this field. Possible events are listed in the `setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction)` API docs.
      Returns:
        the action associated with this event on this Form Element, or `null` if no action is specified for the event.
      Since:
        2.0

    - #### setReadOnly

          public void setReadOnly(boolean readonly)

      Set whether the field is read-only or not.
      Parameters:
        `readonly` - whether the field is read-only or not
      Since:
        1.1.23

    - #### isReadOnly

          public boolean isReadOnly()

      Get whether the field is read-only or not.
      Returns:
        true if the field is read-only
      Since:
        1.1.23

    - #### setRequired

          public void setRequired(boolean required)

      Set whether the field is required before the form is submitted. For some fields like pushbuttons, this method has no effect.
      Parameters:
        `required` - whether the field is a required field or not
      Since:
        1.1.23

    - #### isRequired

          public boolean isRequired()

      Get whether the field is required before the form is submitted. For some fields like pushbuttons, this method always returns false.
      Returns:
        true if the field is required on form submission
      Since:
        1.1.23

    - #### setSubmitted

          public void setSubmitted(boolean submit)

      Set whether the field is submitted or not. The default for every element in the form is true.
      Parameters:
        `submit` - whether the element is submitted or not.
      Since:
        1.1.23

    - #### isSubmitted

          public boolean isSubmitted()

      Get whether the field is submitted or not.
      Returns:
        true if the field is submitted, false otherwise
      Since:
        1.1.23

    - #### rebuild

          public void rebuild()

      Cause the annotation list to be rebuilt. Unless you're rendering the annotation using the viewer, it's not necessary to call this method.
      Since:
        2.8

    - #### flatten

          public void flatten()

      Flatten the form field so that the contents of it's annotation are permanently stamped on the page. The field's annotations are removed, but the field is not removed from the form - this must be done manually. Usually it's more convenient to flatten the entire form in one go, by calling the `Form.flatten()` method.
      Since:
        2.0
      See Also:
        `PDFAnnotation.flatten()`, `Form.flatten()`

    - #### addPropertyChangeListener

          public void addPropertyChangeListener(PropertyChangeListener l)

      Add a PropertyChangeListener to this FormElement. Property changes will be fired when aspects of this FormElement are changed.
      Since:
        2.10.4
      See Also:
        `PDFAnnotation.addPropertyChangeListener(java.beans.PropertyChangeListener)`, `PDFPage.addPropertyChangeListener(java.beans.PropertyChangeListener)`

    - #### removePropertyChangeListener

          public void removePropertyChangeListener(PropertyChangeListener l)

      Remove a previously added PropertyChangeListener form this FormElement.
      Since:
        2.10.4
      See Also:
        `removePropertyChangeListener(java.beans.PropertyChangeListener)`

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization