org.apache.pdfbox.pdmodel.interactive.annotation

## Class PDAnnotation

- java.lang.Object
- - org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotation

All Implemented Interfaces:
  COSObjectable

Direct Known Subclasses:
  PDAnnotationLink, PDAnnotationMarkup, PDAnnotationPopup, PDAnnotationUnknown, PDAnnotationWidget

    public abstract class PDAnnotation
    extends Object
    implements COSObjectable

A PDF annotation.

Author:
  Ben Litchfield

### Constructor Summary

Constructors
Constructor and Description
`PDAnnotation()` Constructor.
`PDAnnotation(COSDictionary dict)` Constructor.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `constructAppearances()` Create the appearance entry for this annotation.
`void` `constructAppearances(PDDocument document)` Create the appearance entry for this annotation.
`static PDAnnotation` `createAnnotation(COSBase base)` Create the correct annotation from the base COS object.
`boolean` `equals(Object o)`
`int` `getAnnotationFlags()` This will get the flags for this field.
`String` `getAnnotationName()` This will get the name, a string intended to uniquely identify each annotation within a page.
`PDAppearanceDictionary` `getAppearance()` This will get the appearance dictionary associated with this annotation.
`COSName` `getAppearanceState()` Returns the annotations appearance state, which selects the applicable appearance stream from an appearance subdictionary.
`COSArray` `getBorder()` This will retrieve the border array.
`PDColor` `getColor()` This will retrieve the color used in drawing various elements.
`protected PDColor` `getColor(COSName itemName)`
`String` `getContents()` Get the "contents" of the field.
`COSDictionary` `getCOSObject()` Interface method for COSObjectable.
`String` `getModifiedDate()` This will retrieve the date and time the annotation was modified.
`PDAppearanceStream` `getNormalAppearanceStream()` Returns the appearance stream for this annotation, if any.
`PDPropertyList` `getOptionalContent()` This will get the optional content group or optional content membership dictionary for the annotation.
`PDPage` `getPage()` This will retrieve the corresponding page of this annotation.
`PDRectangle` `getRectangle()` The annotation rectangle, defining the location of the annotation on the page in default user space units.
`int` `getStructParent()` This will get the key of this annotation in the structural parent tree.
`String` `getSubtype()` This will retrieve the subtype of the annotation.
`int` `hashCode()`
`boolean` `isHidden()` Get the hidden flag.
`boolean` `isInvisible()` Get the invisible flag.
`boolean` `isLocked()` Get the locked flag.
`boolean` `isLockedContents()` Get the LockedContents flag.
`boolean` `isNoRotate()` Get the noRotate flag.
`boolean` `isNoView()` Get the noView flag.
`boolean` `isNoZoom()` Get the noZoom flag.
`boolean` `isPrinted()` Get the printed flag.
`boolean` `isReadOnly()` Get the readOnly flag.
`boolean` `isToggleNoView()` Get the toggleNoView flag.
`void` `setAnnotationFlags(int flags)` This will set the flags for this field.
`void` `setAnnotationName(String nm)` This will set the name, a string intended to uniquely identify each annotation within a page.
`void` `setAppearance(PDAppearanceDictionary appearance)` This will set the appearance associated with this annotation.
`void` `setAppearanceState(COSName as)` This will set the annotations appearance state name.
`void` `setAppearanceState(String as)` This will set the annotations appearance state name.
`void` `setBorder(COSArray borderArray)` This will set the border array.
`void` `setColor(PDColor c)` This will set the color used in drawing various elements.
`void` `setContents(String value)` Set the "contents" of the field.
`void` `setHidden(boolean hidden)` Set the hidden flag.
`void` `setInvisible(boolean invisible)` Set the invisible flag.
`void` `setLocked(boolean locked)` Set the locked flag.
`void` `setLockedContents(boolean lockedContents)` Set the LockedContents flag.
`void` `setModifiedDate(Calendar c)` This will set the date and time the annotation was modified.
`void` `setModifiedDate(String m)` This will set the date and time the annotation was modified.
`void` `setNoRotate(boolean noRotate)` Set the noRotate flag.
`void` `setNoView(boolean noView)` Set the noView flag.
`void` `setNoZoom(boolean noZoom)` Set the noZoom flag.
`void` `setOptionalContent(PDPropertyList oc)` Sets the optional content group or optional content membership dictionary for the annotation.
`void` `setPage(PDPage page)` This will set the corresponding page for this annotation.
`void` `setPrinted(boolean printed)` Set the printed flag.
`void` `setReadOnly(boolean readOnly)` Set the readOnly flag.
`void` `setRectangle(PDRectangle rectangle)` This will set the rectangle for this annotation.
`void` `setStructParent(int structParent)` This will set the key for this annotation in the structural parent tree.
`protected void` `setSubtype(String subType)` This will set the sub type (and hence appearance, AP taking precedence) For this annotation.
`void` `setToggleNoView(boolean toggleNoView)` Set the toggleNoView flag.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### PDAnnotation

    public PDAnnotation()

Constructor.

#### PDAnnotation

    public PDAnnotation(COSDictionary dict)

Constructor.

Parameters:
  `dict` - The annotations dictionary.

### Method Detail

#### createAnnotation

    public static PDAnnotation createAnnotation(COSBase base)
                                         throws IOException

Create the correct annotation from the base COS object.

Parameters:
  `base` - The COS object that is the annotation.
Returns:
  The correctly typed annotation object, never null.
Throws:
  `IOException` - If the annotation type is unknown.

#### equals

    public boolean equals(Object o)

Overrides:
  `equals` in class `Object`

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Object`

#### setSubtype

    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` - The subtype of the annotation

#### getSubtype

    public final String getSubtype()

This will retrieve the subtype of the annotation.

Returns:
  The subtype of this annotation, see the SUB_TYPE_XXX constants.

#### getRectangle

    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:
  The Rect value of this annotation.

#### setRectangle

    public void setRectangle(PDRectangle rectangle)

This will set the rectangle for this annotation.

Parameters:
  `rectangle` - The new rectangle values.

#### getAnnotationFlags

    public int getAnnotationFlags()

This will get the flags for this field.

Returns:
  flags The set of flags.

#### setAnnotationFlags

    public void setAnnotationFlags(int flags)

This will set the flags for this field.

Parameters:
  `flags` - The new flags.

#### getCOSObject

    public COSDictionary getCOSObject()

Interface method for COSObjectable.

Specified by:
  `getCOSObject` in interface `COSObjectable`
Returns:
  This object as a standard COS object.

#### getAppearanceState

    public COSName getAppearanceState()

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

Returns:
  the annotations appearance state

#### setAppearanceState

    public void setAppearanceState(String as)

This will set the annotations appearance state name.

Parameters:
  `as` - The name of the appearance stream.

#### setAppearanceState

    public void setAppearanceState(COSName as)

This will set the annotations appearance state name.

Note that the PDF specification defines the AS entry as a name, but some PDFs use a string. This method will write a name, which is correct and should be preferred but may cause issues with some viewers if the PDF being edited already uses a string.

Parameters:
  `as` - The COSName of the appearance stream.

#### getAppearance

    public PDAppearanceDictionary getAppearance()

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

Returns:
  This annotations appearance.

#### setAppearance

    public void setAppearance(PDAppearanceDictionary appearance)

This will set the appearance associated with this annotation.

Parameters:
  `appearance` - The appearance dictionary for this annotation.

#### getNormalAppearanceStream

    public PDAppearanceStream getNormalAppearanceStream()

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

Returns:
  the appearance stream

#### isInvisible

    public boolean isInvisible()

Get the invisible flag.

Returns:
  The invisible flag.

#### setInvisible

    public void setInvisible(boolean invisible)

Set the invisible flag.

Parameters:
  `invisible` - The new invisible flag.

#### isHidden

    public boolean isHidden()

Get the hidden flag.

Returns:
  The hidden flag.

#### setHidden

    public void setHidden(boolean hidden)

Set the hidden flag.

Parameters:
  `hidden` - The new hidden flag.

#### isPrinted

    public boolean isPrinted()

Get the printed flag.

Returns:
  The printed flag.

#### setPrinted

    public void setPrinted(boolean printed)

Set the printed flag.

Parameters:
  `printed` - The new printed flag.

#### isNoZoom

    public boolean isNoZoom()

Get the noZoom flag.

Returns:
  The noZoom flag.

#### setNoZoom

    public void setNoZoom(boolean noZoom)

Set the noZoom flag.

Parameters:
  `noZoom` - The new noZoom flag.

#### isNoRotate

    public boolean isNoRotate()

Get the noRotate flag.

Returns:
  The noRotate flag.

#### setNoRotate

    public void setNoRotate(boolean noRotate)

Set the noRotate flag.

Parameters:
  `noRotate` - The new noRotate flag.

#### isNoView

    public boolean isNoView()

Get the noView flag.

Returns:
  The noView flag.

#### setNoView

    public void setNoView(boolean noView)

Set the noView flag.

Parameters:
  `noView` - The new noView flag.

#### isReadOnly

    public boolean isReadOnly()

Get the readOnly flag.

Returns:
  The readOnly flag.

#### setReadOnly

    public void setReadOnly(boolean readOnly)

Set the readOnly flag.

Parameters:
  `readOnly` - The new readOnly flag.

#### isLocked

    public boolean isLocked()

Get the locked flag.

Returns:
  The locked flag.

#### setLocked

    public void setLocked(boolean locked)

Set the locked flag.

Parameters:
  `locked` - The new locked flag.

#### isToggleNoView

    public boolean isToggleNoView()

Get the toggleNoView flag.

Returns:
  The toggleNoView flag.

#### setToggleNoView

    public void setToggleNoView(boolean toggleNoView)

Set the toggleNoView flag.

Parameters:
  `toggleNoView` - The new toggleNoView flag.

#### isLockedContents

    public boolean isLockedContents()

Get the LockedContents flag.

Returns:
  The LockedContents flag.
See Also:
  `setLockedContents(boolean)`

#### setLockedContents

    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` - The new LockedContents flag value.
Since:
  PDF 1.7
See Also:
  PDF 32000-1:2008 12.5.3, Table 165, `isLockedContents()`, `FLAG_LOCKED_CONTENTS`

#### getContents

    public String getContents()

Get the "contents" of the field.

Returns:
  the value of the contents.

#### setContents

    public void setContents(String value)

Set the "contents" of the field.

Parameters:
  `value` - the value of the contents.

#### getModifiedDate

    public String getModifiedDate()

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

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

#### setModifiedDate

    public void setModifiedDate(String m)

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

Parameters:
  `m` - 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)`

#### setModifiedDate

    public void setModifiedDate(Calendar c)

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

Parameters:
  `c` - the date and time the annotation was created.

#### getAnnotationName

    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:
  The identifying name for the Annotation.

#### setAnnotationName

    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` - The identifying name for the annotation.

#### getStructParent

    public int getStructParent()

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

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

#### setStructParent

    public void setStructParent(int structParent)

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

Parameters:
  `structParent` - The new key for this annotation.

#### getOptionalContent

    public PDPropertyList getOptionalContent()

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

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

#### setOptionalContent

    public void setOptionalContent(PDPropertyList oc)

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

Parameters:
  `oc` - The optional content group or optional content membership dictionary.

#### getBorder

    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:
  the border array, never null.

#### setBorder

    public void setBorder(COSArray borderArray)

This will set the border array.

Parameters:
  `borderArray` - the border array to set.

#### setColor

    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` - colour in the DeviceRGB colourspace

#### getColor

    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:
  Color object representing the colour

#### getColor

    protected PDColor getColor(COSName itemName)

#### setPage

    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` - is the corresponding page

#### getPage

    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:
  The corresponding page or null if not available.

#### constructAppearances

    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` - the related document

#### constructAppearances

    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.