Package org.faceless.pdf2

Class PDFAnnotation

    • 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).
        • 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

      • 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. Since 2.26 this method calls getXMP().read(new StringReader(xmldata == null ? "" : xmldata)). We strongly recommend using the getXMP() method and modifying the XMP directly rather than using this method.
        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
        See Also:
        getXMP()

      • getMetaData

        public Reader getMetaData()
                   throws IOException

        Return any XML metadata associated with this object.

        Since 2.26 this simply returns getXMP().isEmpty() ? null : new StringReader(getXMP().toString()). It is strongly recommended that any code migrates to using the getXMP() method.

        Since 2.24.3, the returned type is guaranteed to hava a toString() method that will return the Metadata as a String.

        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

      • getXMP

        public XMP getXMP()
        Return an XMP Metadata object representing any XML metadata associated with this object
        Returns:
        the XMP, which may be empty or invalid but will never be null
        Since:
        2.26

      • 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

      • 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" 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

      • 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

      • 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

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

      • 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<PDFAnnotation> l = page.getAnnotations();
 while (!l.isEmpty()) {
   l.get(l.size() - 1).flatten();
 }
        Since:
        2.11.19
        See Also:
        FormElement.flatten(), Form.flatten()

      • setLocale

        public void setLocale​(Locale locale)
        Set the Locale on this annotation. The locale property (really the Language property, but Locale is consistant with PDF#setLocale) on a PDFAnnotation is new in PDF 2.0
        Since:
        2.24.2

      • getLocale

        public Locale getLocale()
        Get the Locale on this annotation, as set by setLocale(java.util.Locale). The ability for an annotation to have a Locale is new in PDF 2.0
        Returns:
        the annotation locale, or PDF.LOCALEROOT if none is set
        Since:
        2.24.2

      • putUserData

        public void putUserData​(String key,
                        Object value)
        Set a custom property on the PDF. The property will be saved with the file with the "BFOO_" prefix.
        Parameters:
        value - a CharSequence, Number, Date, Calendar, Boolean, byte[], or a List/Map of those values, or null to remove the property
        Since:
        2.24.2

      • getUserData

        public Object getUserData​(String key)
        Return a property previously set on the PDF with the putUserData() method
        Returns:
        a String, Boolean, Number, Calendar, byte[] or a Map/List of those values if found, or null if no such property exists.
        Since:
        2.24.2

      • getDefaultColorSpace

        public ColorSpace getDefaultColorSpace​(int components)

        Return the ColorSpace used by this annotation to anchor device-dependent colors to a profile. For example, the ColorSpace returned by getDefaultColorSpace(3) is used by all "Device RGB" colors on the annotation, effectively turning them into calibrated colors.

        Annotations do not inherit any default ColorSpace set on the page.

        Parameters:
        components - identifies the Default ColorSpace we're requesting - valid values are 1 for Gray, 3 for RGB or 4 for CMYK.
        Returns:
        the Default ColorSpace requested, or null if none is set.
        Since:
        2.26.1
        See Also:
        PDFPage.getDefaultColorSpace(int)

      • setDefaultColorSpace

        public void setDefaultColorSpace​(int components,
                                 ColorSpace cs)
        Set the ColorSpace to use to anchor device-dependent colors on this annotation, as described by getColorSpace(java.lang.String).
        Parameters:
        components - identifies the Default ColorSpace to set - valid values are 1 for Gray, 3 for RGB or 4 for CMYK.
        cs - the ColorSpace to set, which must be either null (to delete the existing value) or a ColorSpace of a type that matches the "components" parameter.
        Since:
        2.26.1

      • toString

        public String toString()

      • putLiteral

        public void putLiteral​(String key,
                       String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.