org.faceless.pdf2
Class PDFAction

java.lang.Object
  extended byorg.faceless.pdf2.PDFObject
      extended byorg.faceless.pdf2.PDFMap
          extended byorg.faceless.pdf2.PDFAction
All Implemented Interfaces:
Cloneable

public final class PDFAction
extends org.faceless.pdf2.PDFMap

An action tells the PDF viewer how to navigate around the document. Actions are performed when the user clicks on a PDFBookmark, when a Form element or one of it's WidgetAnnotation children specifies an event, or optionally when an event occurs on a PDF or PDFPage, such as when the document is opened, printed or a page is opened or closed.

The PDFAction class has no public constructor, just a number of static methods returning a new action of the specified type.

Since:
1.0
See Also:
Event, PDFPage.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), PDF.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), FormElement.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), WidgetAnnotation.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), PDFBookmark

Field Summary
static int METHOD_FDF
          Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted in the Adobe Forms Data Format.
static 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.
static 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".
static 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.
static int METHOD_HTTP_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
static int METHOD_PDF
          Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as a PDF.
static int METHOD_XML
          Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as XML.
 
Method Summary
 boolean equals(Object o)
           
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.
static PDFAction formJavaScript(String javascript)
           Return a new PDFAction which executes a JavaScript action.
static PDFAction formReset()
          Return a new PDFAction which resets the documents AcroForm, setting every field to its default values.
static PDFAction formSubmit(String url, int method)
          Return a new PDFAction which submits the documents AcroForm.
 WidgetAnnotation getAnnotation()
          For hideWidget(org.faceless.pdf2.WidgetAnnotation) and showWidget(org.faceless.pdf2.WidgetAnnotation) actions, return the annotation being toggled shown or hidden.
 int getFormSubmitMethod()
          For formSubmit actions, return the method by which the form is submitted - one of the METHOD parameters defined in this class.
 float[] getGoToCoordinates()
           Return the co-ordinates of a GoTo action.
 String getJavaScript()
          For JavaScript type annotations, return the JavaScript that is being executed.
 PDFAction getNext()
          Return the action that's next in the chain after this one, or null if no further actions are defined.
 PDFPage getPage()
          For actions that refer to a page - any of the "GoTo" actions except "GoToURL" - return the page the action refers to.
 PDFSound getSound()
          For "Sound" actions, return the PDFSound object this action refers to.
 String getType()
           Return the type of action.
 String getURL()
          For formSubmit, goToURL and formImportData actions, return the URL that is the destination of the action (or source of the data).
static PDFAction goTo(PDFPage page)
          Return a new PDFAction which jumps to the specified page in the PDF document.
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.
static PDFAction goToFit(PDFPage page)
          Return a new PDFAction which jumps to the specified page in the PDF document.
static PDFAction goToFitHeight(PDFPage page, float x)
          Return a new PDFAction which jumps to the specified page in the PDF document.
static PDFAction goToFitRectangle(PDFPage page, float left, float bottom, float width, float height)
          Return a new PDFAction which jumps to the specified page in the PDF document.
static PDFAction goToFitWidth(PDFPage page, float y)
          Return a new PDFAction which jumps to the specified page in the PDF document.
static PDFAction goToURL(URL url)
          Return a new PDFAction which jumps to the specified URL.
static PDFAction goToURL(URL url, boolean isImageMap)
          Return a new PDFAction which jumps to the specified URL.
static PDFAction hideWidget(WidgetAnnotation annot)
          Return a new PDFAction which hides the specified WidgetAnnotation.
static PDFAction named(String name)
          Return a new PDFAction which runs the named action.
static PDFAction playSound(PDFSound s)
          Return a new PDFAction which plays a PDFSound when activated.
static PDFAction playSound(PDFSound sound, int volume, boolean repeat, boolean mix)
          Return a new PDFAction which plays a PDFSound when activated.
 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.
static PDFAction showWidget(WidgetAnnotation annot)
          Return a new PDFAction which makes the specified WidgetAnnotation visible on screen.
 String toString()
           
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

METHOD_HTTP_POST

public static final int METHOD_HTTP_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

See Also:
Constant Field Values

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_FDF

public static final int METHOD_FDF
Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted in the Adobe Forms Data Format.

See Also:
Constant Field Values

METHOD_XML

public static final int METHOD_XML
Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as XML. This method requires PDF 1.4 (Acrobat 5.0) or later.

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_PDF

public static final int METHOD_PDF
Method for the formSubmit(java.lang.String, int) action specifying that the form should be submitted as a PDF. This method requires PDF 1.4 (Acrobat 5.0) or later.

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(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 left,
                                         float bottom,
                                         float width,
                                         float height)
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
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

goToURL

public static PDFAction goToURL(URL url)
Return a new PDFAction which jumps to the specified URL.

Since:
1.1

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.

Since:
1.1

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.

Since:
1.1

showWidget

public static PDFAction showWidget(WidgetAnnotation annot)
Return a new PDFAction which makes the specified WidgetAnnotation visible on screen.

Parameters:
annot - the annotation to modify
Since:
2.0
See Also:
hideWidget(org.faceless.pdf2.WidgetAnnotation)

hideWidget

public static PDFAction hideWidget(WidgetAnnotation annot)
Return a new PDFAction which hides the specified WidgetAnnotation.

Parameters:
annot - the annotation to modify
Since:
2.0
See Also:
showWidget(org.faceless.pdf2.WidgetAnnotation)

formSubmit

public static PDFAction formSubmit(String url,
                                   int method)
Return a new PDFAction which submits the documents AcroForm. This should be used as the ONCLICK 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

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

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 file is relative to the location of the current document
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", "ShowWidget", "HideWidget", "FormReset", "FormImportData", "FormSubmit", "FormJavaScript" or one of another type of action supported by the PDF specification but not by this library ("Launch", "Thread" or "Movie").

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

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

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

getAnnotation

public WidgetAnnotation getAnnotation()
For hideWidget(org.faceless.pdf2.WidgetAnnotation) and showWidget(org.faceless.pdf2.WidgetAnnotation) actions, return the annotation being toggled shown or hidden.

Returns:
the annotation this action refers to, or null if not applicable.
Since:
1.1.22

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

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

equals

public boolean equals(Object o)


Copyright © 2001-2004 Big Faceless Organization