Package com.snowtide.pdf.annot

Class LinkAnnotation

  • All Implemented Interfaces:
    Annotation, DocumentLocation, Bounded
    public class LinkAnnotation
extends Object

    An Annotation implementation that represents a PDF annotation of type Link.

    Link annotations can refer to a particular location within a PDF document or to an external URI (typically used for web hyperlinks). (Other link action types are available within the PDF specification, but they are generally not relevent outside of a graphical PDF viewer such as Acrobat.

    When referring to an external URI, that URI is available through the getURI() function. In addition, if a link annotation has been edited or modified by a Web Capture process, any previous URI value is moved so that it is available through the getPreviousURI() function.

    If getURI() returns null, then a link annotation refers to a location within a PDF document. The page number is indicated by the return value of the DocumentLocation.pageNumber() function; the area that should be shown on that page when the link annotation is activated is given by the getTopBound(), getBottomBound(), getLeftBound(), and getRightBound() functions.

    Since:
    v1.3.5
    Version:
    ©2004-2024 Snowtide

    • Constructor Summary

      Constructors 
      Constructor Description
      LinkAnnotation()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Region bounds()  
      Page getAppearance()
      Returns a Page containing this annotation's rendered "appearance stream", if it explicitly defines one, null otherwise.
      float getBottomBound()
      Returns the y-coordinate on the page to which this link annotation refers where a PDF viewer should position the bottom edge of its window when the link annotation is activated.
      String getContents()
      Returns the text content of this annotation.
      float getLeftBound()
      Returns the x-coordinate on the page to which this link annotation refers where a PDF viewer should position the left edge of its window when the link annotation is activated.
      String getLinkActionName()
      Returns the name of the type of action that this link annotation will perform when a user activates it within a PDF viewer.
      String getModificationDate()
      Returns the date, in PDF date format, when this annotation was last modified.
      String getName()
      Returns the optional name for this annotation, which should uniquely identify it within a page.
      String getPreviousURI()
      Returns the previous URI to which this link annotation referred.
      float getRightBound()
      Returns the x-coordinate on the page to which this link annotation refers where a PDF viewer should position the right edge of its window when the link annotation is activated.
      int getTargetPageNumber()
      Returns the page number to which this link annotation refers.
      float getTopBound()
      Returns the y-coordinate on the page to which this link annotation refers where a PDF viewer should position the top edge of its window when the link annotation is activated.
      String getTypeCd()
      Returns a String indicating what type of annotation this this.
      String getURI()
      Returns the URI to which this link annotation refers; this will be non-null only if this link's annotation action type is 'URI'.
      int pageNumber()
      This page number is 0-indexed, and may be used to retrieve a Page object representing the page's content using the Document#getPage(int) function.

    • Constructor Detail

      • LinkAnnotation

        public LinkAnnotation()

    • Method Detail

      • getPreviousURI

        public String getPreviousURI()

        Returns the previous URI to which this link annotation referred.

        This attribute will be set if a Web Capture process changes the action associated with a link annotation from going to a URI to jumping to a page and location within the PDF document. When this happens, the original URI is set as the 'previous URI' attribute, and can be used as a backup or alternate destination for this link annotation.

      • getLinkActionName

        public String getLinkActionName()

        Returns the name of the type of action that this link annotation will perform when a user activates it within a PDF viewer. PDFxStream supports the following types of link actions:

        • GoTo - refers to a particular page (and perhaps region of a page)
        • URI - opens a URI in the user's browser

        Other link action types are related to the display or manuipulation of multimedia and file data that is only relevant within the context of a graphical PDF viewer. These include:

        GoToR
        GoToE
        Launch
        Thread
        Sound
        Movie
        Hide
        Named
        SubmitForm
        ResetForm
        ImportData
        JavaScript
        SetOCGState
        Rendition
        Trans
        GoTo3DView

      • getTargetPageNumber

        public int getTargetPageNumber()

        Returns the page number to which this link annotation refers. The page number is 0-based, and can be used to access the corresponding page object via the parent Document's Document.getPage(int) method.

        This function will return -1 if no page number is specified for this link or if this link's annotation action type is GoTo.

      • getLeftBound

        public float getLeftBound()

        Returns the x-coordinate on the page to which this link annotation refers where a PDF viewer should position the left edge of its window when the link annotation is activated.

        This function will return -1 if the bound coordinate is unspecified for this link or if this link's annotation action type is GoTo.

      • getRightBound

        public float getRightBound()

        Returns the x-coordinate on the page to which this link annotation refers where a PDF viewer should position the right edge of its window when the link annotation is activated.

        This function will return -1 if the bound coordinate is unspecified for this link or if this link's annotation action type is GoTo.

      • getTopBound

        public float getTopBound()

        Returns the y-coordinate on the page to which this link annotation refers where a PDF viewer should position the top edge of its window when the link annotation is activated.

        This function will return -1 if the bound coordinate is unspecified for this link or if this link's annotation action type is GoTo.

      • getBottomBound

        public float getBottomBound()

        Returns the y-coordinate on the page to which this link annotation refers where a PDF viewer should position the bottom edge of its window when the link annotation is activated.

        This function will return -1 if the bound coordinate is unspecified for this link or if this link's annotation action type is GoTo.

      • getContents

        public String getContents()
        Description copied from interface: Annotation
        Returns the text content of this annotation. Some annotation types do not encode any text content; in such cases, those annotation type implementations will either return null from this function, or return an alternative descriptive text string that may be used to indicate the value or nature of this annotation.
        Specified by:
        getContents in interface Annotation

      • pageNumber

        public int pageNumber()
        Description copied from interface: DocumentLocation
        This page number is 0-indexed, and may be used to retrieve a Page object representing the page's content using the Document.getPage(int) function.

        If a page number is not available for some reason, then this method will return -1.

        Specified by:
        pageNumber in interface DocumentLocation

      • getName

        public String getName()
        Description copied from interface: Annotation
        Returns the optional name for this annotation, which should uniquely identify it within a page.
        Specified by:
        getName in interface Annotation

      • getModificationDate

        public String getModificationDate()
        Description copied from interface: Annotation
        Returns the date, in PDF date format, when this annotation was last modified. This date string may be parsed using the PDFDateParser class. This function may return null if no modification date is present in the annotation data.
        Specified by:
        getModificationDate in interface Annotation

      • getTypeCd

        public String getTypeCd()
        Description copied from interface: Annotation
        Returns a String indicating what type of annotation this this. These types are defined in Section 8.4.5 of the PDF Format Reference, and are returned with a leading forward slash.
        Specified by:
        getTypeCd in interface Annotation

      • getAppearance

        public Page getAppearance()
                   throws IOException
        Description copied from interface: Annotation
        Returns a Page containing this annotation's rendered "appearance stream", if it explicitly defines one, null otherwise. (If an annotation does not define its own appearance explicitly, it is assumed that a PDF reader / consumer will provide a default rendering based on the annotation's type and associated data.) The contents of the page can be accessed and manipulated just like any "regular" page obtained from e.g. Document.getPage(int).
        Specified by:
        getAppearance in interface Annotation
        Throws:
        IOException