Package org.faceless.pdf2

Class WidgetAnnotation

  • All Implemented Interfaces:
    java.lang.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 Detail

      • getField

        public FormElement getField()
        Return the FormElement that this annotation represents on the page.
        Since:
        2.0

      • getValue

        public java.lang.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.

        Note that a value of null is still possible for RadioButtons if they're incorrectly constructed. In particular, the construction required by PDF/A-1 mandates that this is the case (see OutputProfile.Feature.PushButtonAppearanceIsStream).

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

      • getTextValue

        @Deprecated
public java.lang.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.

      • 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​(java.lang.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

      • 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​(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

      • setReplacementImage

        public boolean setReplacementImage​(PDFCanvas image,
                                   java.lang.String state)

        Set a "replacement image" to completely override the appearance of the widget with a custom PDFCanvas. This only applies to FormButton, FormCheckbox and FormRadioButton fields, and it may not be respected by a PDF Viewer. The canvas should be the same size as the Widget rectangle, otherwise it will be stretched to fit.

        For FormButton fields, the "state" parameter may be normal, down or hover, and the normal image must be set otherwise the default field styling will be used.

        For FormRadioButton and FormCheckbox fields, the "state" parameter may be normal, selected, down hover selected-down or selected-hover, and at least one of the normal or selected images must must be set otherwise the default field styling will be used.

        "down" images are used when the mouse button is depressed on the field, and "hover" images when the mouse rolls over the field. Neither of these are allowed in PDF/A files (they will be silently ignored). Support for "down" and "hover" images is very mixed in PDF viewers: at best they will be ignored, and while they are all supported in Acrobat, at the time of writing there area bugs which can cause these images to sometimes get "stuck". Use with caution.

        Parameters:
        image - the replacement canvas, or null to remove the replacement
        state - the state, as described above
        Returns:
        true if the state is a valid state for this field type
        Since:
        2.28.5

      • getReplacementImage

        public PDFCanvas getReplacementImage​(java.lang.String state)
        Return the specified replacement appearance, as set by #setReplacementAppearance
        Parameters:
        state - the state
        Returns:
        the appearance, or null if it's unset or the state does not apply
        Since:
        2.28.5

      • 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)

      • 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<PDFAnnotation> l = page.getAnnotations();
 while (!l.isEmpty()) {
   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 java.lang.String toString()

      • putLiteral

        public void putLiteral​(java.lang.String key,
                       java.lang.String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.

      • clone

        protected java.lang.Object clone()
        Overrides:
        clone in class java.lang.Object