Package org.faceless.pdf2

Class PDFAction

    • Field Detail

      • METHOD_HTTP_IMAGEMAP_POST

        public static final int METHOD_HTTP_IMAGEMAP_POST
        Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as a standard HTTP POST, in the same way as an HTML form. The co-ordinates where the submit button was clicked are included in the submission as name.x and name.y, where name is the name of the submit button that was clicked.
        See Also:
        Constant Field Values

      • METHOD_XML_WITH_ALL_ANNOTATIONS

        public static final int METHOD_XML_WITH_ALL_ANNOTATIONS
        Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as XFDF XML, and that it should include all the annotations in the document. This method requires PDF 1.4 (Acrobat 5.0) or later.
        Since:
        2.11.7
        See Also:
        Constant Field Values

      • METHOD_FDF_WITH_ALL_ANNOTATIONS

        public static final int METHOD_FDF_WITH_ALL_ANNOTATIONS
        Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted in the Adobe Forms Data Format, and that it should include all the annotations in the document. This method requires PDF 1.4 (Acrobat 5.0) or later.
        See Also:
        Constant Field Values

      • METHOD_FDF_WITH_MY_ANNOTATIONS

        public static final int METHOD_FDF_WITH_MY_ANNOTATIONS
        Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted in the Adobe Forms Data Format, and that it should include any annotations that have been created by the "current user". The spec is a bit vague on how the current user is determined, but we include this method for completeness. This method requires PDF 1.4 (Acrobat 5.0) or later.
        See Also:
        Constant Field Values

      • METHOD_FLAG_CANONICALDATES

        public static final int METHOD_FLAG_CANONICALDATES
        Flag that can be added to the method passed to formSubmit(java.lang.String, int) to specify that all dates should be submitted in "canonical" D:YYYYMMDDHHMMSS format
        Since:
        2.11.7
        See Also:
        Constant Field Values

      • METHOD_FLAG_EMPTYFIELDS

        public static final int METHOD_FLAG_EMPTYFIELDS
        Flag that can be added ot the method passed to formSubmit(java.lang.String, int) tp specify that values for empty fields should be submitted as well. By default this is not the case
        Since:
        2.11.7
        See Also:
        Constant Field Values

    • Method Detail

      • goTo

        public static PDFAction goTo​(PDFPage page)
        Return a new PDFAction which jumps to the specified page in the PDF document. The position and zoom on the new page is the same as that of the original page.
        Parameters:
        page - the page this action should jump to

      • goTo

        public static PDFAction goTo​(Element elt,
                             float x,
                             float y,
                             float zoom)
        Return a new PDFAction which jumps to the page containing the specified element from the StructureTree. This is a PDF 2.0 feature.
        Parameters:
        elt - the element to jump to, which must be
        x - the X position on the new page to scroll to, or Float.NaN to keep the X position unchanged.
        y - the Y position on the new page to scroll to, or Float.NaN to keep the Y position unchanged.
        zoom - The zoom level. A value of 0 or Float.NaN leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.
        Since:
        2.24.2

      • goToEmbedded

        public static PDFAction goToEmbedded​(String path,
                                     int page,
                                     float x,
                                     float y,
                                     float zoom)

        Create an "embedded" link. This links to a location in another PDF file, which is presumed to be either embedded in this file, or (if this link is part of a PDF that is itself embedded), to a location in an ancestor PDF or one if its embedded files. Those locations may optionally contain a URL fragment, which - if present - refers to a named action in the NamedActions tree of the specified file. If specified, The opened page will be the one containing that element and the "page" parameter is ignored.

        Some examples: 

         "a.pdf"             // Link to file "a.pdf" embedded in this PDF
 "a+b.pdf"           // Link to file "a b.pdf" embedded in this PDF (the fragment is URL encoded)
 "a%2Bb.pdf"           // Link to file "a+b.pdf" embedded in this PDF (the fragment is URL encoded)
 "a.pdf/b.pdf"       // Link to file "b.pdf" embedded in "a.pdf", which is embedded in this PDF.
 "a.pdf/b.pdf#body"  // As above, but ignore "page" and run the named action "body".
 ".."                // Link to the parent PDF that embeds this PDF.
 "../a.pdf"          // Link to the file "a.pdf" which is embdded as a sibling of this PDF.
        Parameters:
        path - the relative "path" to the file.
        page - the page number to open: 0 for the first page. Ignored if "path" contains a fragment
        x - the X position on the new page to scroll to, or Float.NaN to keep the X position unchanged.
        y - the Y position on the new page to scroll to, or Float.NaN to keep the Y position unchanged.
        zoom - The zoom level. A value of 0 or Float.NaN leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.
        Since:
        2.24.3
        See Also:
        fromPath(java.lang.String, org.faceless.pdf2.PDF)

      • fromPath

        public static PDFAction fromPath​(String fullpath,
                                 PDF pdf)

        Create an action based on a full-path consisting of:

        • an optional path to an embedded file: a list of zero or more path segments separated by the "/" character
        • an optional "#" character followed by a PDF fragment, as described in Annex O of the PDF Reference and also online: a list of one or more fragment segments separated by the "&" character

        Parsing of this full-path follows these rules:

        • If the path is not specified the fragment refers to this PDF and the pdf parameter is required, otherwise it's recommended if, and only if the PDF has a EmbeddedFile map that corresponds to path. If no pdf parameter is supplied, the path will not be verified
        • Path segments are the name of a file in the EmbeddedFile map, ".." (meaning the parent file), or the syntax [page,annotation] where page is the page index (starting at 0) and annotation is the annotation index (starting at 0) or its unique-id
        • Fragment segments that are unknown, unsupported or syntactically-invalid are ignored
        • If the full-path can be verified as invalid (for example it refers to a non-existant embedded file, or the file exists but the page or named-action is invalid), an IllegalArgumentException is thrown

        Some examples: 

         #name=x               // the named action "x". Identical to pdf.getNamedActions().get("x")
 #page=1&zoom=1,0,0    // the top of the first page. Identical to PDFAction.goTo(pdf.getPages(0), 0, 0, 1)
 #structelem=x         // the structure element "x". Identical to PDFAction.goTo(pdf.getStructureTree().getElementById("x"), NaN, NaN, NaN)
 file.pdf              // the embedded file "file.pdf". Identical to PDFAction.goToEmbedded("file.pdf", 0, NaN, NaN, NaN)
 #ef=file.pdf          // identical to the previous example
 file.pdf#nameddest=x  // the named action "x" in the embedded file "file.pdf". Identical to PDFAction.goToEmbedded("file.pdf#x", 0, NaN, NaN, NaN)
 [1,0]#nameddest=x     // the named action "x" in the embedded file found on the first AnnotationFile on the second PDFPage
        Parameters:
        fullpath - the path and fragment as described above
        pdf - the PDF this action is going to be applied to, or null
        Returns:
        the action, which will never be null.
        Throws:
        IllegalArgumentException - if the path refers to an action that is invalid
        Since:
        2.29

      • toEmbedded

        public PDFAction toEmbedded​(String path)
        If this action is a GoTo type action, return an equivalent GoToE(mbedded) action to use if the PDF was embedded at the specified path. For non-GoTo actions, returns this. If the GoToE action cannot be parsed, return null
        Parameters:
        path - the path the PDF containing this action would be embedded as.
        Returns:
        the described action
        Since:
        2.26

      • getEmbeddedFile

        public EmbeddedFile getEmbeddedFile​(int distance)
                             throws IOException
        For GoToE and Launch actions that refer to an EmbeddedFile, return the EmbeddedFile they refer to. Warning: if the target file is nested within one or more layers of EmbeddedFile, each of those will have to be parsed as a PDF in order to retrieve the file. This "expansion" may be expensive! The distance property controls how many steps from the current PDF this expansion will happen for - if more PDFs need to be expanded after that, an UnsupportedOperationException is thrown. A value of 0 will not expand any new PDF objects within an EmbeddedFile.
        Parameters:
        distance - the number of steps from this PDF to expand any PDFs required to evaluate this action, before throwing an UnsupportedOperationException.
        Returns:
        the EmbeddedFile referred to by this action, or null if the path to that file is invalid, cnnot be resolved, or if this action type does not refer to an EmbeddedFile
        Throws:
        UnsupportedOperationException - if an EmbeddedFile would need to be converted to PDF to retrieve this value and expand is false
        IOException - if an IOException was encountered expanding a PDF
        Since:
        2.29
        See Also:
        EmbeddedFile.hasPDF(), EmbeddedFile.getPDF(), fromPath(java.lang.String, org.faceless.pdf2.PDF)

      • goTo

        public static PDFAction goTo​(PDFPage page,
                             float x,
                             float y,
                             float zoom)
        Return a new PDFAction which jumps to the specified page in the PDF document, at the specified x, y and zoom level.
        Parameters:
        page - the page this action should jump to.
        x - the X position on the new page to scroll to, or Float.NaN to keep the X position unchanged.
        y - the Y position on the new page to scroll to, or Float.NaN to keep the Y position unchanged.
        zoom - The zoom level. A value of 0 or Float.NaN leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.

      • goToFit

        public static PDFAction goToFit​(PDFPage page)
        Return a new PDFAction which jumps to the specified page in the PDF document. The zoom level is set so that the entire page fits within the viewers window.
        Parameters:
        page - the page this action should jump to

      • goToFitWidth

        public static PDFAction goToFitWidth​(PDFPage page,
                                     float y)
        Return a new PDFAction which jumps to the specified page in the PDF document. The zoom level is set so that the width of the page fits within the viewers window.
        Parameters:
        page - the page this action should jump to
        y - if the page is too tall to fit in the windows, the Y position on the new page to scroll to.

      • goToFitHeight

        public static PDFAction goToFitHeight​(PDFPage page,
                                      float x)
        Return a new PDFAction which jumps to the specified page in the PDF document. The zoom level is set so that the full height of the page fits within the viewers window.
        Parameters:
        page - The page this action should jump to.
        x - if the page is too wide to fit in the windows, the X position on the new page to scroll to.

      • goToFitRectangle

        public static PDFAction goToFitRectangle​(PDFPage page,
                                         float x1,
                                         float y1,
                                         float x2,
                                         float y2)
        Return a new PDFAction which jumps to the specified page in the PDF document. The zoom level is set so that the rectangle specified fills the screen
        Parameters:
        page - the page this action should jump to
        x1 - the left edge of the visible rectangle
        y1 - the bottom edge of the visible rectangle
        x2 - the right edge of the visible rectangle
        y2 - the top edge of the visible rectangle

      • goToURL

        public static PDFAction goToURL​(URL url)
        Return a new PDFAction which jumps to the specified URL.
        Parameters:
        url - the URL
        Since:
        1.1

      • goToURL

        public static PDFAction goToURL​(String url)
        Return a new PDFAction which jumps to the specified URL.
        Parameters:
        url - the URL as a String
        Since:
        2.16

      • goToURL

        public static PDFAction goToURL​(URL url,
                                boolean isImageMap)
        Return a new PDFAction which jumps to the specified URL. When used from a PDFAnnotation, the annotation rectangle is treated as a Server-Side ImageMap. So for example, if the user clicks 20 points from the left and 30 points from the top of the link rectangle, the URL that is loaded is http://www.url.com/?20,30.
        Parameters:
        url - the URL
        isImageMap - true if the URL is an imagemap
        Since:
        1.1

      • goToURL

        public static PDFAction goToURL​(URI uri,
                                boolean isImageMap)
        Return a new PDFAction which jumps to the specified URI. Identical to goToURL(URL, boolean) except it takes a java.net.URI
        Since:
        2.6.12

      • goToRemote

        public static PDFAction goToRemote​(String filename,
                                   int pagenumber,
                                   float x,
                                   float y,
                                   float zoom)
        As for goTo(org.faceless.pdf2.PDFPage), but returns a new PDFAction which moves to a page in another PDF. The PDF must be saved on the same filesystem as this one, as it's referenced by filename.
        Parameters:
        filename - the name of the PDF to open
        pagenumber - which page to go to - the first page is 0, the second 1 and so on
        x - the X position on the new page to scroll to, or Float.NaN to keep the X position unchanged.
        y - the Y position on the new page to scroll to, or Float.NaN to keep the Y position unchanged.
        zoom - The zoom level. A value of 0 or Float.NaN leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.
        Since:
        2.6.4

      • goToRemote

        public static PDFAction goToRemote​(String filename,
                                   int pagenumber,
                                   float x,
                                   float y,
                                   float zoom,
                                   String newwindow)
        As for goTo(org.faceless.pdf2.PDFPage), but returns a new PDFAction which moves to a page in another PDF. The PDF must be saved on the same filesystem as this one, as it's referenced by filename. This method allows you to specify whether the new document is to be opened in a new window - the "newwindow" parameter may be "true" or "false" to force this - any other value (including null) will use the default setting of the opening application.
        Parameters:
        filename - the name of the PDF to open
        pagenumber - which page to go to - the first page is 0, the second 1 and so on
        x - the X position on the new page to scroll to, or Float.NaN to keep the X position unchanged.
        y - the Y position on the new page to scroll to, or Float.NaN to keep the Y position unchanged.
        zoom - The zoom level. A value of 0 or Float.NaN leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.
        newwindow - whether to open the document in a new window - either "true" or "false" to force this setting, or any other value to use the application default
        Since:
        2.7.8

      • goToFitRemoteRectangle

        public static PDFAction goToFitRemoteRectangle​(String filename,
                                               int pagenumber,
                                               float left,
                                               float bottom,
                                               float width,
                                               float height)
        As for goToFitRectangle(org.faceless.pdf2.PDFPage, float, float, float, float), but returns a new PDFAction which moves to a page in another PDF. The PDF must be saved on the same filesystem as this one, as it's referenced by filename.
        Parameters:
        filename - the name of the PDF to open
        pagenumber - which page to go to - the first page is 0, the second 1 and so on
        left - the left edge of the visible rectangle
        bottom - the bottom edge of the visible rectangle
        width - the width of the visible rectangle
        height - the height of the visible rectangle
        Since:
        2.6.4

      • launch

        public static PDFAction launch​(String filename,
                               String newwindow)
        Create a "Launch" action. This can be used to open either a new PDF document by specifying the name of the file (in a similar way to goToRemote()), or to open an application.
        Parameters:
        filename - the path name of the document or application to load.
        newwindow - whether to open the document in a new window - either "true" or "false" to force this setting, or any other value to use the application default. Note this is only used when opening PDF documents - it's ignored for applications.
        Since:
        2.7.8

      • launch

        public static PDFAction launch​(EmbeddedFile ef,
                               String newwindow)
        Create a "Launch" action to open an embedded file. This is completely valid and utterly unsupported by every PDF viewer on the market as of September 2022, but someone has to go first.
        Parameters:
        ef - the EmbeddedFile to open
        newwindow - whether to open the document in a new window - either "true" or "false" to force this setting, or any other value to use the application default.
        Since:
        2.27

      • playSound

        public static PDFAction playSound​(PDFSound s)
        Return a new PDFAction which plays a PDFSound when activated. This simpler of the two playSound methods plays the sound once at full volume and with mixing turned off. See the PDFSound class for more information on limitations with sound in PDF documents.
        Since:
        1.1
        See Also:
        PDFSound

      • playSound

        public static PDFAction playSound​(PDFSound sound,
                                  int volume,
                                  boolean repeat,
                                  boolean mix)
        Return a new PDFAction which plays a PDFSound when activated.
        Parameters:
        sound - the PDFSound to play.
        volume - the volume of the sound, from 0 (off) to 100 (maximum)
        repeat - whether to play the sound continuously or just once
        mix - whether to mix the sound in with any other playing samples, or replace them
        Since:
        1.1

      • named

        public static PDFAction named​(String name)

        Return a new PDFAction which runs the named action. Named actions are PDF viewer dependent, so should be used with care. The following actions are among those known to work in Acrobat 3 and 4 readers, and loosely correspond to the equivalent actions available from the menus in Acrobat.

        • Document Control
          Open Close Print GeneralInfo FontsInfo SecurityInfo Quit
        • Document Navigation
          NextPage PrevPage FirstPage LastPage GoToPage
        • Searching and Selecting
          Find FindAgain SelectAll Copy
        • Display
          FullScreen ZoomTo FitPage ZoomTo ActualSize FitWidth FitVisible SinglePage OneColumn TwoColumns
        Since:
        1.1

      • formSubmit

        public static PDFAction formSubmit​(String url,
                                   int method)

        Return a new PDFAction which submits the documents AcroForm. This should be used as the Event.MOUSEUP event for a FormButton somewhere in the form, so the form can be submitted.

        The method parameter can be one of the various METHOD values, although please note that many of these values are only implemented in Acrobat 5.0 or later.

        Parameters:
        url - the URL to submit the form to
        method - the method to use when submitting the form
        Since:
        1.1.23
        See Also:
        Form

      • formSubmit

        public static PDFAction formSubmit​(String url,
                                   int method,
                                   Collection<FormElement> fields)

        Return a new PDFAction which submits the documents AcroForm. This should As for formSubmit(String, int) but only submits the specified fields.

        Parameters:
        url - the URL to submit the form to
        method - the method to use when submitting the form
        fields - the fields to submit or, if null, submit all fields.
        Since:
        2.27
        See Also:
        Form

      • formReset

        public static PDFAction formReset()
        Return a new PDFAction which resets the documents AcroForm, setting every field to its default values.
        Since:
        1.1.23
        See Also:
        Form

      • formReset

        public static PDFAction formReset​(Collection<FormElement> fields)
        Return a new PDFAction which resets the specified fields in the documents AcroForm, setting them field to their default value.
        Parameters:
        fields - the fields to reset or, if null, reset all fields.
        Since:
        2.27
        See Also:
        Form

      • formImportData

        public static PDFAction formImportData​(String file)
        Return a new PDFAction which imports a Forms Data Format (FDF) file into the document AcroForm, setting some or all of the forms values.
        Parameters:
        file - the name of the file containing the FDF. The path to the file should be absolute to ensure that Acrobat can find it.
        Since:
        1.1.23
        See Also:
        Form

      • formJavaScript

        public static PDFAction formJavaScript​(String javascript)

        Return a new PDFAction which executes a JavaScript action. This is generally used with AcroForms, although in theory it doesn't have to be. It's generally better design to create functions in the document-wide JavaScript (as set by PDF.setJavaScript(java.lang.String)) and just use these actions to call those methods.

        Parameters:
        javascript - the JavaScript action to perform
        Since:
        1.1.23
        See Also:
        PDF.setJavaScript(java.lang.String), PDF.getJavaScript(), Form

      • setNext

        public void setNext​(PDFAction action)

        The setNext method allows you to create "chains" of actions which are executed whenever the first entry in the chain is run. This allows more complicated processing - for example, clicking on a button could play a sound and then jump to a specific page.

        Avoiding infinite action loops is the responsibility of the programmer.

        Parameters:
        action - the action to execute after the current one, or null to clear it.
        Since:
        1.1

      • getNext

        public PDFAction getNext()
        Return the action that's next in the chain after this one, or null if no further actions are defined.
        Since:
        1.1

      • getType

        public String getType()

        Return the type of action. Can be "Named:value" (where "value" is the named action that's performed), "URL", "Sound", "GoTo", "GoToFitRectangle", "GoToFit", "GoToFitHeight", "GoToFitWidth", "GoToDp" "ShowWidget", "HideWidget", "FormReset", "FormImportData", "FormSubmit", "FormJavaScript" or one of another type of action supported by the PDF specification but not by this library.

        Note since 1.1.23 the URL value no longer includes the URL being referenced - use the getURL() method to retrieve that value

        Returns:
        the type of action this object represents
        Since:
        1.1.12

      • getStructureElement

        public Element getStructureElement()
        If the action refers to an element in the PDF StructureTree, return the element it points to, or null otherwise. This is a PDF2.0 action
        Returns:
        the element in the PDF StructureTree that the action refers to, or null.
        Since:
        2.24.2

      • getStructureElementId

        public String getStructureElementId()
        If the action refers to an element in the PDF StructureTree, return the ID of that element. This is built on top of getStructureElement() except for the special case where the element is in an embedded or remote PDF.
        Returns:
        the element in the PDF StructureTree that the action refers to, or null.
        Since:
        2.24.3

      • getPage

        public PDFPage getPage()
        For actions that refer to a page - any of the "GoTo" actions except "GoToURL" - return the page the action refers to. For other types of action, returns null.
        Returns:
        the page this action refers to, or null if not applicable.
        Since:
        1.1.12

      • getPageNumber

        public int getPageNumber()
        For actions that refer to a page - any of the "GoTo" actions except "GoToURL" - return the page number of the page the action refers to. For other types of action, returns -1. Unlike getPage(org.faceless.pdf2.PDFMap, org.w3c.dom.Node), this method will not trigger a load of the target page if the PDF has been loaded in a linearized way
        Returns:
        the page number of the page this action refers to, or -1 if not applicable.
        Since:
        2.14

      • getSound

        public PDFSound getSound()
        For "Sound" actions, return the PDFSound object this action refers to. For other types of action this returns null
        Returns:
        the sound this action refers to, or null if not applicable.
        Since:
        1.1.12

      • getJavaScript

        public String getJavaScript()
        For JavaScript type annotations, return the JavaScript that is being executed. For other annotations, return null.
        Returns:
        the JavaScript that is executed or null if not applicable.
        Since:
        1.1.23

      • getURL

        public String getURL()
        For formSubmit, goToURL and formImportData actions, return the URL that is the destination of the action (or source of the data). For other annotations, return null
        Returns:
        the URL of the action
        Since:
        1.1.23

      • getFormSubmitMethod

        public int getFormSubmitMethod()
        For formSubmit actions, return the method by which the form is submitted - one of the METHOD parameters defined in this class. For other action types the return is -1
        Returns:
        the submit method for this formSubmit action
        Since:
        1.1.23

      • getFormSubmitFields

        public Collection<FormElement> getFormSubmitFields()
        Return the list of fields to be submitted by this form-submit action, or null if this action is not a form-submit action or is not part of a PDF. Despite the name this also applies to fields that are to be reset by the form-reset action.
        Since:
        2.8.3

      • getFormSubmitFlags

        public int getFormSubmitFlags()
        For formSubmit actions, return the raw "Flags" field of the action. For other action types the return is 0;
        Returns:
        the submit method for this formSubmit action
        Since:
        2.8.3

      • getGoToCoordinates

        public float[] getGoToCoordinates()

        Return the co-ordinates of a GoTo action. Some "GoTo" actions take one or more coordinates which determine which section of the specified page should be displayed. Examples of this are the goToFitRectangle method, which takes four parameters, and the goToFitWidth method, which takes one. These coordinates can be read by calling this method, which returns an array of floats, the length of which varies depending on the type of GoTo action.

        Specifically, "GoToFitWidth" and "GoToFitHeight" methods return an array of one float, "GoToFitRectangle" will return four and "GoTo" will return three. For this last one, the first number represents the "X" coordinate, the second the "Y" and the third the zoom level, but it's important to remember that any one of these may be unspecified - in this case the value is set to Float.NaN.

        Since:
        1.2

      • toString

        public String toString()