Class PDFAction
- java.lang.Object
-
- org.faceless.pdf2.PDFAction
-
- All Implemented Interfaces:
java.lang.Cloneable
public final class PDFAction extends java.lang.Object
An action tells the PDF viewer how to navigate around the document. Actions are performed when the user clicks on a
PDFBookmark
, when aForm
element or one of it'sWidgetAnnotation
children specifies an event, or optionally when an event occurs on aPDF
orPDFPage
, 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
Fields Modifier and Type Field Description static int
METHOD_FDF
Method for theformSubmit(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 theformSubmit(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 theformSubmit(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_FLAG_CANONICALDATES
Flag that can be added to the method passed toformSubmit(java.lang.String, int)
to specify that all dates should be submitted in "canonical" D:YYYYMMDDHHMMSS formatstatic int
METHOD_FLAG_EMPTYFIELDS
Flag that can be added ot the method passed toformSubmit(java.lang.String, int)
tp specify that values for empty fields should be submitted as well.static int
METHOD_HTTP_IMAGEMAP_POST
Method for theformSubmit(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 theformSubmit(java.lang.String, int)
action specifying that the form should be submitted as a standard HTTP POST, in the same way as an HTML formstatic int
METHOD_PDF
Method for theformSubmit(java.lang.String, int)
action specifying that the form should be submitted as a PDF.static int
METHOD_XML
Method for theformSubmit(java.lang.String, int)
action specifying that the form should be submitted as XFDF XML.static int
METHOD_XML_WITH_ALL_ANNOTATIONS
Method for theformSubmit(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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected java.lang.Object
clone()
static PDFAction
formImportData(java.lang.String file)
Return a newPDFAction
which imports a Forms Data Format (FDF) file into the document AcroForm, setting some or all of the forms values.static PDFAction
formJavaScript(java.lang.String javascript)
Return a newPDFAction
which executes a JavaScript action.static PDFAction
formReset()
Return a newPDFAction
which resets the documents AcroForm, setting every field to its default values.static PDFAction
formReset(java.util.Collection<FormElement> fields)
Return a newPDFAction
which resets the specified fields in the documents AcroForm, setting them field to their default value.static PDFAction
formSubmit(java.lang.String url, int method)
Return a new PDFAction which submits the documents AcroForm.static PDFAction
formSubmit(java.lang.String url, int method, java.util.Collection<FormElement> fields)
Return a new PDFAction which submits the documents AcroForm.WidgetAnnotation
getAnnotation()
ForhideWidget(org.faceless.pdf2.WidgetAnnotation)
andshowWidget(org.faceless.pdf2.WidgetAnnotation)
actions, return the annotation being toggled shown or hidden.java.util.Collection<FormElement>
getFormSubmitFields()
Return the list of fields to be submitted by this form-submit action, ornull
if this action is not a form-submit action or is not part of a PDF.int
getFormSubmitFlags()
For formSubmit actions, return the raw "Flags" field of the action.int
getFormSubmitMethod()
For formSubmit actions, return the method by which the form is submitted - one of theMETHOD
parameters defined in this class.float[]
getGoToCoordinates()
Return the co-ordinates of a GoTo action.java.lang.String
getJavaScript()
ForJavaScript
type annotations, return the JavaScript that is being executed.PDFAction
getNext()
Return the action that's next in the chain after this one, ornull
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.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.java.lang.String
getRemoteFilename()
ForgoToRemote(java.lang.String, int, float, float, float)
,goToFitRemoteRectangle(java.lang.String, int, float, float, float, float)
andgoToEmbedded(java.lang.String, int, float, float, float)
actions, return the file name that this action refers to.int
getRemotePageNumber()
ForgoToRemote(java.lang.String, int, float, float, float)
andgoToFitRemoteRectangle(java.lang.String, int, float, float, float, float)
actions, return the page number that this action refers to, starting at 0.PDFSound
getSound()
For "Sound" actions, return the PDFSound object this action refers to.org.w3c.dom.Element
getStructureElement()
If the action refers to an element in the PDF StructureTree, return the element it points to, or null otherwise.java.lang.String
getStructureElementId()
If the action refers to an element in the PDF StructureTree, return the ID of that element.java.lang.String
getType()
Return the type of action.java.lang.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
goTo(org.w3c.dom.Element elt, float x, float y, float zoom)
Return a new PDFAction which jumps to the page containing the specified element from theStructureTree
.static PDFAction
goToEmbedded(java.lang.String path, int page, float x, float y, float zoom)
Create an "embedded" link.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 x1, float y1, float x2, float y2)
Return a new PDFAction which jumps to the specified page in the PDF document.static PDFAction
goToFitRemoteRectangle(java.lang.String filename, int pagenumber, float left, float bottom, float width, float height)
As forgoToFitRectangle(org.faceless.pdf2.PDFPage, float, float, float, float)
, but returns a new PDFAction which moves to a page in another PDF.static PDFAction
goToFitWidth(PDFPage page, float y)
Return a new PDFAction which jumps to the specified page in the PDF document.static PDFAction
goToRemote(java.lang.String filename, int pagenumber, float x, float y, float zoom)
As forgoTo(org.faceless.pdf2.PDFPage)
, but returns a new PDFAction which moves to a page in another PDF.static PDFAction
goToRemote(java.lang.String filename, int pagenumber, float x, float y, float zoom, java.lang.String newwindow)
As forgoTo(org.faceless.pdf2.PDFPage)
, but returns a new PDFAction which moves to a page in another PDF.static PDFAction
goToURL(java.lang.String url)
Return a new PDFAction which jumps to the specified URL.static PDFAction
goToURL(java.net.URI uri, boolean isImageMap)
Return a new PDFAction which jumps to the specified URI.static PDFAction
goToURL(java.net.URL url)
Return a new PDFAction which jumps to the specified URL.static PDFAction
goToURL(java.net.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 specifiedWidgetAnnotation
.static PDFAction
launch(java.lang.String filename, java.lang.String newwindow)
Create a "Launch" action.static PDFAction
launch(EmbeddedFile ef, java.lang.String newwindow)
Create a "Launch" action to open an embedded file.static PDFAction
named(java.lang.String name)
Return a new PDFAction which runs the named action.static PDFAction
playSound(PDFSound s)
Return a new PDFAction which plays aPDFSound
when activated.static PDFAction
playSound(PDFSound sound, int volume, boolean repeat, boolean mix)
Return a new PDFAction which plays aPDFSound
when activated.void
putLiteral(java.lang.String key, java.lang.String tokens)
Put a literal token sequnce.void
setNext(PDFAction action)
ThesetNext
method allows you to create "chains" of actions which are executed whenever the first entry in the chain is run.static PDFAction
showOptionalContent(java.util.Map<OptionalContentLayer,OptionalContentLayer.When> map, boolean preserveRadioButtons)
Set the visibility of the specifiedOptionalContentLayer
objects to on (OptionalContentLayer.When.Always
), off (OptionalContentLayer.When.Never
) or "toggle" (OptionalContentLayer.When.Always
), where the current state will be changed between off and onstatic PDFAction
showWidget(WidgetAnnotation annot)
Return a new PDFAction which makes the specifiedWidgetAnnotation
visible on screen.PDFAction
toEmbedded(java.lang.String path)
If this action is a GoTo type action, return an equivalent GoToE(mbedded) action that is its equivalent if the PDF was embedded at the specified path.java.lang.String
toString()
-
-
-
Field Detail
-
METHOD_HTTP_POST
public static final int METHOD_HTTP_POST
Method for theformSubmit(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 theformSubmit(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 theformSubmit(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 theformSubmit(java.lang.String, int)
action specifying that the form should be submitted as XFDF XML. This method requires PDF 1.4 (Acrobat 5.0) or later.- See Also:
- Constant Field Values
-
METHOD_XML_WITH_ALL_ANNOTATIONS
public static final int METHOD_XML_WITH_ALL_ANNOTATIONS
Method for theformSubmit(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 theformSubmit(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 theformSubmit(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 theformSubmit(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_FLAG_CANONICALDATES
public static final int METHOD_FLAG_CANONICALDATES
Flag that can be added to the method passed toformSubmit(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 toformSubmit(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(org.w3c.dom.Element elt, float x, float y, float zoom)
Return a new PDFAction which jumps to the page containing the specified element from theStructureTree
. This is a PDF 2.0 feature.- Parameters:
elt
- the element to jump to, which must bex
- the X position on the new page to scroll to, orFloat.NaN
to keep the X position unchanged.y
- the Y position on the new page to scroll to, orFloat.NaN
to keep the Y position unchanged.zoom
- The zoom level. A value of 0 orFloat.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(java.lang.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 the name of an element in the
StructureTree
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.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 jump to the page containing the element "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 fragmentx
- the X position on the new page to scroll to, orFloat.NaN
to keep the X position unchanged.y
- the Y position on the new page to scroll to, orFloat.NaN
to keep the Y position unchanged.zoom
- The zoom level. A value of 0 orFloat.NaN
leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.- Since:
- 2.24.3
-
toEmbedded
public PDFAction toEmbedded(java.lang.String path)
If this action is a GoTo type action, return an equivalent GoToE(mbedded) action that is its equivalent if the PDF was embedded at the specified path. For non GoTo actions, returns ths.- Parameters:
path
- the path the PDF containing this action would be embedded as.- Returns:
- the described action
- Since:
- 2.26
-
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, orFloat.NaN
to keep the X position unchanged.y
- the Y position on the new page to scroll to, orFloat.NaN
to keep the Y position unchanged.zoom
- The zoom level. A value of 0 orFloat.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 toy
- 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 tox1
- the left edge of the visible rectangley1
- the bottom edge of the visible rectanglex2
- the right edge of the visible rectangley2
- the top edge of the visible rectangle
-
goToURL
public static PDFAction goToURL(java.net.URL url)
Return a new PDFAction which jumps to the specified URL.- Parameters:
url
- the URL- Since:
- 1.1
-
goToURL
public static PDFAction goToURL(java.lang.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(java.net.URL url, boolean isImageMap)
Return a new PDFAction which jumps to the specified URL. When used from aPDFAnnotation
, 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 ishttp://www.url.com/?20,30
.- Parameters:
url
- the URLisImageMap
- true if the URL is an imagemap- Since:
- 1.1
-
goToURL
public static PDFAction goToURL(java.net.URI uri, boolean isImageMap)
Return a new PDFAction which jumps to the specified URI. Identical togoToURL(URL, boolean)
except it takes ajava.net.URI
- Since:
- 2.6.12
-
goToRemote
public static PDFAction goToRemote(java.lang.String filename, int pagenumber, float x, float y, float zoom)
As forgoTo(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 openpagenumber
- which page to go to - the first page is 0, the second 1 and so onx
- the X position on the new page to scroll to, orFloat.NaN
to keep the X position unchanged.y
- the Y position on the new page to scroll to, orFloat.NaN
to keep the Y position unchanged.zoom
- The zoom level. A value of 0 orFloat.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(java.lang.String filename, int pagenumber, float x, float y, float zoom, java.lang.String newwindow)
As forgoTo(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 openpagenumber
- which page to go to - the first page is 0, the second 1 and so onx
- the X position on the new page to scroll to, orFloat.NaN
to keep the X position unchanged.y
- the Y position on the new page to scroll to, orFloat.NaN
to keep the Y position unchanged.zoom
- The zoom level. A value of 0 orFloat.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(java.lang.String filename, int pagenumber, float left, float bottom, float width, float height)
As forgoToFitRectangle(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 openpagenumber
- which page to go to - the first page is 0, the second 1 and so onleft
- the left edge of the visible rectanglebottom
- the bottom edge of the visible rectanglewidth
- the width of the visible rectangleheight
- the height of the visible rectangle- Since:
- 2.6.4
-
launch
public static PDFAction launch(java.lang.String filename, java.lang.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 togoToRemote()
), 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, java.lang.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 opennewwindow
- 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 aPDFSound
when activated. This simpler of the two playSound methods plays the sound once at full volume and with mixing turned off. See thePDFSound
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 aPDFSound
when activated.- Parameters:
sound
- thePDFSound
to play.volume
- the volume of the sound, from 0 (off) to 100 (maximum)repeat
- whether to play the sound continuously or just oncemix
- whether to mix the sound in with any other playing samples, or replace them- Since:
- 1.1
-
named
public static PDFAction named(java.lang.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
- Document Control
-
showWidget
public static PDFAction showWidget(WidgetAnnotation annot)
Return a new PDFAction which makes the specifiedWidgetAnnotation
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 specifiedWidgetAnnotation
.- Parameters:
annot
- the annotation to modify- Since:
- 2.0
- See Also:
showWidget(org.faceless.pdf2.WidgetAnnotation)
-
showOptionalContent
public static PDFAction showOptionalContent(java.util.Map<OptionalContentLayer,OptionalContentLayer.When> map, boolean preserveRadioButtons)
Set the visibility of the specifiedOptionalContentLayer
objects to on (OptionalContentLayer.When.Always
), off (OptionalContentLayer.When.Never
) or "toggle" (OptionalContentLayer.When.Always
), where the current state will be changed between off and on- Parameters:
map
- a map of layers and their target statespreserveRadioButtons
- "... indicates that radio-button state relationships between optional content groups should be preserved when the states in the State array are applied.". The default is true.- Since:
- 2.24.2
-
formSubmit
public static PDFAction formSubmit(java.lang.String url, int method)
Return a new PDFAction which submits the documents AcroForm. This should be used as the
Event.MOUSEUP
event for aFormButton
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 tomethod
- the method to use when submitting the form- Since:
- 1.1.23
- See Also:
Form
-
formSubmit
public static PDFAction formSubmit(java.lang.String url, int method, java.util.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 tomethod
- the method to use when submitting the formfields
- the fields to submit or, if null, submit all fields.- Since:
- 2.27
- See Also:
Form
-
formReset
public static PDFAction formReset()
Return a newPDFAction
which resets the documents AcroForm, setting every field to its default values.- Since:
- 1.1.23
- See Also:
Form
-
formReset
public static PDFAction formReset(java.util.Collection<FormElement> fields)
Return a newPDFAction
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(java.lang.String file)
Return a newPDFAction
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(java.lang.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 byPDF.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, ornull
to clear it.- Since:
- 1.1
-
getNext
public PDFAction getNext()
Return the action that's next in the chain after this one, ornull
if no further actions are defined.- Since:
- 1.1
-
getType
public java.lang.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 org.w3c.dom.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 java.lang.String getStructureElementId()
If the action refers to an element in the PDF StructureTree, return the ID of that element. This is built on top ofgetStructureElement()
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. UnlikegetPage()
, 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
-
getAnnotation
public WidgetAnnotation getAnnotation()
ForhideWidget(org.faceless.pdf2.WidgetAnnotation)
andshowWidget(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 java.lang.String getJavaScript()
ForJavaScript
type annotations, return the JavaScript that is being executed. For other annotations, returnnull
.- Returns:
- the JavaScript that is executed or null if not applicable.
- Since:
- 1.1.23
-
getURL
public java.lang.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, returnnull
- 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 theMETHOD
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 java.util.Collection<FormElement> getFormSubmitFields()
Return the list of fields to be submitted by this form-submit action, ornull
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 thegoToFitWidth
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
-
getRemotePageNumber
public int getRemotePageNumber()
ForgoToRemote(java.lang.String, int, float, float, float)
andgoToFitRemoteRectangle(java.lang.String, int, float, float, float, float)
actions, return the page number that this action refers to, starting at 0. A value of -1 is returned if this action is not a remote action or the remote action doesn't reference a page- Since:
- 2.6.4
-
getRemoteFilename
public java.lang.String getRemoteFilename()
ForgoToRemote(java.lang.String, int, float, float, float)
,goToFitRemoteRectangle(java.lang.String, int, float, float, float, float)
andgoToEmbedded(java.lang.String, int, float, float, float)
actions, return the file name that this action refers to. For other types of action this method returns null.- Since:
- 2.6.4
-
toString
public java.lang.String toString()
-
putLiteral
public void putLiteral(java.lang.String key, java.lang.String tokens)
Put a literal token sequnce. For debugging- Parameters:
key
- the keytokens
- the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.
-
clone
protected java.lang.Object clone()
- Overrides:
clone
in classjava.lang.Object
-
-