|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.PDFAnnotation
public class PDFAnnotation
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.
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 |
---|
public String getType()
AnnotationNote
s), "Link",
(for AnnotationLink
s), "Stamp" (for AnnotationStamp
s), "Widget"
(for WidgetAnnotation
s), "Highlight", "Underline", "Squiggly" or "StrikeOut"
(for AnnotationMarkup
s), "FreeText" (for AnnotationText
s), "FileAttachment"
(for AnnotationFile
s) 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.
public void setRectangle(float x1, float y1, float x2, float y2)
AnnotationLink
and AnnotationStamp
annotations, this is
the rectangle containing the hyperlink area or stamp.AnnotationNote
annotations, whether this method adjusts the location
of the icon or the popup window depends on whether the annotation is closed or open
at the time of the call to this method. When closed, the icon is positioned at x1,y2
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.
x1
- the X co-ordinate of the bottom-left corner of the rectangley1
- the Y co-ordinate of the bottom-left corner of the rectanglex2
- the X co-ordinate of the top-right corner of the rectangley2
- the Y co-ordinate of the top-right corner of the rectanglepublic PDFAnnotation getPopup()
public float[] getRectangle()
setRectangle()
method for a discussion on units.
setRectangle(float, float, float, float)
public PDFPage getPage()
null
if it a new annotation which has not yet been placed on a page
public void setPage(PDFPage page)
PDFPage.getAnnotations()
.add()
public void setVisible(boolean visible)
visible
- whether the annotation should be displayed on the screenpublic void setPrintable(boolean printable)
printable
- whether the annotation should be printedpublic 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
public boolean isVisible()
public boolean isPrintable()
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.
setReadOnly(boolean)
,
FormElement.isReadOnly()
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
position
- whether to lock the size/position of the annotationcontent
- whether to lock the content of the annotationpublic boolean isPositionLocked()
public boolean isContentLocked()
public void setMetaData(String metadata)
PDF.setMetaData(java.lang.String)
for more information.
metadata
- the XML data to embed into the document, or null to clear any existing metadata. No validation is performed on this input.public Reader getMetaData() throws IOException
PDF.getMetaData()
for more information
Reader
containing the source of the XML or null if no metadata is available.
IOException
- if the metadata can't be extractedpublic Calendar getModifyDate()
null
otherwise.
getLastModified
public void setModifyDate(Calendar date)
date
- the Date to set the modification date topublic Calendar getCreationDate()
null
otherwise.
public void setCreationDate(Calendar date)
date
- the Date to set the creation date topublic void setSubject(String subject)
AnnotationLink
and WidgetAnnotation
) this has no effect
subject
- a brief summary of the contents of the annotationpublic String getSubject()
setSubject(java.lang.String)
public void setInReplyTo(PDFAnnotation annotation)
AnnotationLink
andWidgetAnnotation
) this has no effect
annotation
- the annotation this is in reply to, or null
to remove
the current valuepublic PDFAnnotation getInReplyTo()
null
if this annotation is not in reply to anything.
public void setUniqueID(String id)
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.
id
- the unique ID to assign to this annotationpublic String getUniqueID()
public void setAuthor(String label)
AnnotationLink
and WidgetAnnotation
) this has no effect
public String getAuthor()
setAuthor(java.lang.String)
Note prior to version 2.3.7 this method existed, but only on certain subclasses.
public void setContents(String contents)
contents
- the contents of the window - may contain newline and non-ASCII
Unicode characters.public String getContents()
setContents(java.lang.String)
public void setColor(Color color)
Color
of the annotation. This color will be used
for the following purposes:
public Color getColor()
Color
of the annotation as set by setColor(java.awt.Color)
, or
null
if not set.
public void setOpacity(int opacity)
AnnotationLink
and WidgetAnnotation
) this has no effect
Note this setting will be ignored by Acrobat 4.0 and earlier.
opacity
- the opacity of the annotation from 0 to 100public int getOpacity()
setOpacity(int)
public AnnotationNote addReview(String name, String status)
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
name
- the name of the person doing the reviewstatus
- the status of the review - must be one of those listed for
the AnnotationNote.setStatus(java.lang.String)
method, or an IllegalArgumentException
is thrown.
null
if none was createdpublic List getReplies()
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.
getReplies()
,
setInReplyTo(org.faceless.pdf2.PDFAnnotation)
public List getReviews()
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.
getReplies()
,
setInReplyTo(org.faceless.pdf2.PDFAnnotation)
,
addReview(java.lang.String, java.lang.String)
,
AnnotationNote.getStatus()
public boolean hasAppearanceState(String state)
state
- the state to check - "N" for normal, "D" for down or "R" for rolloverpublic void addPropertyChangeListener(PropertyChangeListener l)
FormElement.addPropertyChangeListener(java.beans.PropertyChangeListener)
,
PDFPage.addPropertyChangeListener(java.beans.PropertyChangeListener)
public void removePropertyChangeListener(PropertyChangeListener l)
removePropertyChangeListener(java.beans.PropertyChangeListener)
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(); }
FormElement.flatten()
,
Form.flatten()
public String toString()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |