Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.faceless.pdf2
Class PDFAnnotation

    java.lang.Object
      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 `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.

  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).
  - For `AnnotationLink` and `AnnotationStamp` annotations, this is the rectangle containing the hyperlink area or stamp.
  - For `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.

  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` and`WidgetAnnotation`) 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:
  - The background of the annotation's icon when closed, if applicable
  - The title bar of the annotation's pop-up window
  - The border of a link annotation

  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()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2012 Big Faceless Organization