org.faceless.pdf2
Class PDFAnnotation

java.lang.Object
  extended by org.faceless.pdf2.PDFAnnotation
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
AnnotationFile, AnnotationLink, AnnotationMarkup, AnnotationNote, AnnotationRichMedia, AnnotationShape, AnnotationSound, AnnotationStamp, AnnotationText, WidgetAnnotation

public class PDFAnnotation
extends Object

A PDFAnnotation allows the user to interact with the generated PDF document, by adding / viewing rubber-stamps, popup notes hyperlinks and so on. A special subclass of annotation, called a Widget, is also used to display FormElement objects on the page. Since version 2.0, the various types of annotation have been split into unique subclasses. This class contains the methods that are common to all of them.

Since:
1.1

Method Summary
 void addPropertyChangeListener(PropertyChangeListener l)
          Add a PropertyChangeListener to this PDFAnnotation.
 AnnotationNote addReview(String name, String status)
          Add a review to this annotation.
 void flatten()
           Stamp the visible appearance of this annotation permanently onto its page, and remove the annotation from the page.
 String getAuthor()
          Return the author (or "Label") of the annotation if set, as set by setAuthor(java.lang.String) Note prior to version 2.3.7 this method existed, but only on certain subclasses.
 Color getColor()
          Return the Color of the annotation as set by setColor(java.awt.Color), or null if not set.
 String getContents()
          Return the contents of the notes' pop-up window, as set by setContents(java.lang.String)
 Calendar getCreationDate()
          Return the date when the annotation was first created if specified, or null otherwise.
 PDFAnnotation getInReplyTo()
          Return the PDFAnnotation that this annotation is in reply to, or null if this annotation is not in reply to anything.
 Reader getMetaData()
          Return any XML metadata associated with this object.
 Calendar getModifyDate()
          Return the date when the annotation was last modified if specified, or null otherwise.
 int getOpacity()
          Return the opacity of this annotation, as set by setOpacity(int)
 PDFPage getPage()
          Return the page that this annotation is on, or null if it a new annotation which has not yet been placed on a page
 PDFAnnotation getPopup()
          Return the Popup annotation for this annotation.
 float[] getRectangle()
          Return the rectangle this annotation applies to on the page, or null if no rectangle applies for this type of annotation.
 List getReplies()
          Get an unmodifiable List of AnnotationNote objects that are in reply to this Annotation.
 List getReviews()
          Get an unmodifiable List of AnnotationNote objects that are reviews of this Annotation.
 String getSubject()
          Get the subject of the annotation, as set by setSubject(java.lang.String)
 String getType()
          Return the type of annotation.
 String getUniqueID()
          Return the unique ID for this annotation, if set.
 boolean hasAppearanceState(String state)
          Return true if this annotation has an appearance for the specified state.
 boolean isContentLocked()
          Returns whether the content of the annotation is locked
 boolean isPositionLocked()
          Returns whether the size and position of the annotation is locked
 boolean isPrintable()
          Returns whether the annotation is included when the document is printed (true) or not (false)
 boolean isReadOnly()
           Return whether the annotation to "read-only".
 boolean isVisible()
          Returns whether the annotation is visible on the screen (true) or not (false)
 void removePropertyChangeListener(PropertyChangeListener l)
          Remove a previously added PropertyChangeListener from this PDFAnnotation.
 void setAuthor(String label)
          Set the author of the annotation.
 void setColor(Color color)
          Set the Color of the annotation.
 void setContents(String contents)
          Set the contents pop-up window displayed when the annotation is open.
 void setCreationDate(Calendar date)
          Set the date when the annotation was created.
 void setInReplyTo(PDFAnnotation annotation)
          Set which annotation this annotation is in reply to.
 void setLocked(boolean position, boolean content)
           Set the annotation to be "locked".
 void setMetaData(String metadata)
          Set the XML metadata associated with this object.
 void setModifyDate(Calendar date)
          Set the date when the annotation is last modified.
 void setOpacity(int opacity)
          Set the opacity of this annotation.
 void setPage(PDFPage page)
          Set the page for this annotation.
 void setPrintable(boolean printable)
          Set whether the annotation is included when the document is printed.
 void setReadOnly(boolean readonly)
           Set the annotation to "read-only", or not.
 void setRectangle(float x1, float y1, float x2, float y2)
          Set the rectangle for the annotation - where it is on the page.
 void setSubject(String subject)
          Set the subject of the annotation.
 void setUniqueID(String id)
          Set the unique ID for this annotation.
 void setVisible(boolean visible)
          Set whether the annotation is visible on screen.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getType

public String getType()
Return the type of annotation. Could be one of "Text" (for AnnotationNotes), "Link", (for AnnotationLinks), "Stamp" (for AnnotationStamps), "Widget" (for WidgetAnnotations), "Highlight", "Underline", "Squiggly" or "StrikeOut" (for AnnotationMarkups), "FreeText" (for AnnotationTexts), "FileAttachment" (for AnnotationFiles) or "Line", "Square", "Circle", "Polygon", "Polyline", "Caret", "Ink", "Popup", "Sound", "Movie", "Screen", "PrinterMark" or "TrapNet", all of which only have only basic support with this API.

Since:
1.1.12

setRectangle

public void setRectangle(float x1,
                         float y1,
                         float x2,
                         float y2)
Set the rectangle for the annotation - where it is on the page. Every annotation must have a rectangle set - if it's not set when the document is written, it's forced to (0,0,0,0).

Note that all co-ordinates are in absolute page co-ordinates. This means they are measured in points from the bottom-left hand corner of the page, regardless of any calls to PDFPage.rotate(float, float, double) or PDFPage.setUnits(float, int) that have been made. This restriction is part of the PDF specification.

Parameters:
x1 - the X co-ordinate of the bottom-left corner of the rectangle
y1 - the Y co-ordinate of the bottom-left corner of the rectangle
x2 - the X co-ordinate of the top-right corner of the rectangle
y2 - the Y co-ordinate of the top-right corner of the rectangle

getPopup

public PDFAnnotation getPopup()
Return the Popup annotation for this annotation.

Since:
2.8

getRectangle

public float[] getRectangle()
Return the rectangle this annotation applies to on the page, or null if no rectangle applies for this type of annotation. See the setRectangle() method for a discussion on units.

Returns:
the rectangle for this annotation, in the form of an array (x1, y1, x2, y2)
Since:
1.1.12
See Also:
setRectangle(float, float, float, float)

getPage

public PDFPage getPage()
Return the page that this annotation is on, or null if it a new annotation which has not yet been placed on a page

Since:
1.1.23

setPage

public void setPage(PDFPage page)
Set the page for this annotation. This is useful when moving annotations between documents or across pages - when simply adding a new annotation to a page, this method is identical to calling PDFPage.getAnnotations().add()

Since:
1.1.23

setVisible

public void setVisible(boolean visible)
Set whether the annotation is visible on screen. By default, all new annotations are visible.

Parameters:
visible - whether the annotation should be displayed on the screen
Since:
1.1.23

setPrintable

public void setPrintable(boolean printable)
Set whether the annotation is included when the document is printed. By default, all new annotations (except for hyperlinks) are printed.

Parameters:
printable - whether the annotation should be printed
Since:
1.1.23

setReadOnly

public void setReadOnly(boolean readonly)

Set the annotation to "read-only", or not. Read-only annotations cannot be moved or deleted and do not respond to mouse clicks in Acrobat

Additionally, using Acrobat there is no way to change this flag, so fields set to read-only using this method will basically stay that way unless edited with an API like this one. This makes this setting useful for placing "permanent" annotations on a page.

Note this value is ignored for WidgetAnnotation objects - see the FormElement.setReadOnly(boolean) method instead

Since:
2.0

isVisible

public boolean isVisible()
Returns whether the annotation is visible on the screen (true) or not (false)

Since:
1.1.23

isPrintable

public boolean isPrintable()
Returns whether the annotation is included when the document is printed (true) or not (false)

Since:
1.1.23

isReadOnly

public boolean isReadOnly()

Return whether the annotation to "read-only". Read-only annotations cannot be moved or deleted and do not respond to mouse clicks in Acrobat.

Note this value is ignored for WidgetAnnotation objects - see the FormElement.isReadOnly() method instead.

Since:
2.0
See Also:
setReadOnly(boolean), FormElement.isReadOnly()

setLocked

public void setLocked(boolean position,
                      boolean content)

Set the annotation to be "locked". It's possible to lock the size and position of the annotation, the content, or both - although locking the content is only supported in Acrobat 8 or later

Parameters:
position - whether to lock the size/position of the annotation
content - whether to lock the content of the annotation
Since:
2.11.4

isPositionLocked

public boolean isPositionLocked()
Returns whether the size and position of the annotation is locked

Since:
2.11.4

isContentLocked

public boolean isContentLocked()
Returns whether the content of the annotation is locked

Since:
2.11.4

setMetaData

public void setMetaData(String metadata)
Set the XML metadata associated with this object. See PDF.setMetaData(java.lang.String) for more information.

Parameters:
metadata - the XML data to embed into the document, or null to clear any existing metadata. No validation is performed on this input.
Since:
2.11.5

getMetaData

public Reader getMetaData()
                   throws IOException
Return any XML metadata associated with this object. See the PDF.getMetaData() for more information

Returns:
a Reader containing the source of the XML or null if no metadata is available.
Throws:
IOException - if the metadata can't be extracted
Since:
2.11.5

getModifyDate

public Calendar getModifyDate()
Return the date when the annotation was last modified if specified, or null otherwise.

Since:
2.0 - prior to that this method was called getLastModified

setModifyDate

public void setModifyDate(Calendar date)
Set the date when the annotation is last modified. This is updated automatically when the annotation is modified, so there's no need to call this unless you need to set it to a specific value.

Parameters:
date - the Date to set the modification date to
Since:
2.7.1

getCreationDate

public Calendar getCreationDate()
Return the date when the annotation was first created if specified, or null otherwise.

Since:
2.0

setCreationDate

public void setCreationDate(Calendar date)
Set the date when the annotation was created. This is set automatically when an annotation is created, so there's no need to call this method unless you need to set it to a specific value.

Parameters:
date - the Date to set the creation date to
Since:
2.7.1

setSubject

public void setSubject(String subject)
Set the subject of the annotation. This is an Acrobat 6.0 feature only, but will safely be ignored by earlier viewers. For some annotations (including AnnotationLink and WidgetAnnotation) this has no effect

Parameters:
subject - a brief summary of the contents of the annotation
Since:
2.0

getSubject

public String getSubject()
Get the subject of the annotation, as set by setSubject(java.lang.String)

Since:
2.0

setInReplyTo

public void setInReplyTo(PDFAnnotation annotation)
Set which annotation this annotation is in reply to. This is an Acrobat 6 or later only feature, although it will safely be ignored by earlier viewers. The two annotations must be on the same page to be related like this - if they're not, this annotation will be moved to the page of it's reply. For some annotations (including AnnotationLink andWidgetAnnotation) this has no effect

Parameters:
annotation - the annotation this is in reply to, or null to remove the current value
Since:
2.0

getInReplyTo

public PDFAnnotation getInReplyTo()
Return the PDFAnnotation that this annotation is in reply to, or null if this annotation is not in reply to anything.

Since:
2.0

setUniqueID

public void setUniqueID(String id)
Set the unique ID for this annotation. See the getUniqueID() method for more information. Note that it is down to the user to ensure that the unique ID generated is actually unique. Since 2.3.7 all new annotations have a random unique ID generated when created.

Parameters:
id - the unique ID to assign to this annotation
Since:
2.0.8

getUniqueID

public String getUniqueID()
Return the unique ID for this annotation, if set. This is the "NM" field, added as an optional attribute in Acrobat 5.0, and is usually in the form of a 15-30 random characters. If no unique ID is set, this method returns null.

Since:
2.0.8

setAuthor

public void setAuthor(String label)
Set the author of the annotation. This is also sometimes referred to as the Label. Note prior to version 2.3.7 this method existed, but only on certain subclasses. For some annotations (including AnnotationLink and WidgetAnnotation) this has no effect

Since:
2.3.7

getAuthor

public String getAuthor()
Return the author (or "Label") of the annotation if set, as set by setAuthor(java.lang.String) Note prior to version 2.3.7 this method existed, but only on certain subclasses.

Since:
2.3.7

setContents

public void setContents(String contents)
Set the contents pop-up window displayed when the annotation is open.

Parameters:
contents - the contents of the window - may contain newline and non-ASCII Unicode characters.
Since:
2.3.7

getContents

public String getContents()
Return the contents of the notes' pop-up window, as set by setContents(java.lang.String)

Since:
2.3.7

setColor

public void setColor(Color color)
Set the Color of the annotation. This color will be used for the following purposes:

Since:
2.3.7

getColor

public Color getColor()
Return the Color of the annotation as set by setColor(java.awt.Color), or null if not set.

Since:
2.3.7

setOpacity

public void setOpacity(int opacity)
Set the opacity of this annotation. A value of 100 (the default) means the annotation is completely opaque, a value of 0 means completely invisible. For some annotations (including AnnotationLink and WidgetAnnotation) this has no effect Note this setting will be ignored by Acrobat 4.0 and earlier.

Parameters:
opacity - the opacity of the annotation from 0 to 100
Since:
2.3.7

getOpacity

public int getOpacity()
Return the opacity of this annotation, as set by setOpacity(int)

Returns:
the opacity of the annotation
Since:
2.3.7

addReview

public AnnotationNote addReview(String name,
                                String status)
Add a review to this annotation. See the getReviews() method for a more complete discussion of annotation reviews. This method is a convenient way of creating a new AnnotationNote, setting it's status and author, and marking it as in reply to this annotation. For some annotations (including AnnotationLink and WidgetAnnotation), this method will have no effect and will return null

Parameters:
name - the name of the person doing the review
status - the status of the review - must be one of those listed for the AnnotationNote.setStatus(java.lang.String) method, or an IllegalArgumentException is thrown.
Returns:
the AnnotationNote that was created, or null if none was created
Since:
2.4

getReplies

public List getReplies()
Get an unmodifiable List of AnnotationNote objects that are in reply to this Annotation.

Since Acrobat 6.0 it has been possible to add "replies" to another annotation. These replies are actually AnnotationNote objects - although the specification allows for any type of annotation to be used as a reply, in practice only AnnotationNote objects are used. These annotations have the same physical location as the original one, but return a value from getInReplyTo(). Unlike those returned by getReviews(), they have a AnnotationNote.getStatus() equal to null.

The list returned by this method is a convenient way of doing the following: Loop over all annotations on the same page as this one, and return any AnnotationNote objects in reply to this one that have AnnotationNote.getStatus() equal to null.

Note the returned list is unmodifiable - if you want to remove a reply, delete it from it's pages list of annotations.

Returns:
an unmodifiable List containing all the replies to this annotation
Since:
2.4
See Also:
getReplies(), setInReplyTo(org.faceless.pdf2.PDFAnnotation)

getReviews

public List getReviews()
Get an unmodifiable List of AnnotationNote objects that are reviews of this Annotation.

Since Acrobat 6.0 it has been possible to "review" another annotation by setting it's status to "Accepted", "Rejected", "Cancelled" or "Completed". It's also possible to "Mark" or "Unmark" an annotation (in Acrobat, this appears as a checkbox next to the annotation)

These "reviews" are actually a collection of AnnotationNote objects which are attached to the original annotation, very similar to the Replies as returned by getReplies(). The only different is that they have a "State" set, which you can see using the AnnotationNote.getStatus() method.

The list returned from this method is a convenient way of doing the following: Loop over all annotations on the same page as this one, and return any AnnotationNote objects in reply to this one, or one of it's other reviews, that have AnnotationNote.getStatus() set to a non-null value.

Returns:
an unmodifiable List containing all the Reviews of this annotation
Since:
2.4
See Also:
getReplies(), setInReplyTo(org.faceless.pdf2.PDFAnnotation), addReview(java.lang.String, java.lang.String), AnnotationNote.getStatus()

hasAppearanceState

public boolean hasAppearanceState(String state)
Return true if this annotation has an appearance for the specified state.

Parameters:
state - the state to check - "N" for normal, "D" for down or "R" for rollover
Since:
2.10.3

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Add a PropertyChangeListener to this PDFAnnotation. PropertyChangeEvents will be raised when various aspects of this annotation are changed

Since:
2.10.4
See Also:
FormElement.addPropertyChangeListener(java.beans.PropertyChangeListener), PDFPage.addPropertyChangeListener(java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Remove a previously added PropertyChangeListener from this PDFAnnotation.

Since:
2.10.4
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener)

flatten

public void flatten()

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 a ConcurrentModificationException if you were iterating over the page's annotations. To flatten all the annotations on a page we'd recommend something like this:

  List l = page.getAnnotations();
  while (l.size() > 0) {
    ((PDFAnnotation)l.get(l.size() - 1)).flatten();
  }
 

Since:
2.11.19
See Also:
FormElement.flatten(), Form.flatten()

toString

public String toString()


Copyright © 2001-2012 Big Faceless Organization