com.itextpdf.forms.fields

Class PdfFormAnnotation

java.lang.Object

com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>

com.itextpdf.forms.fields.AbstractPdfFormField

com.itextpdf.forms.fields.PdfFormAnnotation

public class PdfFormAnnotation
extends AbstractPdfFormField

This class represents a single annotation in form fields hierarchy in an AcroForm.

To be able to be wrapped with this PdfObjectWrapper the PdfObject must be indirect.

Field Summary

Fields

Modifier and Type	Field and Description
protected Color	backgroundColor
protected Color	borderColor
protected float	borderWidth
static int	HIDDEN
static int	HIDDEN_BUT_PRINTABLE
static String	OFF_STATE_VALUE Value which represents "off" state of form field.
static String	ON_STATE_VALUE Value which represents "on" state of form field.
static int	VISIBLE
static int	VISIBLE_BUT_DOES_NOT_PRINT

Fields inherited from class com.itextpdf.forms.fields.AbstractPdfFormField

color, DEFAULT_FONT_SIZE, font, fontSize, MIN_FONT_SIZE, parent, pdfAConformanceLevel, pdfConformanceLevel

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PdfFormAnnotation(PdfDictionary pdfObject) Creates a form field annotation as a wrapper object around a PdfDictionary.
protected	PdfFormAnnotation(PdfWidgetAnnotation widget, PdfDocument pdfDocument) Creates a form field annotation as a wrapper of a PdfWidgetAnnotation.

Method Summary

Modifier and Type	Method and Description
protected void	drawBorder(PdfCanvas canvas, PdfFormXObject xObject, float width, float height) Draws a border using the borderWidth and borderColor of the form field.
protected void	drawCheckBoxAndSaveAppearance(String onStateName) Draw a checkbox and save its appearance.
protected void	drawComboBoxAndSaveAppearance() Draws the appearance of a Combo box form field and saves it into an appearance stream.
protected void	drawListFormFieldAndSaveAppearance() Draws the appearance of a list box form field and saves it into an appearance stream.
protected void	drawPushButtonFieldAndSaveAppearance() Draws the appearance of a push button and saves it into an appearance stream.
protected void	drawRadioButtonAndSaveAppearance(String value) Draws the appearance of a radio button with a specified value and saves it into an appearance stream.
protected void	drawSignatureFormFieldAndSaveAppearance() Draws the appearance of a signature field and saves it into an appearance stream.
protected void	drawTextFormFieldAndSaveAppearance() Draws the appearance of a text form field and saves it into an appearance stream.
String[]	getAppearanceStates() Gets the appearance state names.
Border	getBorder() Get border object specified in the widget annotation dictionary.
float	getBorderWidth() Gets the border width for the field.
PdfString	getDefaultAppearance() Gets default appearance string containing a sequence of valid page-content graphics or text state operators that define such properties as the field's text size and color.
protected Rectangle	getRect(PdfDictionary field) Gets a Rectangle that matches the current size and position of this form field.
int	getRotation() Get rotation property specified in this form annotation.
PdfWidgetAnnotation	getWidget() Gets PdfWidgetAnnotation that this form field refers to.
static PdfFormAnnotation	makeFormAnnotation(PdfObject pdfObject, PdfDocument document) Creates a PdfFormAnnotation object.
boolean	regenerateField() This method regenerates appearance stream of the field.
PdfFormAnnotation	setAction(PdfAction action) Sets the action on widget of this annotation form field.
PdfFormAnnotation	setAppearance(PdfName appearanceType, String appearanceState, PdfStream appearanceStream) Sets an appearance for (the widgets related to) the form field.
PdfFormAnnotation	setBackgroundColor(Color backgroundColor) Basic setter for the backgroundColor property.
PdfFormAnnotation	setBorderColor(Color color) Sets the Border Color.
PdfFormAnnotation	setBorderStyle(PdfDictionary style) Sets the border style for the field.
PdfFormAnnotation	setBorderWidth(float borderWidth) Sets the border width for the field.
PdfFormAnnotation	setCaption(String caption) Basic setter for the push button caption.
PdfFormAnnotation	setCaption(String caption, boolean regenerateField) Basic setter for the push button caption.
PdfFormAnnotation	setCheckBoxAppearanceOnStateName(String onStateName) Sets on state name for the checkbox annotation normal appearance and regenerates widget.
PdfFormAnnotation	setFormFieldElement(IFormField element) This method sets the model element associated with the current annotation and can be useful to take into account when drawing those properties that the annotation does not have.
PdfFormAnnotation	setPage(int pageNum) Specifies on which page the form field's widget must be shown.
PdfFormAnnotation	setRotation(int degRotation) Basic setter for the degRotation property.
PdfFormAnnotation	setVisibility(int visibility) Set the visibility flags of the form field annotation.

Methods inherited from class com.itextpdf.forms.fields.AbstractPdfFormField

disableCurrentFieldRegeneration, disableFieldRegeneration, enableCurrentFieldRegeneration, enableFieldRegeneration, equals, getColor, getDocument, getFieldName, getFont, getFontSize, getParent, getParentField, getPdfAConformanceLevel, getPdfConformanceLevel, getPdfObject, hashCode, isFieldRegenerationEnabled, isTerminalFormField, isWrappedObjectMustBeIndirect, put, release, remove, setColor, setFont, setFontAndSize, setFontSize, setFontSize, setFontSizeAutoScale, setParent

Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper

ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, flush, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setModified, setPdfObject, unsetForbidRelease

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

HIDDEN

public static final int HIDDEN

See Also:

Constant Field Values

VISIBLE_BUT_DOES_NOT_PRINT

public static final int VISIBLE_BUT_DOES_NOT_PRINT

See Also:

Constant Field Values

HIDDEN_BUT_PRINTABLE

public static final int HIDDEN_BUT_PRINTABLE

See Also:

Constant Field Values

VISIBLE

public static final int VISIBLE

See Also:

Constant Field Values

OFF_STATE_VALUE

public static final String OFF_STATE_VALUE

Value which represents "off" state of form field.

See Also:

Constant Field Values

ON_STATE_VALUE

public static final String ON_STATE_VALUE

Value which represents "on" state of form field.

See Also:

Constant Field Values

borderWidth

protected float borderWidth

backgroundColor

protected Color backgroundColor

borderColor

protected Color borderColor

Constructor Detail

PdfFormAnnotation

protected PdfFormAnnotation(PdfWidgetAnnotation widget,
                            PdfDocument pdfDocument)

Creates a form field annotation as a wrapper of a PdfWidgetAnnotation.

Parameters:

widget - The widget which will be a kid of the PdfFormField

pdfDocument - The PdfDocument instance.

PdfFormAnnotation

protected PdfFormAnnotation(PdfDictionary pdfObject)

Creates a form field annotation as a wrapper object around a PdfDictionary. This PdfDictionary must be an indirect object.

Parameters:

pdfObject - the dictionary to be wrapped, must have an indirect reference.

Method Detail

makeFormAnnotation

public static PdfFormAnnotation makeFormAnnotation(PdfObject pdfObject,
                                                   PdfDocument document)

Creates a PdfFormAnnotation object.

Parameters:

pdfObject - assumed to be either a PdfDictionary, or a PdfIndirectReference to a PdfDictionary.

document - the PdfDocument to create the field in.

Returns:

a new PdfFormAnnotation, or null if pdfObject is not a widget annotation.

getWidget

public PdfWidgetAnnotation getWidget()

Gets PdfWidgetAnnotation that this form field refers to.

Returns:

PdfWidgetAnnotation.

getDefaultAppearance

public PdfString getDefaultAppearance()

Gets default appearance string containing a sequence of valid page-content graphics or text state operators that define such properties as the field's text size and color.

Specified by:

getDefaultAppearance in class AbstractPdfFormField

Returns:

the default appearance graphics, as a PdfString.

regenerateField

public boolean regenerateField()

This method regenerates appearance stream of the field. Use it if you changed any field parameters and didn't use setValue method which generates appearance by itself.

Specified by:

regenerateField in class AbstractPdfFormField

Returns:

whether or not the regeneration was successful.

getAppearanceStates

public String[] getAppearanceStates()

Gets the appearance state names.

Specified by:

getAppearanceStates in class AbstractPdfFormField

Returns:

an array of Strings containing the names of the appearance states.

setBackgroundColor

public PdfFormAnnotation setBackgroundColor(Color backgroundColor)

Basic setter for the backgroundColor property. Regenerates the field appearance after setting the new value.

Parameters:

backgroundColor - The new color to be set or null if no background needed.

Returns:

The edited PdfFormAnnotation.

setCaption

public PdfFormAnnotation setCaption(String caption)

Basic setter for the push button caption. Regenerates the field appearance after setting the new caption.

Parameters:

caption - button caption to be set.

Returns:

The edited PdfFormAnnotation.

setCaption

public PdfFormAnnotation setCaption(String caption,
                                    boolean regenerateField)

Basic setter for the push button caption. Regenerates the field appearance after setting the new caption if corresponding parameter is specified.

Parameters:

caption - button caption to be set.

regenerateField - true if field should be regenerated, false otherwise.

Returns:

The edited PdfFormAnnotation.

getRotation

public int getRotation()

Get rotation property specified in this form annotation.

Returns:

int value which represents field's rotation

setRotation

public PdfFormAnnotation setRotation(int degRotation)

Basic setter for the degRotation property. Regenerates the field appearance after setting the new value.

Parameters:

degRotation - The new degRotation to be set

Returns:

The edited PdfFormAnnotation.

setAction

public PdfFormAnnotation setAction(PdfAction action)

Sets the action on widget of this annotation form field.

Parameters:

action - The action.

Returns:

The edited PdfFormAnnotation.

setVisibility

public PdfFormAnnotation setVisibility(int visibility)

Set the visibility flags of the form field annotation. Options are: HIDDEN, HIDDEN_BUT_PRINTABLE, VISIBLE, VISIBLE_BUT_DOES_NOT_PRINT.

Parameters:

visibility - visibility option.

Returns:

The edited PdfFormAnnotation.

getBorderWidth

public float getBorderWidth()

Gets the border width for the field.

Returns:

the current border width.

setBorderWidth

public PdfFormAnnotation setBorderWidth(float borderWidth)

Sets the border width for the field.

Parameters:

borderWidth - The new border width.

Returns:

The edited PdfFormAnnotation.

getBorder

public Border getBorder()

Get border object specified in the widget annotation dictionary.

Returns:

Border specified in the widget annotation dictionary

setBorderStyle

public PdfFormAnnotation setBorderStyle(PdfDictionary style)

Sets the border style for the field.

Parameters:

style - the new border style.

Returns:

The edited PdfFormAnnotation.

setBorderColor

public PdfFormAnnotation setBorderColor(Color color)

Sets the Border Color.

Parameters:

color - the new value for the Border Color.

Returns:

The edited PdfFormAnnotation.

setPage

public PdfFormAnnotation setPage(int pageNum)

Specifies on which page the form field's widget must be shown.

Parameters:

pageNum - the page number.

Returns:

The edited PdfFormAnnotation.

setFormFieldElement

public PdfFormAnnotation setFormFieldElement(IFormField element)

This method sets the model element associated with the current annotation and can be useful to take into account when drawing those properties that the annotation does not have. Note that annotation properties will take precedence, so such properties cannot be overridden by using this method (e.g. background, text color, etc.).

Also note that the model element won't be used for annotations for choice form field.

Parameters:

element - model element to set.

Returns:

this PdfFormAnnotation.

setAppearance

public PdfFormAnnotation setAppearance(PdfName appearanceType,
                                       String appearanceState,
                                       PdfStream appearanceStream)

Sets an appearance for (the widgets related to) the form field.

Parameters:

appearanceType - the type of appearance stream to be added

• PdfName.N: normal appearance
• PdfName.R: rollover appearance
• PdfName.D: down appearance

appearanceState - the state of the form field that needs to be true for the appearance to be used. Differentiates between several streams of the same type.

appearanceStream - the appearance instructions, as a PdfStream.

Returns:

The edited PdfFormAnnotation.

setCheckBoxAppearanceOnStateName

public PdfFormAnnotation setCheckBoxAppearanceOnStateName(String onStateName)

Sets on state name for the checkbox annotation normal appearance and regenerates widget.

Parameters:

onStateName - the new appearance name representing on state.

Returns:

The edited PdfFormAnnotation.

getRect

protected Rectangle getRect(PdfDictionary field)

Gets a Rectangle that matches the current size and position of this form field.

Parameters:

field - current form field.

Returns:

a Rectangle that matches the current size and position of this form field annotation.

drawBorder

protected void drawBorder(PdfCanvas canvas,
                          PdfFormXObject xObject,
                          float width,
                          float height)

Draws a border using the borderWidth and borderColor of the form field.

Parameters:

canvas - The PdfCanvas on which to draw

xObject - The PdfFormXObject

width - The width of the rectangle to draw

height - The height of the rectangle to draw

drawPushButtonFieldAndSaveAppearance

protected void drawPushButtonFieldAndSaveAppearance()

Draws the appearance of a push button and saves it into an appearance stream.

drawSignatureFormFieldAndSaveAppearance

protected void drawSignatureFormFieldAndSaveAppearance()

Draws the appearance of a signature field and saves it into an appearance stream.

drawRadioButtonAndSaveAppearance

protected void drawRadioButtonAndSaveAppearance(String value)

Draws the appearance of a radio button with a specified value and saves it into an appearance stream.

Parameters:

value - the value of the radio button.

drawListFormFieldAndSaveAppearance

protected void drawListFormFieldAndSaveAppearance()

Draws the appearance of a list box form field and saves it into an appearance stream.

drawTextFormFieldAndSaveAppearance

protected void drawTextFormFieldAndSaveAppearance()

Draws the appearance of a text form field and saves it into an appearance stream.

drawComboBoxAndSaveAppearance

protected void drawComboBoxAndSaveAppearance()

Draws the appearance of a Combo box form field and saves it into an appearance stream.

drawCheckBoxAndSaveAppearance

protected void drawCheckBoxAndSaveAppearance(String onStateName)

Draw a checkbox and save its appearance.

Parameters:

onStateName - the name of the appearance state for the checked state