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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 value of the "Contents" property of this annotation, 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<PDFAnnotation>` | `getReplies()` Get an unmodifiable List of `PDFAnnotation` objects that are in reply to this Annotation.
    `List<PDFAnnotation>` | `getReviews()` Get an unmodifiable List of `PDFAnnotation` 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` | `rebuild()` Rebuild the annotation's appearance.
    `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" value of this annotation, which is required for "note" annotations and when making annotations accessible.
    `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)`

    - #### 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

    - #### 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" value of this annotation, which is required for "note" annotations and when making annotations accessible. For note annotations, this is the contents of the 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 value of the "Contents" property of this annotation, 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

    - #### rebuild

          public void rebuild()

      Rebuild the annotation's appearance. This will be done automatically when required, usually just before saving the PDF or rasterizing it to a bitmap. However this method can be called explicitly if necessary, usually to ensure the rebuild (which may fire a `PropertyChangeEvent`) is run on a specific thread.
      Since:
        2.11.26

    - #### 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<PDFAnnotation> getReplies()

      Get an unmodifiable List of `PDFAnnotation` 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 `PDFAnnotation` objects - although the specification allows for any type of annotation to be used as a reply, in general 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 `PDFAnnotation` 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<PDFAnnotation> getReviews()

      Get an unmodifiable List of `PDFAnnotation` 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 `PDFAnnotation` 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 `PDFAnnotation` 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()`

    - #### 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-2015 Big Faceless Organization