com.itextpdf.kernel.pdf.annot

Class PdfMarkupAnnotation

java.lang.Object

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

com.itextpdf.kernel.pdf.annot.PdfAnnotation

com.itextpdf.kernel.pdf.annot.PdfMarkupAnnotation

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

PdfCaretAnnotation, PdfCircleAnnotation, PdfFileAttachmentAnnotation, PdfFreeTextAnnotation, PdfInkAnnotation, PdfLineAnnotation, PdfPolyGeomAnnotation, PdfRedactAnnotation, PdfSoundAnnotation, PdfSquareAnnotation, PdfStampAnnotation, PdfTextAnnotation, PdfTextMarkupAnnotation

public abstract class PdfMarkupAnnotation
extends PdfAnnotation

This is a super class for the annotations which are defined as markup annotations because they are used primarily to mark up PDF documents. These annotations have text that appears as part of the annotation and may be displayed in other ways by a conforming reader, such as in a Comments pane. See also ISO-320001 12.5.6.2 "Markup Annotations".

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected PdfAnnotation	inReplyTo
protected PdfPopupAnnotation	popup

Fields inherited from class com.itextpdf.kernel.pdf.annot.PdfAnnotation

Accepted, Canceled, Completed, HIDDEN, HIGHLIGHT_INVERT, HIGHLIGHT_NONE, HIGHLIGHT_OUTLINE, HIGHLIGHT_PUSH, HIGHLIGHT_TOGGLE, INVISIBLE, LOCKED, LOCKED_CONTENTS, Marked, MarkedModel, NO_ROTATE, NO_VIEW, NO_ZOOM, None, page, PRINT, READ_ONLY, Rejected, ReviewModel, STYLE_BEVELED, STYLE_DASHED, STYLE_INSET, STYLE_SOLID, STYLE_UNDERLINE, TOGGLE_NO_VIEW, Unmarked

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PdfMarkupAnnotation(PdfDictionary pdfObject)
protected	PdfMarkupAnnotation(Rectangle rect)

Method Summary

Modifier and Type	Method and Description
PdfDictionary	getBorderEffect() A border effect dictionary that specifies an effect that shall be applied to the border of the annotations.
PdfString	getCreationDate() The date and time when the annotation was created.
PdfString	getDefaultAppearance() The default appearance string that shall be used in formatting the text.
PdfDictionary	getExternalData() An external data dictionary specifying data that shall be associated with the annotation.
PdfName	getIconName() The name of an icon that is used in displaying the annotation.
PdfAnnotation	getInReplyTo() An annotation that this annotation is “in reply to.” Both annotations shall be on the same page of the document.
PdfDictionary	getInReplyToObject() An annotation object that this annotation is “in reply to.” Both annotations shall be on the same page of the document.
PdfName	getIntent() A name describing the intent of the markup annotation.
Color	getInteriorColor() The interior color which is used to fill areas specific for different types of annotation.
int	getJustification() A code specifying the form of quadding (justification) that is used in displaying the annotation's text: 0 - Left-justified, 1 - Centered, 2 - Right-justified.
PdfNumber	getOpacity() The constant opacity value that will be used in painting the annotation.
PdfPopupAnnotation	getPopup() An associated pop-up annotation for entering or editing the text associated with this annotation.
PdfDictionary	getPopupObject() An associated pop-up annotation object.
PdfArray	getRectangleDifferences() A set of four numbers describing the numerical differences between two rectangles: the Rect entry of the annotation and another rectangle within that one, which meaning depends on the type of the annotation (see setRectangleDifferences(PdfArray)).
PdfName	getReplyType() A name specifying the relationship (the “reply type”) between this annotation and one specified by IRT entry (see getInReplyTo()).
PdfObject	getRichText() A rich text string (see ISO-320001 12.7.3.4, “Rich Text Strings”) that shall be displayed in the pop-up window when the annotation is opened.
PdfString	getSubject() Text representing a short description of the subject being addressed by the annotation.
PdfString	getText() The text label that will be displayed in the title bar of the annotation's pop-up window when open and active.
PdfMarkupAnnotation	setBorderEffect(PdfDictionary borderEffect) Some annotations types (PdfSquareAnnotation, PdfCircleAnnotation, PdfPolyGeomAnnotation and PdfFreeTextAnnotation) may have a PdfName.BE entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations.
PdfMarkupAnnotation	setCreationDate(PdfString creationDate) Sets the date and time when the annotation was created.
PdfMarkupAnnotation	setDefaultAppearance(PdfString appearanceString) The default appearance string that shall be used in formatting the text.
PdfMarkupAnnotation	setExternalData(PdfName exData) Sets an external data dictionary specifying data that shall be associated with the annotation.
PdfMarkupAnnotation	setIconName(PdfName name) The name of an icon that is used in displaying the annotation.
PdfMarkupAnnotation	setInReplyTo(PdfAnnotation inReplyTo) Sets an annotation that this annotation is “in reply to.” Both annotations shall be on the same page of the document.
PdfMarkupAnnotation	setIntent(PdfName intent) Sets a name describing the intent of the markup annotation.
PdfMarkupAnnotation	setInteriorColor(float[] interiorColor) An array of numbers in the range 0.0 to 1.0 specifying the interior color which is used to fill areas specific for different types of annotation.
PdfMarkupAnnotation	setInteriorColor(PdfArray interiorColor) An array of numbers in the range 0.0 to 1.0 specifying the interior color which is used to fill areas specific for different types of annotation.
PdfMarkupAnnotation	setJustification(int justification) A code specifying the form of quadding (justification) that is used in displaying the annotation's text: 0 - Left-justified, 1 - Centered, 2 - Right-justified.
PdfMarkupAnnotation	setOpacity(PdfNumber ca) Sets the constant opacity value that will be used in painting the annotation.
PdfMarkupAnnotation	setPopup(PdfPopupAnnotation popup) Sets a pop-up annotation for entering or editing the text associated with this annotation.
PdfMarkupAnnotation	setRectangleDifferences(PdfArray rect) A set of four numbers describing the numerical differences between two rectangles: the Rect entry of the annotation and another rectangle within that one, which meaning depends on the type of the annotation: for PdfFreeTextAnnotation the inner rectangle is where the annotation's text should be displayed; for PdfSquareAnnotation and PdfCircleAnnotation the inner rectangle is the actual boundaries of the underlying square or circle; for PdfCaretAnnotation the inner rectangle is the actual boundaries of the underlying caret.
PdfMarkupAnnotation	setReplyType(PdfName replyType) Sets the relationship (the “reply type”) between this annotation and one specified by IRT entry (see setInReplyTo(PdfAnnotation)).
PdfMarkupAnnotation	setRichText(PdfObject richText) Sets a rich text string (see ISO-320001 12.7.3.4, “Rich Text Strings”) that shall be displayed in the pop-up window when the annotation is opened.
PdfMarkupAnnotation	setSubject(PdfString subject) Sets the text representing a short description of the subject being addressed by the annotation.
PdfMarkupAnnotation	setText(PdfString text) Sets the text label that will be displayed in the title bar of the annotation's pop-up window when open and active.

Methods inherited from class com.itextpdf.kernel.pdf.annot.PdfAnnotation

flush, getAction, getAdditionalAction, getAppearanceCharacteristics, getAppearanceDictionary, getAppearanceObject, getAppearanceState, getBorder, getBorderStyle, getColorObject, getContents, getDate, getDownAppearanceObject, getFlags, getName, getNormalAppearanceObject, getOpen, getPage, getPageObject, getQuadPoints, getRectangle, getRolloverAppearanceObject, getStructParentIndex, getSubtype, getTitle, hasFlag, isWrappedObjectMustBeIndirect, makeAnnotation, makeAnnotation, put, remove, resetFlag, setAction, setAdditionalAction, setAppearance, setAppearance, setAppearanceCharacteristics, setAppearanceState, setBorder, setBorderStyle, setBorderStyle, setColor, setColor, setColor, setContents, setContents, setDashPattern, setDate, setDownAppearance, setDownAppearance, setFlag, setFlags, setLayer, setName, setNormalAppearance, setNormalAppearance, setOpen, setPage, setQuadPoints, setRectangle, setRolloverAppearance, setRolloverAppearance, setStructParentIndex, setTitle

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

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

Methods inherited from class java.lang.Object

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

Field Detail

inReplyTo

protected PdfAnnotation inReplyTo

popup

protected PdfPopupAnnotation popup

Constructor Detail

PdfMarkupAnnotation

protected PdfMarkupAnnotation(Rectangle rect)

PdfMarkupAnnotation

protected PdfMarkupAnnotation(PdfDictionary pdfObject)

Method Detail

getText

public PdfString getText()

The text label that will be displayed in the title bar of the annotation's pop-up window when open and active. This entry shall identify the user who added the annotation.

Returns:

PdfString which value is an annotation text label content or null if text is not specified.

setText

public PdfMarkupAnnotation setText(PdfString text)

Sets the text label that will be displayed in the title bar of the annotation's pop-up window when open and active. This entry shall identify the user who added the annotation.

Parameters:

text - PdfString which value is an annotation text label content.

Returns:

this PdfMarkupAnnotation instance.

getOpacity

public PdfNumber getOpacity()

The constant opacity value that will be used in painting the annotation. This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. Default value: 1.0.

Returns:

a PdfNumber which value is in range between 0 and 1, which specifies the level of opacity. This method returns null if opacity is not specified; in this case default value is used, which is 1.

setOpacity

public PdfMarkupAnnotation setOpacity(PdfNumber ca)

Sets the constant opacity value that will be used in painting the annotation.

Parameters:

ca - a PdfNumber which value is in range between 0 and 1, which specifies the level of opacity.

Returns:

this PdfMarkupAnnotation instance.

See Also:

getOpacity()

getRichText

public PdfObject getRichText()

A rich text string (see ISO-320001 12.7.3.4, “Rich Text Strings”) that shall be displayed in the pop-up window when the annotation is opened.

Returns:

text string or text stream that specifies rich text or null if rich text is not specified.

setRichText

public PdfMarkupAnnotation setRichText(PdfObject richText)

Sets a rich text string (see ISO-320001 12.7.3.4, “Rich Text Strings”) that shall be displayed in the pop-up window when the annotation is opened.

Parameters:

richText - text string or text stream that specifies rich text.

Returns:

this PdfMarkupAnnotation instance.

getCreationDate

public PdfString getCreationDate()

The date and time when the annotation was created.

Returns:

a PdfString which value should be in the date format specified in (ISO-320001 7.9.4, “Dates”).

setCreationDate

public PdfMarkupAnnotation setCreationDate(PdfString creationDate)

Sets the date and time when the annotation was created.

Parameters:

creationDate - PdfString which value should be in the date format specified in (ISO-320001 7.9.4, “Dates”).

Returns:

this PdfMarkupAnnotation instance.

getInReplyToObject

public PdfDictionary getInReplyToObject()

An annotation object that this annotation is “in reply to.” Both annotations shall be on the same page of the document. The relationship between the two annotations shall be specified by the RT entry (see getReplyType()).

Returns:

a PdfDictionary that represents an annotation that this annotation is “in reply to.”

getInReplyTo

public PdfAnnotation getInReplyTo()

An annotation that this annotation is “in reply to.” Both annotations shall be on the same page of the document. The relationship between the two annotations shall be specified by the RT entry (see getReplyType()).

Returns:

a PdfAnnotation that this annotation is “in reply to.”

setInReplyTo

public PdfMarkupAnnotation setInReplyTo(PdfAnnotation inReplyTo)

Sets an annotation that this annotation is “in reply to.” Both annotations shall be on the same page of the document. The relationship between the two annotations shall be specified by the RT entry (see getReplyType()).

Parameters:

inReplyTo - a PdfAnnotation that this annotation is “in reply to.”

Returns:

this PdfMarkupAnnotation instance.

setPopup

public PdfMarkupAnnotation setPopup(PdfPopupAnnotation popup)

Sets a pop-up annotation for entering or editing the text associated with this annotation. Pop-up annotation defines an associated with this annotation pop-up window that may contain text. The Contents (see PdfAnnotation.setContents(PdfString)) entry of the annotation that has an associated popup specifies the text that shall be displayed when the pop-up window is opened.

Parameters:

popup - an PdfPopupAnnotation that will be associated with this annotation.

Returns:

this PdfMarkupAnnotation instance.

getPopupObject

public PdfDictionary getPopupObject()

An associated pop-up annotation object. See getPopup() for more info.

Returns:

a PdfDictionary that represents an associated pop-up annotation, or null if popup annotation is not specified.

getPopup

public PdfPopupAnnotation getPopup()

An associated pop-up annotation for entering or editing the text associated with this annotation. Pop-up annotation defines an associated with this annotation pop-up window that may contain text. The Contents (see PdfAnnotation.getContents()) entry of the annotation that has an associated popup specifies the text that shall be displayed when the pop-up window is opened.

Returns:

an PdfPopupAnnotation that is associated with this annotation, or null if there is none.

getSubject

public PdfString getSubject()

Text representing a short description of the subject being addressed by the annotation.

Returns:

a PdfString which value is a annotation subject.

setSubject

public PdfMarkupAnnotation setSubject(PdfString subject)

Sets the text representing a short description of the subject being addressed by the annotation.

Parameters:

subject - a PdfString which value is a annotation subject.

Returns:

this PdfMarkupAnnotation instance.

getReplyType

public PdfName getReplyType()

A name specifying the relationship (the “reply type”) between this annotation and one specified by IRT entry (see getInReplyTo()). Valid values are:

• PdfName.R - The annotation shall be considered a reply to the annotation specified by IRT. Conforming readers shall not display replies to an annotation individually but together in the form of threaded comments.
• PdfName.Group - The annotation shall be grouped with the annotation specified by IRT.

Returns:

a PdfName specifying relationship with the specified by the IRT entry; or null if reply type is not specified, in this case the default value is PdfName.R.

setReplyType

public PdfMarkupAnnotation setReplyType(PdfName replyType)

Sets the relationship (the “reply type”) between this annotation and one specified by IRT entry (see setInReplyTo(PdfAnnotation)). For valid values see getInReplyTo().

Parameters:

replyType - a PdfName specifying relationship with the specified by the IRT entry.

Returns:

this PdfMarkupAnnotation instance.

getIntent

public PdfName getIntent()

A name describing the intent of the markup annotation. See setIntent(PdfName) for more info.

Returns:

a PdfName describing the intent of the markup annotation, or null if not specified.

setIntent

public PdfMarkupAnnotation setIntent(PdfName intent)

Sets a name describing the intent of the markup annotation. Intents allow conforming readers to distinguish between different uses and behaviors of a single markup annotation type. If this entry is not present or its value is the same as the annotation type, the annotation shall have no explicit intent and should behave in a generic manner in a conforming reader.

See ISO-320001, free text annotations (Table 174), line annotations (Table 175), polygon annotations (Table 178), and polyline annotations (Table 178) for the specific intent values for those types.

Parameters:

intent - a PdfName describing the intent of the markup annotation.

Returns:

this PdfMarkupAnnotation instance.

getExternalData

public PdfDictionary getExternalData()

An external data dictionary specifying data that shall be associated with the annotation. This dictionary contains the following entries:

• PdfName.Type - (optional) If present, shall be PdfName.ExData.
• PdfName.Subtype - (required) a name specifying the type of data that the markup annotation shall be associated with. The only defined value is PdfName.Markup3D. Table 298 (ISO-320001) lists the values that correspond to a subtype of Markup3D (See also Pdf3DAnnotation).

Returns:

An external data PdfDictionary, or null if not specified.

setExternalData

public PdfMarkupAnnotation setExternalData(PdfName exData)

Sets an external data dictionary specifying data that shall be associated with the annotation. This dictionary should contain the following entries:

• PdfName.Type - (optional) If present, shall be PdfName.ExData.
• PdfName.Subtype - (required) a name specifying the type of data that the markup annotation shall be associated with. The only defined value is PdfName.Markup3D. Table 298 (ISO-320001) lists the values that correspond to a subtype of Markup3D (See also Pdf3DAnnotation).

Returns:

this PdfMarkupAnnotation instance.

setRectangleDifferences

public PdfMarkupAnnotation setRectangleDifferences(PdfArray rect)

A set of four numbers describing the numerical differences between two rectangles: the Rect entry of the annotation and another rectangle within that one, which meaning depends on the type of the annotation:

• for PdfFreeTextAnnotation the inner rectangle is where the annotation's text should be displayed;
• for PdfSquareAnnotation and PdfCircleAnnotation the inner rectangle is the actual boundaries of the underlying square or circle;
• for PdfCaretAnnotation the inner rectangle is the actual boundaries of the underlying caret.

Parameters:

rect - a PdfArray with four numbers which correspond to the differences in default user space between the left, top, right, and bottom coordinates of Rect and those of the inner rectangle, respectively. Each value shall be greater than or equal to 0. The sum of the top and bottom differences shall be less than the height of Rect, and the sum of the left and right differences shall be less than the width of Rect.

Returns:

this PdfMarkupAnnotation instance.

getRectangleDifferences

public PdfArray getRectangleDifferences()

A set of four numbers describing the numerical differences between two rectangles: the Rect entry of the annotation and another rectangle within that one, which meaning depends on the type of the annotation (see setRectangleDifferences(PdfArray)).

Returns:

null if not specified, otherwise a PdfArray with four numbers which correspond to the differences in default user space between the left, top, right, and bottom coordinates of Rect and those of the inner rectangle, respectively.

setBorderEffect

public PdfMarkupAnnotation setBorderEffect(PdfDictionary borderEffect)

Some annotations types (PdfSquareAnnotation, PdfCircleAnnotation, PdfPolyGeomAnnotation and PdfFreeTextAnnotation) may have a PdfName.BE entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations.

Parameters:

borderEffect - a PdfDictionary which contents shall be specified in accordance to ISO-320001, Table 167.

Returns:

this PdfMarkupAnnotation instance.

getBorderEffect

public PdfDictionary getBorderEffect()

A border effect dictionary that specifies an effect that shall be applied to the border of the annotations.

Returns:

a PdfDictionary, which is a border effect dictionary (see ISO-320001, Table 167).

getInteriorColor

public Color getInteriorColor()

The interior color which is used to fill areas specific for different types of annotation. For PdfLineAnnotation and polyline annotation (PdfPolyGeomAnnotation - the annotation's line endings, for PdfSquareAnnotation and PdfCircleAnnotation - the annotation's rectangle or ellipse, for PdfRedactAnnotation - the redacted region after the affected content has been removed.

Returns:

Color of either DeviceGray, DeviceRgb or DeviceCmyk type which defines interior color of the annotation, or null if interior color is not specified.

setInteriorColor

public PdfMarkupAnnotation setInteriorColor(PdfArray interiorColor)

An array of numbers in the range 0.0 to 1.0 specifying the interior color which is used to fill areas specific for different types of annotation. For PdfLineAnnotation and polyline annotation (PdfPolyGeomAnnotation - the annotation's line endings, for PdfSquareAnnotation and PdfCircleAnnotation - the annotation's rectangle or ellipse, for PdfRedactAnnotation - the redacted region after the affected content has been removed.

Parameters:

interiorColor - a PdfArray of numbers in the range 0.0 to 1.0. The number of array elements determines the colour space in which the colour is defined: 0 - No colour, transparent; 1 - DeviceGray, 3 - DeviceRGB, 4 - DeviceCMYK. For the PdfRedactAnnotation number of elements shall be equal to 3 (which defines DeviceRGB colour space).

Returns:

this PdfMarkupAnnotation instance.

setInteriorColor

public PdfMarkupAnnotation setInteriorColor(float[] interiorColor)

An array of numbers in the range 0.0 to 1.0 specifying the interior color which is used to fill areas specific for different types of annotation. See setInteriorColor(PdfArray) for more info.

Parameters:

interiorColor - an array of floats in the range 0.0 to 1.0.

Returns:

this PdfMarkupAnnotation instance.

getIconName

public PdfName getIconName()

The name of an icon that is used in displaying the annotation. Possible values are different for different annotation types. See setIconName(PdfName).

Returns:

a PdfName that specifies the icon for displaying annotation, or null if icon name is not specified.

setIconName

public PdfMarkupAnnotation setIconName(PdfName name)

The name of an icon that is used in displaying the annotation.

Parameters:

name - a PdfName that specifies the icon for displaying annotation. Possible values are different for different annotation types:

• PdfTextAnnotation - Comment, Key, Note, Help, NewParagraph, Paragraph, Insert;
• PdfStampAnnotation - Approved, Experimental, NotApproved, AsIs, Expired, NotForPublicRelease, Confidential, Final, Sold, Departmental, ForComment, TopSecret, Draft, ForPublicRelease.
• PdfFileAttachmentAnnotation - GraphPushPin, PaperclipTag. Additional names may be supported as well.
• PdfSoundAnnotation - Speaker and Mic. Additional names may be supported as well.

Returns:

this PdfMarkupAnnotation instance.

setDefaultAppearance

public PdfMarkupAnnotation setDefaultAppearance(PdfString appearanceString)

The default appearance string that shall be used in formatting the text. See ISO-32001 12.7.3.3, “Variable Text”.

Parameters:

appearanceString - a PdfString that specifies the default appearance.

Returns:

this PdfMarkupAnnotation instance.

getDefaultAppearance

public PdfString getDefaultAppearance()

The default appearance string that shall be used in formatting the text. See ISO-32001 12.7.3.3, “Variable Text”.

Returns:

a PdfString that specifies the default appearance, or null if default appereance is not specified.

getJustification

public int getJustification()

A code specifying the form of quadding (justification) that is used in displaying the annotation's text: 0 - Left-justified, 1 - Centered, 2 - Right-justified. Default value: 0 (left-justified).

Returns:

a code specifying the form of quadding (justification), returns the default value if not explicitly specified.

setJustification

public PdfMarkupAnnotation setJustification(int justification)

A code specifying the form of quadding (justification) that is used in displaying the annotation's text: 0 - Left-justified, 1 - Centered, 2 - Right-justified. Default value: 0 (left-justified).

Parameters:

justification - a code specifying the form of quadding (justification).

Returns:

this PdfMarkupAnnotation instance.