org.faceless.pdf2

## Class WidgetAnnotation

- java.lang.Object
- - org.faceless.pdf2.PDFAnnotation
  - - org.faceless.pdf2.WidgetAnnotation

- All Implemented Interfaces:
    Cloneable

      public class WidgetAnnotation
      extends PDFAnnotation

  The `WidgetAnnotation` class represents the type of annotation used to represent the visual contents of a `FormElement` on the page.
  Since:
    2.0

- - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `flatten()` Stamp the visible appearance of this annotation permanently onto its page, and remove the annotation from the page.
    `PDFAction` | `getAction(Event event)` Return the action that occurs when the specified event happens to this annotation.
    `PDFStyle` | `getBackgroundStyle()` Get the background style for this annotation.
    `PDFCanvas` | `getButtonImage()` For a `FormButton` annotation, return the image that is drawn on the button, or `null` if the field is not a button or no image is specified.
    `FormElement` | `getField()` Return the `FormElement` that this annotation represents on the page.
    `PDFStyle` | `getTextStyle()` Get the text style for this widget.
    `String` | `getTextValue()` Deprecated. since 2.11 just call getValue() instead.
    `String` | `getValue()` Get the value of this Widget annotation - the value of the box for RadioButton and Checkbox annotations, the text on the Button for Button annotations, or `null` otherwise.
    `boolean` | `isOverflowing()` Return true if the Widget is not big enough to hold the value of the field without overflowing (based on the layout algorithm, rather then the visual appearance of the text).
    `boolean` | `isSelected()` For Radiobuttons and Checkboxes, this method returns true if this specific Widget is selected.
    `void` | `setAction(Event event, PDFAction action)` Set an action to occur when the specified event happens to this annotation.
    `void` | `setBackgroundStyle(PDFStyle style)` Set the background style for this annotation.
    `void` | `setButtonImage(PDFCanvas image, char scale, boolean anamorphic, double x, double y)` For `FormButton` annotations, set the image to display on the button.
    `void` | `setButtonImage(PDFImage image)` For `FormButton` annotations, set the image to display on the button.
    `void` | `setSelected(boolean selected)` For Radiobuttons and Checkboxes, this method can be called to set the specified Widget to true.
    `void` | `setTextStyle(PDFStyle style)` Set the text style for this annotation.
    `void` | `setTextValue(String value)` Deprecated. since 2.11 just call #setValue
    `void` | `setValue(String value)` Set the value of this annotation for for PushButton, RadioButton and Checkbox annotations.
    `String` | `toString()`

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

      `addPropertyChangeListener, addReview, getAuthor, getColor, getContents, getCreationDate, getInReplyTo, getMetaData, getModifyDate, getOpacity, getPage, getPopup, getRectangle, getReplies, getReviews, getSubject, getType, getUniqueID, hasAppearanceState, isContentLocked, isPositionLocked, isPrintable, isReadOnly, isVisible, rebuild, removePropertyChangeListener, setAuthor, setColor, setContents, setCreationDate, setInReplyTo, setLocked, setMetaData, setModifyDate, setOpacity, setPage, setPrintable, setReadOnly, setRectangle, setSubject, setUniqueID, setVisible`

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

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

- - ### Method Detail

    - #### getField

          public FormElement getField()

      Return the `FormElement` that this annotation represents on the page.
      Since:
        2.0

    - #### getValue

          public String getValue()

      Get the value of this Widget annotation - the value of the box for RadioButton and Checkbox annotations, the text on the Button for Button annotations, or `null` otherwise.

      For example, a RadioButton used to select a type of credit card may have three annotations with the values "Visa", "MasterCard" and "Amex". For fields other than Push Buttons, RadioButtons and Checkboxes this method will return `null` - in this case the value of the field can be read by calling the `FormElement.getValue()` method instead.

      Since:
        2.0
      See Also:
        `setValue(java.lang.String)`, `FormRadioButton.setValue(java.lang.String)`, `FormCheckbox.setValue(java.lang.String)`

    - #### getTextValue

          @Deprecated
          public String getTextValue()

      Deprecated. since 2.11 just call getValue() instead.

      Since 2.11 just returns the value of `getValue()`, so just call that method instead.

      From 2.6.3 to 2.10.6, this method returned the value from the "Opt" array of the parent field corresponding to this field. Earlier versions of the PDF specification described this as a way of storing a "key" and "export value" for the field, but in practice this is not how it's used, and when an export value is present the key is simply the numeric index of the field. Release 2.10.6 removed the issues this caused, and widgets are now always referred to by their export value.

    - #### setValue

          public void setValue(String value)

      Set the value of this annotation for for PushButton, RadioButton and Checkbox annotations. For other types of annotation this method has no effect. See the `getValue()` method for a discussion of annotation values.
      Since:
        2.0
      See Also:
        `getValue()`, `FormRadioButton.setValue(java.lang.String)`, `FormCheckbox.setValue(java.lang.String)`

    - #### setSelected

          public void setSelected(boolean selected)

      For Radiobuttons and Checkboxes, this method can be called to set the specified Widget to true. Generally this is identical to calling `getField().setValue(getValue())` - this method is only required when a field has multiple items with the same value. For any other type of field this method throws an IllegalStateException
      Since:
        2.10.6

    - #### isSelected

          public boolean isSelected()

      For Radiobuttons and Checkboxes, this method returns true if this specific Widget is selected. This is generally the same as checking if `getField().getValue().equals(getValue())`, but see the `setSelected(boolean)` method for more detail. For other fields this method always returns false.
      Since:
        2.10.6

    - #### setTextValue

          @Deprecated
          public void setTextValue(String value)

      Deprecated. since 2.11 just call #setValue
      Since 2.11, just calls `setValue()`. See `getTextValue()` for a description of this change.
      Since:
        2.6.3

    - #### getBackgroundStyle

          public PDFStyle getBackgroundStyle()

      Get the background style for this annotation. The style returned will typically have a fill or line color, a `FormStyle`, and, if appropriate, a `RadioButton` or `Checkbox` style.
      Since:
        2.0

    - #### getTextStyle

          public PDFStyle getTextStyle()

      Get the text style for this widget. This will typically have a font and fill color set, but nothing else.
      Since:
        2.0

    - #### setBackgroundStyle

          public void setBackgroundStyle(PDFStyle style)

      Set the background style for this annotation. Typically the style will have one or more of the `Fill Color`, `Line Color`, `FormStyle`, `Radio Button style` or `Check Box style` attributes set. A value of `null` means the default style for the form will be used.
      Since:
        2.0

    - #### setTextStyle

          public void setTextStyle(PDFStyle style)

      Set the text style for this annotation. The style must have a `Font` and `fill color` set, although the font size may be 0 to specified "Auto" sized text. It may also have a `text alignment` specified, which is used for `FormButton` and `FormText` annotations. A value of `null` means the default style for the form will be used.
      Since:
        2.0

    - #### setButtonImage

          public void setButtonImage(PDFImage image)

      For `FormButton` annotations, set the image to display on the button. Draws the image to a `PDFCanvas` and then calls `setButtonImage(image, 'A', false, 0.5, 0.5)`
      Parameters:
        `image` - the image to display on the button
      Throws:
        `IllegalStateException` - if this method is called on an annotation for anything other than a `FormButton`

    - #### setButtonImage

          public void setButtonImage(PDFCanvas image,
                                     char scale,
                                     boolean anamorphic,
                                     double x,
                                     double y)

      For `FormButton` annotations, set the image to display on the button. Where the image is positioned in relation to the text depends on the value of the text-alignment in the style specified by `setTextStyle(org.faceless.pdf2.PDFStyle)` and the other parameters to this method. Setting `image` to `null` removes any current image from the button annotation. Calling this method on an annotation for any type of field other than a Button will result in an `IllegalStateException` being thrown
      Parameters:
        `image` - the image to display on the button, or `null` for no image
        `scale` - one of 'A' to always scale the image (the default), 'B' to only scale the image down to fit the annotation, 'S' to only scale the image up to fit the annotation or 'N' to never scale the image
        `anamorphic` - true to ignore the aspect ratio of the image when scaling it
        `x` - where to horizontally position the image in the space allowed to it - 0 for left, 0.5 to center it and 1 to place it to the right
        `y` - where to vertically position the image in the space allowed to it - 0 for top, 0.5 to center it and 1 to place it to the bottom
      Since:
        2.10

    - #### getButtonImage

          public PDFCanvas getButtonImage()

      For a `FormButton` annotation, return the image that is drawn on the button, or `null` if the field is not a button or no image is specified.
      Since:
        2.10 (this method has existed since 2.0, but it returned a `PDFImage`)

    - #### setAction

          public void setAction(Event event,
                                PDFAction action)

      Set an action to occur when the specified event happens to this annotation. These event actions are only used for annotations created by form elements - those returned from `FormElement.getAnnotations()`.

      The event can be one of `Event.MOUSEOVER`, `Event.MOUSEOUT`, `Event.MOUSEDOWN`, `Event.MOUSEUP`, `Event.FOCUS`, `Event.BLUR`, `Event.CHANGE`, `Event.KEYPRESS` or `Event.FORMAT`.

      Parameters:
        `event` - the event the action applies to
        `action` - the action you wish to occur, or `null` to remove the action
      Since:
        2.0
      See Also:
        `FormElement.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction)`

    - #### getAction

          public PDFAction getAction(Event event)

      Return the action that occurs when the specified event happens to this annotation. This is only used with annotations returned from form fields via the `FormElement.getAnnotations()` method.
      Parameters:
        `event` - the event you want the action for - one of the events listed in `setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction)`
      Returns:
        the action for that event, or `null` if no action is specified
      Since:
        2.0
      See Also:
        `FormElement`

    - #### flatten

          public void flatten()

      Description copied from class: `PDFAnnotation`

      Stamp the visible appearance of this annotation permanently onto its page, and remove the annotation from the page. The annotation object should be discarded afterwards.

      Note that this method removes this PDFAnnotation from the page list (and if this annotation is a Widget, from the `FormElement.getAnnotations()` FormElement Annotations list} as well), which could result in a `ConcurrentModificationException` if you were `iterating` over the page's annotations. To flatten all the annotations on a page we'd recommend something like this:

           List l = page.getAnnotations();
           while (l.size() > 0) {
             ((PDFAnnotation)l.get(l.size() - 1)).flatten();
           }

      Overrides:
        `flatten` in class `PDFAnnotation`
      See Also:
        `FormElement.flatten()`, `Form.flatten()`

    - #### isOverflowing

          public boolean isOverflowing()

      Return true if the Widget is not big enough to hold the value of the field without overflowing (based on the layout algorithm, rather then the visual appearance of the text). This only applies to widgets on `FormText` fields, and for some types of field (eg. those formatted by JavaScript or XFA rules) it cannot reliably be determined - in this case this method returns false.
      Returns:
        true if the Widget has been identified as too small to fully display the field value
      Since:
        2.11.22

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization