Package com.itextpdf.kernel.pdf.action

Class PdfAction

java.lang.Object
com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>
com.itextpdf.kernel.pdf.action.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 Details

    • SUBMIT_EXCLUDE

      public static final int SUBMIT_EXCLUDE
      A possible submit value
      See Also:

    • SUBMIT_INCLUDE_NO_VALUE_FIELDS

      public static final int SUBMIT_INCLUDE_NO_VALUE_FIELDS
      A possible submit value
      See Also:

    • SUBMIT_HTML_FORMAT

      public static final int SUBMIT_HTML_FORMAT
      A possible submit value
      See Also:

    • SUBMIT_HTML_GET

      public static final int SUBMIT_HTML_GET
      A possible submit value
      See Also:

    • SUBMIT_COORDINATES

      public static final int SUBMIT_COORDINATES
      A possible submit value
      See Also:

    • SUBMIT_XFDF

      public static final int SUBMIT_XFDF
      A possible submit value
      See Also:

    • SUBMIT_INCLUDE_APPEND_SAVES

      public static final int SUBMIT_INCLUDE_APPEND_SAVES
      A possible submit value
      See Also:

    • SUBMIT_INCLUDE_ANNOTATIONS

      public static final int SUBMIT_INCLUDE_ANNOTATIONS
      A possible submit value
      See Also:

    • SUBMIT_PDF

      public static final int SUBMIT_PDF
      A possible submit value
      See Also:

    • SUBMIT_CANONICAL_FORMAT

      public static final int SUBMIT_CANONICAL_FORMAT
      A possible submit value
      See Also:

    • SUBMIT_EXCL_NON_USER_ANNOTS

      public static final int SUBMIT_EXCL_NON_USER_ANNOTS
      A possible submit value
      See Also:

    • SUBMIT_EXCL_F_KEY

      public static final int SUBMIT_EXCL_F_KEY
      A possible submit value
      See Also:

    • SUBMIT_EMBED_FORM

      public static final int SUBMIT_EMBED_FORM
      A possible submit value
      See Also:

    • RESET_EXCLUDE

      public static final int RESET_EXCLUDE
      A possible submit value
      See Also:

  • Constructor Details

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

    • 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 (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 (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 (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 (String filename, 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 (String filename, 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 (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 (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, 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 (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 (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

    • createNamed

      public static PdfAction createNamed (PdfName namedAction)
      Creates a Named action (section 12.6.4.11 of ISO 32000-1).
      Parameters:
      namedAction - the name of the action that shall be performed. Shall be one of the following: PdfName.NextPage, PdfName.PrevPage, PdfName.FirstPage, PdfName.LastPage
      Returns:
      created action

    • createSetOcgState

      public static PdfAction createSetOcgState (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 (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 (String file, PdfFileSpec fileSpec, 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 (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 (String file, 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 (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

    • setAdditionalAction

      public static void setAdditionalAction (PdfObjectWrapper<PdfDictionary> wrapper, PdfName key, PdfAction action)
      Adds an additional action to the provided PdfObjectWrapper<PdfDictionary> wrapper.
      Parameters:
      wrapper - the wrapper to add an additional action to
      key - a PdfName specifying the name of an additional action
      action - the PdfAction to add as an additional 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.