Class WidgetAnnotation
- java.lang.Object
-
- org.faceless.pdf2.PDFAnnotation
-
- org.faceless.pdf2.WidgetAnnotation
-
- All Implemented Interfaces:
Cloneable
public class WidgetAnnotation extends PDFAnnotation
TheWidgetAnnotation
class represents the type of annotation used to represent the visual contents of aFormElement
on the page.- Since:
- 2.0
-
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected Object
clone()
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 aFormButton
annotation, return the image that is drawn on the button, ornull
if the field is not a button or no image is specified.FormElement
getField()
Return theFormElement
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, ornull
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
putLiteral(String key, String tokens)
Put a literal token sequnce.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)
ForFormButton
annotations, set the image to display on the button.void
setButtonImage(PDFImage image)
ForFormButton
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 #setValuevoid
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, getAssociatedFiles, getAuthor, getColor, getContents, getCreationDate, getDefaultColorSpace, getInReplyTo, getLocale, getMetaData, getModifyDate, getOpacity, getOptionalContentDescriptor, getPage, getPopup, getRectangle, getReplies, getReviews, getSubject, getType, getUniqueID, getUserData, getXMP, hasAppearanceState, isContentLocked, isPositionLocked, isPrintable, isReadOnly, isVisible, putUserData, rebuild, removePropertyChangeListener, setAuthor, setColor, setContents, setCreationDate, setDefaultColorSpace, setInReplyTo, setLocale, setLocked, setMetaData, setModifyDate, setOpacity, setOptionalContentDescriptor, setPage, setPrintable, setReadOnly, setRectangle, setSubject, setUniqueID, setVisible
-
-
-
-
Method Detail
-
getField
public FormElement getField()
Return theFormElement
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 theFormElement.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
).
-
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 thegetValue()
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 callinggetField().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 ifgetField().getValue().equals(getValue())
, but see thesetSelected(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 #setValueSince 2.11, just callssetValue()
. SeegetTextValue()
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, aFormStyle
, and, if appropriate, aRadioButton
orCheckbox
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 theFill Color
,Line Color
,FormStyle
,Radio Button style
orCheck Box style
attributes set. A value ofnull
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 aFont
andfill color
set, although the font size may be 0 to specified "Auto" sized text. It may also have atext alignment
specified, which is used forFormButton
andFormText
annotations. A value ofnull
means the default style for the form will be used.- Since:
- 2.0
-
setButtonImage
public void setButtonImage(PDFImage image)
ForFormButton
annotations, set the image to display on the button. Draws the image to aPDFCanvas
and then callssetButtonImage(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 aFormButton
-
setButtonImage
public void setButtonImage(PDFCanvas image, char scale, boolean anamorphic, double x, double y)
ForFormButton
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 bysetTextStyle(org.faceless.pdf2.PDFStyle)
and the other parameters to this method. Settingimage
tonull
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 anIllegalStateException
being thrown- Parameters:
image
- the image to display on the button, ornull
for no imagescale
- 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 imageanamorphic
- true to ignore the aspect ratio of the image when scaling itx
- 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 righty
- 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 aFormButton
annotation, return the image that is drawn on the button, ornull
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
orEvent.FORMAT
.- Overrides:
setAction
in classPDFAnnotation
- Parameters:
event
- the event the action applies toaction
- the action you wish to occur, ornull
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 theFormElement.getAnnotations()
method.- Overrides:
getAction
in classPDFAnnotation
- Parameters:
event
- the event you want the action for - one of the events listed insetAction(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 aConcurrentModificationException
if you wereiterating
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 classPDFAnnotation
- 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 onFormText
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()
-
putLiteral
public void putLiteral(String key, String tokens)
Put a literal token sequnce. For debugging- Parameters:
key
- the keytokens
- the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.
-
-