Top Description Fields Constructors Methods
org.apache.pdfbox.pdmodel.interactive.annotation

public abstract Class PDAnnotation

extends Object
implements COSObjectable
Class Inheritance
All Implemented Interfaces
org.apache.pdfbox.pdmodel.common.COSObjectable
Known Direct Subclasses
org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationLink, org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationMarkup, org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationUnknown, org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationWidget, org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationPopup
Imports
java.io.IOException, java.util.Calendar, .Objects, org.apache.commons.logging.Log, .LogFactory, org.apache.pdfbox.cos.COSArray, .COSBase, .COSDictionary, .COSInteger, .COSName, .COSNumber, org.apache.pdfbox.pdmodel.PDDocument, .PDPage, org.apache.pdfbox.pdmodel.common.COSObjectable, .PDRectangle, org.apache.pdfbox.pdmodel.documentinterchange.markedcontent.PDPropertyList, org.apache.pdfbox.pdmodel.graphics.color.PDColor, .PDColorSpace, .PDDeviceCMYK, .PDDeviceGray, .PDDeviceRGB

A PDF annotation.
Author
Ben Litchfield

Field Summary

Modifier and TypeField and Description
private final COSDictionary
private static final int
FLAG_HIDDEN

An annotation flag.

private static final int
FLAG_INVISIBLE

An annotation flag.

private static final int
FLAG_LOCKED

An annotation flag.

private static final int
FLAG_LOCKED_CONTENTS

An annotation flag.

private static final int
FLAG_NO_ROTATE

An annotation flag.

private static final int
FLAG_NO_VIEW

An annotation flag.

private static final int
FLAG_NO_ZOOM

An annotation flag.

private static final int
FLAG_PRINTED

An annotation flag.

private static final int
FLAG_READ_ONLY

An annotation flag.

private static final int
FLAG_TOGGLE_NO_VIEW

An annotation flag.

private static final Log
LOG

Log instance.

Constructor Summary

AccessConstructor and Description
public
PDAnnotation()

Constructor.

public
PDAnnotation(COSDictionary
The annotations dictionary.
dict
)

Constructor.

Method Summary

Modifier and TypeMethod and Description
public void
constructAppearances(PDDocument
the related document
document
)

Create the appearance entry for this annotation.

public void
constructAppearances()

Create the appearance entry for this annotation.

public static PDAnnotation

Returns:

The correctly typed annotation object, never null.
createAnnotation
(COSBase
The COS object that is the annotation.
base
)

Create the correct annotation from the base COS object.

public boolean
equals(Object
the reference object with which to compare.
o
)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public int

Returns:

flags The set of flags.
getAnnotationFlags
()

This will get the flags for this field.

public String

Returns:

The identifying name for the Annotation.
getAnnotationName
()

This will get the name, a string intended to uniquely identify each annotation within a page.

public PDAppearanceDictionary

Returns:

This annotations appearance.
getAppearance
()

This will get the appearance dictionary associated with this annotation.

public COSName

Returns:

the annotations appearance state
getAppearanceState
()

Returns the annotations appearance state, which selects the applicable appearance stream from an appearance subdictionary.

public COSArray

Returns:

the border array, never null.
getBorder
()

This will retrieve the border array.

public PDColor

Returns:

Color object representing the colour
getColor
()

This will retrieve the color used in drawing various elements.

protected PDColor
getColor(COSName itemName)

public String

Returns:

the value of the contents.
getContents
()

Get the "contents" of the field.

public COSDictionary

Returns:

This object as a standard COS object.
getCOSObject
()

Implements org.apache.pdfbox.pdmodel.common.COSObjectable.getCOSObject.

Interface method for COSObjectable.

public String

Returns:

the modified date/time (often in date format, but can be an arbitrary string).
getModifiedDate
()

This will retrieve the date and time the annotation was modified.

public PDAppearanceStream

Returns:

the appearance stream
getNormalAppearanceStream
()

Returns the appearance stream for this annotation, if any.

public PDPropertyList

Returns:

The optional content group or optional content membership dictionary or null if there is none.
getOptionalContent
()

This will get the optional content group or optional content membership dictionary for the annotation.

public PDPage

Returns:

The corresponding page or null if not available.
getPage
()

This will retrieve the corresponding page of this annotation.

public PDRectangle

Returns:

The Rect value of this annotation.
getRectangle
()

The annotation rectangle, defining the location of the annotation on the page in default user space units.

public int

Returns:

the integer key of the annotation's entry in the structural parent tree or -1 if there isn't any.
getStructParent
()

This will get the key of this annotation in the structural parent tree.

public final String

Returns:

The subtype of this annotation, see the SUB_TYPE_XXX constants.
getSubtype
()

This will retrieve the subtype of the annotation.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public boolean

Returns:

The hidden flag.
isHidden
()

Get the hidden flag.

public boolean

Returns:

The invisible flag.
isInvisible
()

Get the invisible flag.

public boolean

Returns:

The locked flag.
isLocked
()

Get the locked flag.

public boolean

Returns:

The LockedContents flag.
isLockedContents
()

Get the LockedContents flag.

public boolean

Returns:

The noRotate flag.
isNoRotate
()

Get the noRotate flag.

public boolean

Returns:

The noView flag.
isNoView
()

Get the noView flag.

public boolean

Returns:

The noZoom flag.
isNoZoom
()

Get the noZoom flag.

public boolean

Returns:

The printed flag.
isPrinted
()

Get the printed flag.

public boolean

Returns:

The readOnly flag.
isReadOnly
()

Get the readOnly flag.

public boolean

Returns:

The toggleNoView flag.
isToggleNoView
()

Get the toggleNoView flag.

public void
setAnnotationFlags(int
The new flags.
flags
)

This will set the flags for this field.

public void
setAnnotationName(String
The identifying name for the annotation.
nm
)

This will set the name, a string intended to uniquely identify each annotation within a page.

public void
setAppearance(PDAppearanceDictionary
The appearance dictionary for this annotation.
appearance
)

This will set the appearance associated with this annotation.

public void
setAppearanceState(String
The name of the appearance stream.
as
)

This will set the annotations appearance state name.

public void
setBorder(COSArray
the border array to set.
borderArray
)

This will set the border array.

public void
setColor(PDColor
colour in the DeviceRGB colourspace
c
)

This will set the color used in drawing various elements.

public void
setContents(String
the value of the contents.
value
)

Set the "contents" of the field.

public void
setHidden(boolean
The new hidden flag.
hidden
)

Set the hidden flag.

public void
setInvisible(boolean
The new invisible flag.
invisible
)

Set the invisible flag.

public void
setLocked(boolean
The new locked flag.
locked
)

Set the locked flag.

public void
setLockedContents(boolean
The new LockedContents flag value.
lockedContents
)

Set the LockedContents flag.

public void
setModifiedDate(String
the date and time the annotation was created. Date values used in a PDF shall conform to a standard date format, which closely follows that of the international standard ASN.1 (Abstract Syntax Notation One), defined in ISO/IEC 8824. A date shall be a text string of the form (D:YYYYMMDDHHmmSSOHH'mm). Alternatively, use setModifiedDate(java.util.Calendar)
m
)

This will set the date and time the annotation was modified.

public void
setModifiedDate(Calendar
the date and time the annotation was created.
c
)

This will set the date and time the annotation was modified.

public void
setNoRotate(boolean
The new noRotate flag.
noRotate
)

Set the noRotate flag.

public void
setNoView(boolean
The new noView flag.
noView
)

Set the noView flag.

public void
setNoZoom(boolean
The new noZoom flag.
noZoom
)

Set the noZoom flag.

public void
setOptionalContent(PDPropertyList
The optional content group or optional content membership dictionary.
oc
)

Sets the optional content group or optional content membership dictionary for the annotation.

public void
setPage(PDPage
is the corresponding page
page
)

This will set the corresponding page for this annotation.

public void
setPrinted(boolean
The new printed flag.
printed
)

Set the printed flag.

public void
setReadOnly(boolean
The new readOnly flag.
readOnly
)

Set the readOnly flag.

public void
setRectangle(PDRectangle
The new rectangle values.
rectangle
)

This will set the rectangle for this annotation.

public void
setStructParent(int
The new key for this annotation.
structParent
)

This will set the key for this annotation in the structural parent tree.

protected final void
setSubtype(String
The subtype of the annotation
subType
)

This will set the sub type (and hence appearance, AP taking precedence) For this annotation.

public void
setToggleNoView(boolean
The new toggleNoView flag.
toggleNoView
)

Set the toggleNoView flag.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

dictionaryback to summary
private final COSDictionary dictionary
FLAG_HIDDENback to summary
private static final int FLAG_HIDDEN

An annotation flag.

FLAG_INVISIBLEback to summary
private static final int FLAG_INVISIBLE

An annotation flag.

FLAG_LOCKEDback to summary
private static final int FLAG_LOCKED

An annotation flag.

FLAG_LOCKED_CONTENTSback to summary
private static final int FLAG_LOCKED_CONTENTS

An annotation flag.

See Also
setLockedContents(boolean)
FLAG_NO_ROTATEback to summary
private static final int FLAG_NO_ROTATE

An annotation flag.

FLAG_NO_VIEWback to summary
private static final int FLAG_NO_VIEW

An annotation flag.

FLAG_NO_ZOOMback to summary
private static final int FLAG_NO_ZOOM

An annotation flag.

FLAG_PRINTEDback to summary
private static final int FLAG_PRINTED

An annotation flag.

FLAG_READ_ONLYback to summary
private static final int FLAG_READ_ONLY

An annotation flag.

FLAG_TOGGLE_NO_VIEWback to summary
private static final int FLAG_TOGGLE_NO_VIEW

An annotation flag.

LOGback to summary
private static final Log LOG

Log instance.

Constructor Detail

PDAnnotationback to summary
public PDAnnotation()

Constructor.

PDAnnotationback to summary
public PDAnnotation(COSDictionary dict)

Constructor.

Parameters
dict:COSDictionary

The annotations dictionary.

Method Detail

constructAppearancesback to summary
public void constructAppearances(PDDocument document)

Create the appearance entry for this annotation. Not having it may prevent display in some viewers. This method is for overriding in subclasses, the default implementation does nothing.

Parameters
document:PDDocument

the related document

constructAppearancesback to summary
public void constructAppearances()

Create the appearance entry for this annotation. Not having it may prevent display in some viewers. This method is for overriding in subclasses, the default implementation does nothing.

createAnnotationback to summary
public static PDAnnotation createAnnotation(COSBase base) throws IOException

Create the correct annotation from the base COS object.

Parameters
base:COSBase

The COS object that is the annotation.

Returns:PDAnnotation

The correctly typed annotation object, never null.

Exceptions
IOException:
If the annotation type is unknown.
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getAnnotationFlagsback to summary
public int getAnnotationFlags()

This will get the flags for this field.

Returns:int

flags The set of flags.

getAnnotationNameback to summary
public String getAnnotationName()

This will get the name, a string intended to uniquely identify each annotation within a page. Not to be confused with some annotations Name entry which impact the default image drawn for them.

Returns:String

The identifying name for the Annotation.

getAppearanceback to summary
public PDAppearanceDictionary getAppearance()

This will get the appearance dictionary associated with this annotation. This may return null.

Returns:PDAppearanceDictionary

This annotations appearance.

getAppearanceStateback to summary
public COSName getAppearanceState()

Returns the annotations appearance state, which selects the applicable appearance stream from an appearance subdictionary.

Returns:COSName

the annotations appearance state

getBorderback to summary
public COSArray getBorder()

This will retrieve the border array. If none is available then it will create and return a default array, which is [0 0 1]. The array consists of at least three numbers defining the horizontal corner radius, vertical corner radius, and border width. The array may have a fourth element, an optional dash array defining a pattern of dashes and gaps that shall be used in drawing the border. If the array has less than three elements, the original array will be copied and missing elements with value 0 will be added.

Returns:COSArray

the border array, never null.

getColorback to summary
public PDColor getColor()

This will retrieve the color used in drawing various elements. As of PDF 1.6 these are :

  • Background of icon when closed
  • Title bar of popup window
  • Border of a link annotation
Returns:PDColor

Color object representing the colour

getColorback to summary
protected PDColor getColor(COSName itemName)
getContentsback to summary
public String getContents()

Get the "contents" of the field.

Returns:String

the value of the contents.

getCOSObjectback to summary
public COSDictionary getCOSObject()

Implements org.apache.pdfbox.pdmodel.common.COSObjectable.getCOSObject.

Interface method for COSObjectable.

Returns:COSDictionary

This object as a standard COS object.

Annotations
@Override
getModifiedDateback to summary
public String getModifiedDate()

This will retrieve the date and time the annotation was modified.

Returns:String

the modified date/time (often in date format, but can be an arbitrary string).

getNormalAppearanceStreamback to summary
public PDAppearanceStream getNormalAppearanceStream()

Returns the appearance stream for this annotation, if any. The annotation state is taken into account, if present.

Returns:PDAppearanceStream

the appearance stream

getOptionalContentback to summary
public PDPropertyList getOptionalContent()

This will get the optional content group or optional content membership dictionary for the annotation.

Returns:PDPropertyList

The optional content group or optional content membership dictionary or null if there is none.

getPageback to summary
public PDPage getPage()

This will retrieve the corresponding page of this annotation. See also this answer about what to do if the page isn't available.

Returns:PDPage

The corresponding page or null if not available.

getRectangleback to summary
public PDRectangle getRectangle()

The annotation rectangle, defining the location of the annotation on the page in default user space units. This is usually required and should not return null on valid PDF documents. But where this is a parent form field with children, such as radio button collections then the rectangle will be null.

Returns:PDRectangle

The Rect value of this annotation.

getStructParentback to summary
public int getStructParent()

This will get the key of this annotation in the structural parent tree.

Returns:int

the integer key of the annotation's entry in the structural parent tree or -1 if there isn't any.

getSubtypeback to summary
public final String getSubtype()

This will retrieve the subtype of the annotation.

Returns:String

The subtype of this annotation, see the SUB_TYPE_XXX constants.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
isHiddenback to summary
public boolean isHidden()

Get the hidden flag.

Returns:boolean

The hidden flag.

isInvisibleback to summary
public boolean isInvisible()

Get the invisible flag.

Returns:boolean

The invisible flag.

isLockedback to summary
public boolean isLocked()

Get the locked flag.

Returns:boolean

The locked flag.

isLockedContentsback to summary
public boolean isLockedContents()

Get the LockedContents flag.

Returns:boolean

The LockedContents flag.

See Also
setLockedContents(boolean)
isNoRotateback to summary
public boolean isNoRotate()

Get the noRotate flag.

Returns:boolean

The noRotate flag.

isNoViewback to summary
public boolean isNoView()

Get the noView flag.

Returns:boolean

The noView flag.

isNoZoomback to summary
public boolean isNoZoom()

Get the noZoom flag.

Returns:boolean

The noZoom flag.

isPrintedback to summary
public boolean isPrinted()

Get the printed flag.

Returns:boolean

The printed flag.

isReadOnlyback to summary
public boolean isReadOnly()

Get the readOnly flag.

Returns:boolean

The readOnly flag.

isToggleNoViewback to summary
public boolean isToggleNoView()

Get the toggleNoView flag.

Returns:boolean

The toggleNoView flag.

setAnnotationFlagsback to summary
public void setAnnotationFlags(int flags)

This will set the flags for this field.

Parameters
flags:int

The new flags.

setAnnotationNameback to summary
public void setAnnotationName(String nm)

This will set the name, a string intended to uniquely identify each annotation within a page. Not to be confused with some annotations Name entry which impact the default image drawn for them.

Parameters
nm:String

The identifying name for the annotation.

setAppearanceback to summary
public void setAppearance(PDAppearanceDictionary appearance)

This will set the appearance associated with this annotation.

Parameters
appearance:PDAppearanceDictionary

The appearance dictionary for this annotation.

setAppearanceStateback to summary
public void setAppearanceState(String as)

This will set the annotations appearance state name.

Parameters
as:String

The name of the appearance stream.

setBorderback to summary
public void setBorder(COSArray borderArray)

This will set the border array.

Parameters
borderArray:COSArray

the border array to set.

setColorback to summary
public void setColor(PDColor c)

This will set the color used in drawing various elements. As of PDF 1.6 these are : Background of icon when closed Title bar of popup window Border of a link annotation Colour is in DeviceRGB colourspace

Parameters
c:PDColor

colour in the DeviceRGB colourspace

setContentsback to summary
public void setContents(String value)

Set the "contents" of the field.

Parameters
value:String

the value of the contents.

setHiddenback to summary
public void setHidden(boolean hidden)

Set the hidden flag.

Parameters
hidden:boolean

The new hidden flag.

setInvisibleback to summary
public void setInvisible(boolean invisible)

Set the invisible flag.

Parameters
invisible:boolean

The new invisible flag.

setLockedback to summary
public void setLocked(boolean locked)

Set the locked flag.

Parameters
locked:boolean

The new locked flag.

setLockedContentsback to summary
public void setLockedContents(boolean lockedContents)

Set the LockedContents flag. If set, do not allow the contents of the annotation to be modified by the user. This flag does not restrict deletion of the annotation or changes to other annotation properties, such as position and size.

Parameters
lockedContents:boolean

The new LockedContents flag value.

Since
PDF 1.7
See Also
PDF 32000-1:2008 12.5.3, Table 165, isLockedContents(), FLAG_LOCKED_CONTENTS
setModifiedDateback to summary
public void setModifiedDate(String m)

This will set the date and time the annotation was modified.

Parameters
m:String

the date and time the annotation was created. Date values used in a PDF shall conform to a standard date format, which closely follows that of the international standard ASN.1 (Abstract Syntax Notation One), defined in ISO/IEC 8824. A date shall be a text string of the form (D:YYYYMMDDHHmmSSOHH'mm). Alternatively, use setModifiedDate(java.util.Calendar)

setModifiedDateback to summary
public void setModifiedDate(Calendar c)

This will set the date and time the annotation was modified.

Parameters
c:Calendar

the date and time the annotation was created.

setNoRotateback to summary
public void setNoRotate(boolean noRotate)

Set the noRotate flag.

Parameters
noRotate:boolean

The new noRotate flag.

setNoViewback to summary
public void setNoView(boolean noView)

Set the noView flag.

Parameters
noView:boolean

The new noView flag.

setNoZoomback to summary
public void setNoZoom(boolean noZoom)

Set the noZoom flag.

Parameters
noZoom:boolean

The new noZoom flag.

setOptionalContentback to summary
public void setOptionalContent(PDPropertyList oc)

Sets the optional content group or optional content membership dictionary for the annotation.

Parameters
oc:PDPropertyList

The optional content group or optional content membership dictionary.

setPageback to summary
public void setPage(PDPage page)

This will set the corresponding page for this annotation. This is optional but recommended. Not doing it can cause trouble when PDFs get signed.

Parameters
page:PDPage

is the corresponding page

setPrintedback to summary
public void setPrinted(boolean printed)

Set the printed flag.

Parameters
printed:boolean

The new printed flag.

setReadOnlyback to summary
public void setReadOnly(boolean readOnly)

Set the readOnly flag.

Parameters
readOnly:boolean

The new readOnly flag.

setRectangleback to summary
public void setRectangle(PDRectangle rectangle)

This will set the rectangle for this annotation.

Parameters
rectangle:PDRectangle

The new rectangle values.

setStructParentback to summary
public void setStructParent(int structParent)

This will set the key for this annotation in the structural parent tree.

Parameters
structParent:int

The new key for this annotation.

setSubtypeback to summary
protected final void setSubtype(String subType)

This will set the sub type (and hence appearance, AP taking precedence) For this annotation. See the SUB_TYPE_XXX constants for valid values.

Parameters
subType:String

The subtype of the annotation

setToggleNoViewback to summary
public void setToggleNoView(boolean toggleNoView)

Set the toggleNoView flag.

Parameters
toggleNoView:boolean

The new toggleNoView flag.