Class PdfAction


  • public class PdfAction
    extends PdfObjectWrapper<PdfDictionary>
    A wrapper for action dictionaries (ISO 32000-1 section 12.6). An action dictionary defines the characteristics and behaviour of an action.
    • Field Detail

      • SUBMIT_EXCLUDE

        public static final int SUBMIT_EXCLUDE
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_INCLUDE_NO_VALUE_FIELDS

        public static final int SUBMIT_INCLUDE_NO_VALUE_FIELDS
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_HTML_FORMAT

        public static final int SUBMIT_HTML_FORMAT
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_HTML_GET

        public static final int SUBMIT_HTML_GET
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_COORDINATES

        public static final int SUBMIT_COORDINATES
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_XFDF

        public static final int SUBMIT_XFDF
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_INCLUDE_APPEND_SAVES

        public static final int SUBMIT_INCLUDE_APPEND_SAVES
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_INCLUDE_ANNOTATIONS

        public static final int SUBMIT_INCLUDE_ANNOTATIONS
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_CANONICAL_FORMAT

        public static final int SUBMIT_CANONICAL_FORMAT
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_EXCL_NON_USER_ANNOTS

        public static final int SUBMIT_EXCL_NON_USER_ANNOTS
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_EXCL_F_KEY

        public static final int SUBMIT_EXCL_F_KEY
        A possible submit value
        See Also:
        Constant Field Values
      • SUBMIT_EMBED_FORM

        public static final int SUBMIT_EMBED_FORM
        A possible submit value
        See Also:
        Constant Field Values
      • RESET_EXCLUDE

        public static final int RESET_EXCLUDE
        A possible submit value
        See Also:
        Constant Field Values
    • Constructor Detail

      • PdfAction

        public PdfAction()
        Constructs an empty action that can be further modified.
      • PdfAction

        public PdfAction​(PdfDictionary pdfObject)
        Constructs a PdfAction instance with a given dictionary. It can be used for handy property reading in reading mode or modifying in stamping mode.
        Parameters:
        pdfObject - the dictionary to construct the wrapper around
    • Method Detail

      • createURI

        public static PdfAction createURI​(java.net.URI uri)
        Creates a GoTo action (section 12.6.4.2 of ISO 32000-1) via a given uri.
        Parameters:
        uri - the uniform resource identifier to resolve
        Returns:
        created action
      • createGoTo

        public static PdfAction createGoTo​(PdfDestination destination)
        Creates a GoTo action (section 12.6.4.2 of ISO 32000-1) via a given destination.
        Parameters:
        destination - the desired destination of the action
        Returns:
        created action
      • createGoTo

        public static PdfAction createGoTo​(java.lang.String destination)
        Creates a GoTo action (section 12.6.4.2 of ISO 32000-1) via a given PdfStringDestination name.
        Parameters:
        destination - PdfStringDestination name
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(PdfFileSpec fileSpec,
                                            PdfDestination destination,
                                            boolean newWindow)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        fileSpec - the file in which the destination shall be located
        destination - the destination in the remote document to jump to
        newWindow - a flag specifying whether to open the destination document in a new window
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(PdfFileSpec fileSpec,
                                            PdfDestination destination)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        fileSpec - the file in which the destination shall be located
        destination - the destination in the remote document to jump to
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(java.lang.String filename,
                                            int pageNum)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        filename - the remote destination file to jump to
        pageNum - the remote destination document page to jump to
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(java.lang.String filename,
                                            int pageNum,
                                            boolean newWindow)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        filename - the remote destination file to jump to
        pageNum - the remote destination document page to jump to
        newWindow - a flag specifying whether to open the destination document in a new window
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(java.lang.String filename,
                                            java.lang.String destination,
                                            boolean newWindow)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        filename - the remote destination file to jump to
        destination - the string destination in the remote document to jump to
        newWindow - a flag specifying whether to open the destination document in a new window
        Returns:
        created action
      • createGoToR

        public static PdfAction createGoToR​(java.lang.String filename,
                                            java.lang.String destination)
        Creates a GoToR action, or remote action (section 12.6.4.3 of ISO 32000-1).
        Parameters:
        filename - the remote destination file to jump to
        destination - the string destination in the remote document to jump to
        Returns:
        created action
      • createGoToE

        public static PdfAction createGoToE​(PdfDestination destination,
                                            boolean newWindow,
                                            PdfTarget targetDictionary)
        Creates a GoToE action, or embedded file action (section 12.6.4.4 of ISO 32000-1).
        Parameters:
        destination - the destination in the target to jump to
        newWindow - if true, the destination document should be opened in a new window; if false, the destination document should replace the current document in the same window
        targetDictionary - A target dictionary specifying path information to the target document. Each target dictionary specifies one element in the full path to the target and may have nested target dictionaries specifying additional elements
        Returns:
        created action
      • createGoToE

        public static PdfAction createGoToE​(PdfFileSpec fileSpec,
                                            PdfDestination destination,
                                            boolean newWindow,
                                            PdfTarget targetDictionary)
        Creates a GoToE action, or embedded file action (section 12.6.4.4 of ISO 32000-1).
        Parameters:
        fileSpec - The root document of the target relative to the root document of the source
        destination - the destination in the target to jump to
        newWindow - if true, the destination document should be opened in a new window; if false, the destination document should replace the current document in the same window
        targetDictionary - A target dictionary specifying path information to the target document. Each target dictionary specifies one element in the full path to the target and may have nested target dictionaries specifying additional elements
        Returns:
        created action
      • createLaunch

        public static PdfAction createLaunch​(PdfFileSpec fileSpec,
                                             boolean newWindow)
        Creates a Launch action (section 12.6.4.5 of ISO 32000-1).
        Parameters:
        fileSpec - the application that shall be launched or the document that shall beopened or printed
        newWindow - a flag specifying whether to open the destination document in a new window
        Returns:
        created action
      • createLaunch

        public static PdfAction createLaunch​(PdfFileSpec fileSpec)
        Creates a Launch action (section 12.6.4.5 of ISO 32000-1).
        Parameters:
        fileSpec - the application that shall be launched or the document that shall beopened or printed
        Returns:
        created action
      • createThread

        public static PdfAction createThread​(PdfFileSpec fileSpec,
                                             PdfObject destinationThread,
                                             PdfObject bead)
        Creates a Thread action (section 12.6.4.6 of ISO 32000-1). A thread action jumps to a specified bead on an article thread (see 12.4.3, "Articles"), in either the current document or a different one. Table 205 shows the action dictionary entries specific to this type of action.
        Parameters:
        fileSpec - the file containing the thread. If this entry is absent, the thread is in the current file
        destinationThread - the destination thread
        bead - the bead in the destination thread
        Returns:
        created action
      • createThread

        public static PdfAction createThread​(PdfFileSpec fileSpec)
        Creates a Thread action (section 12.6.4.6 of ISO 32000-1). A thread action jumps to a specified bead on an article thread (see 12.4.3, "Articles"), in either the current document or a different one. Table 205 shows the action dictionary entries specific to this type of action.
        Parameters:
        fileSpec - the file containing the thread. If this entry is absent, the thread is in the current file
        Returns:
        created action
      • createURI

        public static PdfAction createURI​(java.lang.String uri)
        Creates a URI action (section 12.6.4.7 of ISO 32000-1).
        Parameters:
        uri - the uniform resource identifier to resolve
        Returns:
        created action
      • createURI

        public static PdfAction createURI​(java.lang.String uri,
                                          boolean isMap)
        Creates a URI action (section 12.6.4.7 of ISO 32000-1).
        Parameters:
        uri - the uniform resource identifier to resolve
        isMap - a flag specifying whether to track the mouse position when the URI is resolved
        Returns:
        created action
      • createSound

        public static PdfAction createSound​(PdfStream sound)
        Creates a Sound action (section 12.6.4.8 of ISO 32000-1). Deprecated in PDF 2.0.
        Parameters:
        sound - a sound object defining the sound that shall be played (see section 13.3 of ISO 32000-1)
        Returns:
        created action
      • createSound

        public static PdfAction createSound​(PdfStream sound,
                                            float volume,
                                            boolean synchronous,
                                            boolean repeat,
                                            boolean mix)
        Creates a Sound action (section 12.6.4.8 of ISO 32000-1). Deprecated in PDF 2.0.
        Parameters:
        sound - a sound object defining the sound that shall be played (see section 13.3 of ISO 32000-1)
        volume - the volume at which to play the sound, in the range -1.0 to 1.0. Default value: 1.0
        synchronous - a flag specifying whether to play the sound synchronously or asynchronously. If this flag is true, the conforming reader retains control, allowing no further user interaction other than canceling the sound, until the sound has been completely played. Default value: false
        repeat - a flag specifying whether to repeat the sound indefinitely If this entry is present, the Synchronous entry shall be ignored. Default value: false
        mix - a flag specifying whether to mix this sound with any other sound already playing
        Returns:
        created action
      • createMovie

        public static PdfAction createMovie​(PdfAnnotation annotation,
                                            java.lang.String title,
                                            PdfName operation)
        Creates a Movie annotation (section 12.6.4.9 of ISO 32000-1). Deprecated in PDF 2.0.
        Parameters:
        annotation - a movie annotation identifying the movie that shall be played
        title - the title of a movie annotation identifying the movie that shall be played
        operation - the operation that shall be performed on the movie. Shall be one of the following: PdfName.Play, PdfName.Stop, PdfName.Pause, PdfName.Resume
        Returns:
        created annotation
      • createHide

        public static PdfAction createHide​(PdfAnnotation annotation,
                                           boolean hidden)
        Creates a Hide action (section 12.6.4.10 of ISO 32000-1).
        Parameters:
        annotation - the annotation to be hidden or shown
        hidden - a flag indicating whether to hide the annotation (true) or show it (false)
        Returns:
        created action
      • createHide

        public static PdfAction createHide​(PdfAnnotation[] annotations,
                                           boolean hidden)
        Creates a Hide action (section 12.6.4.10 of ISO 32000-1).
        Parameters:
        annotations - the annotations to be hidden or shown
        hidden - a flag indicating whether to hide the annotation (true) or show it (false)
        Returns:
        created action
      • createHide

        public static PdfAction createHide​(java.lang.String text,
                                           boolean hidden)
        Creates a Hide action (section 12.6.4.10 of ISO 32000-1).
        Parameters:
        text - a text string giving the fully qualified field name of an interactive form field whose associated widget annotation or annotations are to be affected
        hidden - a flag indicating whether to hide the annotation (true) or show it (false)
        Returns:
        created action
      • createHide

        public static PdfAction createHide​(java.lang.String[] text,
                                           boolean hidden)
        Creates a Hide action (section 12.6.4.10 of ISO 32000-1).
        Parameters:
        text - a text string array giving the fully qualified field names of interactive form fields whose associated widget annotation or annotations are to be affected
        hidden - a flag indicating whether to hide the annotation (true) or show it (false)
        Returns:
        created action
      • createSetOcgState

        public static PdfAction createSetOcgState​(java.util.List<PdfActionOcgState> states)
        Creates a Set-OCG-State action (section 12.6.4.12 of ISO 32000-1).
        Parameters:
        states - a list of PdfActionOcgState state descriptions
        Returns:
        created action
      • createSetOcgState

        public static PdfAction createSetOcgState​(java.util.List<PdfActionOcgState> states,
                                                  boolean preserveRb)
        Creates a Set-OCG-State action (section 12.6.4.12 of ISO 32000-1).
        Parameters:
        states - states a list of PdfActionOcgState state descriptions
        preserveRb - If true, indicates that radio-button state relationships between optional content groups should be preserved when the states are applied
        Returns:
        created action
      • createRendition

        public static PdfAction createRendition​(java.lang.String file,
                                                PdfFileSpec fileSpec,
                                                java.lang.String mimeType,
                                                PdfAnnotation screenAnnotation)
        Creates a Rendition action (section 12.6.4.13 of ISO 32000-1).
        Parameters:
        file - the name of the media clip, for use in the user interface.
        fileSpec - a full file specification or form XObject that specifies the actual media data
        mimeType - an ASCII string identifying the type of data
        screenAnnotation - a screen annotation
        Returns:
        created action
      • createJavaScript

        public static PdfAction createJavaScript​(java.lang.String javaScript)
        Creates a JavaScript action (section 12.6.4.16 of ISO 32000-1).
        Parameters:
        javaScript - a text string containing the JavaScript script to be executed.
        Returns:
        created action
      • createSubmitForm

        public static PdfAction createSubmitForm​(java.lang.String file,
                                                 java.lang.Object[] names,
                                                 int flags)
        Creates a Submit-Form Action (section 12.7.5.2 of ISO 32000-1).
        Parameters:
        file - a uniform resource locator, as described in 7.11.5, "URL Specifications"
        names - an array identifying which fields to include in the submission or which to exclude, depending on the setting of the Include/Exclude flag in the Flags entry. This is an optional parameter and can be null
        flags - a set of flags specifying various characteristics of the action (see Table 237 of ISO 32000-1). Default value to be passed: 0.
        Returns:
        created action
      • createResetForm

        public static PdfAction createResetForm​(java.lang.Object[] names,
                                                int flags)
        Creates a Reset-Form Action (section 12.7.5.3 of ISO 32000-1).
        Parameters:
        names - an array identifying which fields to reset or which to exclude from resetting, depending on the setting of the Include/Exclude flag in the Flags entry (see Table 239 of ISO 32000-1).
        flags - a set of flags specifying various characteristics of the action (see Table 239 of ISO 32000-1). Default value to be passed: 0.
        Returns:
        created action
      • next

        public void next​(PdfAction nextAction)
        Adds a chained action.
        Parameters:
        nextAction - the next action or sequence of actions that shall be performed after the current action
      • put

        public PdfAction put​(PdfName key,
                             PdfObject value)
        Inserts the value into the underlying object of this PdfAction and associates it with the specified key. If the key is already present in this PdfAction, this method will override the old value with the specified one.
        Parameters:
        key - key to insert or to override
        value - the value to associate with the specified key
        Returns:
        this PdfAction instance
      • flush

        public void flush()
        To manually flush a PdfObject behind this wrapper, you have to ensure that this object is added to the document, i.e. it has an indirect reference. Basically this means that before flushing you need to explicitly call PdfObjectWrapper.makeIndirect(PdfDocument). For example: wrapperInstance.makeIndirect(document).flush(); Note that not every wrapper require this, only those that have such warning in documentation.
        Overrides:
        flush in class PdfObjectWrapper<PdfDictionary>
      • isWrappedObjectMustBeIndirect

        protected boolean isWrappedObjectMustBeIndirect()
        Defines if the object behind this wrapper must be an indirect object in the resultant document.

        If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.

        Return value of this method shouldn't depend on any logic, it should return always true or false.
        Specified by:
        isWrappedObjectMustBeIndirect in class PdfObjectWrapper<PdfDictionary>
        Returns:
        true if in the resultant document the object behind the wrapper must be indirect, otherwise false.
      • getPdfArrayFromAnnotationsList

        private static PdfArray getPdfArrayFromAnnotationsList​(PdfAnnotation[] wrappers)
      • getArrayFromStringList

        private static PdfArray getArrayFromStringList​(java.lang.String[] strings)
      • buildArray

        private static PdfArray buildArray​(java.lang.Object[] names)
      • validateRemoteDestination

        private static void validateRemoteDestination​(PdfDestination destination)
      • validateNotRemoteDestination

        private static void validateNotRemoteDestination​(PdfDestination destination)
        Validates not remote destination against the PDF specification and in case of invalidity logs a warning. See section 12.3.2.2 of ISO 32000-1.
        Parameters:
        destination - the destination to be validated