PDFAction


1   // $Id: PDFAction.java,v 1.3 2003/10/06 12:40:07 mike Exp $
2   
3   package org.faceless.pdf;
4   
5   import java.util.*;
6   
7   /**
8    * <p>
9    * An action tells the PDF viewer how to navigate around the document.
10   * Actions are performed when the user clicks on a <code>PDFBookmark</code>,
11   * when a {@link Form} element specifies an event, or optionally when a
12   * document is opened (if the PDF's <code>setOpenAction</code> method is called).
13   * </p><p>
14   * The <code>PDFAction</code> class has no public constructor, just a number of
15   * static methods returning a new action of the specified type.
16   * </p>
17   * @version $Revision: 1.3 $
18   */
19  public final class PDFAction extends PeeredObject
20  {
21      /**
22       * Method for the {@link #formSubmit} action specifying that the form should
23       * be submitted as a standard HTTP GET, in the same way as an HTML form. 
24       * <i><b>Note:</b> we've recently found some problems with submission via an
25       * HTTP GET - specifically it doesn't work from a browser with Acrobat 5.
26       * For this reason we strongly recommend using {@link #METHOD_HTTP_POST}
27       * instead</i>
28       */
29      public static final int METHOD_HTTP_GET = 4+8;
30  
31      /**
32       * Method for the {@link #formSubmit} action specifying that the form should
33       * be submitted as a standard HTTP GET, in the same way as an HTML form. The
34       * co-ordinates where the submit button was clicked are included in the
35       * submission as <i>name.x</i> and <i>name.y</i>, where name is the name of
36       * the submit button that was clicked.
37       * </p><p>
38       * <i><b>Note:</b> we've recently found some problems with submission via an
39       * HTTP GET - specifically it doesn't work from a browser with the Acrobat 5
40       * plugin. For this reason we strongly recommend using
41       * {@link #METHOD_HTTP_IMAGEMAP_POST} instead</i>
42       * </p>
43       */
44      public static final int METHOD_HTTP_IMAGEMAP_GET = 4+8+16;
45  
46      /**
47       * Method for the {@link #formSubmit} action specifying that the form should
48       * be submitted as a standard HTTP POST, in the same way as an HTML form
49       */
50      public static final int METHOD_HTTP_POST = 4;
51  
52      /**
53       * Method for the {@link #formSubmit} action specifying that the form should
54       * be submitted as a standard HTTP POST, in the same way as an HTML form. The
55       * co-ordinates where the submit button was clicked are included in the
56       * submission as <i>name.x</i> and <i>name.y</i>, where name is the name of
57       * the submit button that was clicked.
58       */
59      public static final int METHOD_HTTP_IMAGEMAP_POST = 4+16;
60  
61      /**
62       * Method for the {@link #formSubmit} action specifying that the form should
63       * be submitted in the Adobe Forms Data Format.
64       */
65      public static final int METHOD_FDF = 0;
66  
67      /**
68       * Method for the {@link #formSubmit} action specifying that the form should
69       * be submitted as XML.
70       * This method requires PDF 1.4 (Acrobat 5.0) or later.
71       */
72      public static final int METHOD_XML = 32;
73  
74      /**
75       * Method for the {@link #formSubmit} action specifying that the form should
76       * be submitted in the Adobe Forms Data Format, and that it should include
77       * all the annotations in the document.
78       * This method requires PDF 1.4 (Acrobat 5.0) or later.
79       */
80      public static final int METHOD_FDF_WITH_ALL_ANNOTATIONS = 128;
81  
82      /**
83       * Method for the {@link #formSubmit} action specifying that the form should
84       * be submitted in the Adobe Forms Data Format, and that it should include
85       * any annotations that have been created by the "current user". The spec is
86       * a bit vague on how the current user is determined, but we include this method
87       * for completeness.
88       * This method requires PDF 1.4 (Acrobat 5.0) or later.
89       */
90      public static final int METHOD_FDF_WITH_MY_ANNOTATIONS = 128+1024;
91      
92      /**
93       * Method for the {@link #formSubmit} action specifying that the form should
94       * be submitted as a PDF.
95       * This method requires PDF 1.4 (Acrobat 5.0) or later.
96       */
97      public static final int METHOD_PDF = 256;
98  
99  
100     final org.faceless.pdf2.PDFAction action;
101 
102     PDFAction(org.faceless.pdf2.PDFAction action)
103     {
104         this.action=action;
105     }
106 
107     Object   getPeer()
108     {
109         return action;
110     }
111 
112     /**
113      * Return a new PDFAction which jumps to the specified page in the
114      * PDF document. The position and zoom on the new page is the same
115      * as that of the original page.
116      * @param page the page this action should jump to
117      */
118     public static PDFAction goTo(PDFPage page)
119     {
120     return new PDFAction(org.faceless.pdf2.PDFAction.goTo(page.page));
121     }
122 
123     /**
124      * Return a new PDFAction which jumps to the specified page in the
125      * PDF document, at the specified x, y and zoom level.
126      * @param page the page this action should jump to.
127      * @param x the X position on the new page to scroll to, or <code>Float.NaN</code> to keep the X position unchanged.
128      * @param x the Y position on the new page to scroll to, or <code>Float.NaN</code> to keep the Y position unchanged.
129      * @param zoom The zoom level. A value of 0 or <code>Float.NaN</code> leaves the zoom unchanged, 1 sets the zoom to 100%, 2 to 200% and so on.
130      */
131     public static PDFAction goTo(PDFPage page, float x, float y, float zoom)
132     {
133     return new PDFAction(org.faceless.pdf2.PDFAction.goTo(page.page,x,y,zoom));
134     }
135 
136     /**
137      * Return a new PDFAction which jumps to the specified page in the PDF document. The
138      * zoom level is set so that the entire page fits within the viewers window.
139      *
140      * @param page the page this action should jump to
141      */
142     public static PDFAction goToFit(PDFPage page)
143     {
144     return new PDFAction(org.faceless.pdf2.PDFAction.goToFit(page.page));
145     }
146 
147     /**
148      * Return a new PDFAction which jumps to the specified page in the PDF document. The
149      * zoom level is set so that the width of the page fits within the viewers window.
150      *
151      * @param page the page this action should jump to
152      * @param y if the page is too tall to fit in the windows, the Y position on the new
153      * page to scroll to.
154      */
155     public static PDFAction goToFitWidth(PDFPage page, float y)
156     {
157     return new PDFAction(org.faceless.pdf2.PDFAction.goToFitWidth(page.page,y));
158     }
159 
160     /**
161      * Return a new PDFAction which jumps to the specified page in the PDF document. The
162      * zoom level is set so that the full height of the page fits within the viewers window.
163      *
164      * @param page The page this action should jump to.
165      * @param x if the page is too wide to fit in the windows, the X position on the new
166      * page to scroll to.
167      */
168     public static PDFAction goToFitHeight(PDFPage page, float x)
169     {
170     return new PDFAction(org.faceless.pdf2.PDFAction.goToFitHeight(page.page,x));
171     }
172 
173     /**
174      * Return a new PDFAction which jumps to the specified page in the PDF document. The
175      * zoom level is set so that the rectangle specified fills the screen
176      *
177      * @param page the page this action should jump to
178      * @param left the left edge of the visible rectangle
179      * @param bottom the bottom edge of the visible rectangle
180      * @param width the width of the visible rectangle
181      * @param height the height of the visible rectangle
182      */
183     public static PDFAction goToFitRectangle(PDFPage page, float left, float bottom, float width, float height)
184     {
185     return new PDFAction(org.faceless.pdf2.PDFAction.goToFitRectangle(page.page,left,bottom,width,height));
186     }
187 
188     /**
189      * Return a new PDFAction which jumps to the specified URL.
190      * @since 1.1
191      */
192     public static PDFAction goToURL(java.net.URL   url)
193     {
194     return new PDFAction(org.faceless.pdf2.PDFAction.goToURL(url));
195     }
196 
197     /**
198      * Return a new PDFAction which jumps to the specified URL. When used
199      * from a {@link PDFAnnotation}, the annotation rectangle is treated
200      * as a Server-Side ImageMap. So for example, if the user clicks 20 points
201      * from the left and 30 points from the top of the link rectangle, the
202      * URL that is loaded is <code>http://www.url.com/?20,30</code>.
203      * @since 1.1
204      */
205     public static PDFAction goToURL(java.net.URL   url, boolean isImageMap)
206     {
207     return new PDFAction(org.faceless.pdf2.PDFAction.goToURL(url,isImageMap));
208     }
209 
210     /**
211      * Return a new PDFAction which plays a {@link PDFSound} when activated.
212      * This simpler of the two playSound methods plays the sound once at full
213      * volume and with mixing turned off. See the {@link PDFSound} class
214      * for more information on limitations with sound in PDF documents.
215      * @since 1.1
216      */
217     public static PDFAction playSound(PDFSound sound)
218     {
219     return new PDFAction(org.faceless.pdf2.PDFAction.playSound(sound.sound));
220     }
221 
222     /**
223      * Return a new PDFAction which plays a {@link PDFSound} when activated.
224      * @param sound the {@link PDFSound} to play.
225      * @param volume the volume of the sound, from 0 (off) to 100 (maximum)
226      * @param repeat whether to play the sound continuously or just once
227      * @param mix whether to mix the sound in with any other playing samples, or replace them
228      * @since 1.1
229      */
230     public static PDFAction playSound(PDFSound sound, int volume, boolean repeat, boolean mix)
231     {
232     return new PDFAction(org.faceless.pdf2.PDFAction.playSound(sound.sound, volume, repeat, mix));
233     }
234 
235     /**
236      * <p>Return a new PDFAction which runs the named action. Named actions
237      * are PDF viewer dependent, so should be used with care. The following
238      * actions are among those known to work in Acrobat 3 and 4 readers, and
239      * loosely correspond to the equivalent actions available from the menus
240      * in Acrobat.
241      * </p>
242      * <ul>
243      * <li>Document Control<BR>
244      * <tt>Open Close Print GeneralInfo FontsInfo SecurityInfo Quit</tt>
245      * </li>
246      * <li>Document Navigation<BR>
247      * <tt>NextPage PrevPage FirstPage LastPage GoToPage</tt>
248      * </li>
249      * <li>Searching and Selecting<BR>
250      * <tt>Find FindAgain SelectAll Copy</tt>
251      * </li>
252      * <li>Display<BR>
253      * <tt>FullScreen ZoomTo FitPage ZoomTo ActualSize FitWidth
254      * FitVisible SinglePage OneColumn TwoColumns</tt>
255      * </li>
256      * </ul>
257      * @since 1.1
258      */
259     public static PDFAction named(String   name)
260     {
261     return new PDFAction(org.faceless.pdf2.PDFAction.named(name));
262     }
263 
264     /**
265      * Return a new PDFAction which makes the specified {@link FormElement}
266      * visible on screen.
267      * @param element the form element to modify
268      * @see #hideElement
269      * @since 1.1.23
270      */
271     public static PDFAction showElement(FormElement element)
272     {
273     return (PDFAction)PeeredObject.getPeer(org.faceless.pdf2.PDFAction.showWidget(element.element.getAnnotation(0)));
274     }
275 
276     /**
277      * Return a new PDFAction which hides the specified {@link FormElement}.
278      * @param element the form element to modify
279      * @see #showElement
280      * @since 1.1.23
281      */
282     public static PDFAction hideElement(FormElement element)
283     {
284     return (PDFAction)PeeredObject.getPeer(org.faceless.pdf2.PDFAction.hideWidget(element.element.getAnnotation(0)));
285     }
286 
287     /**
288      * Return a new PDFAction which submits the documents AcroForm. This should
289      * be used as the <code>ONCLICK</code> event for a {@link FormButton}
290      * somewhere in the form, so the form can be submitted.
291      * </p><p>
292      * The method parameter can be one of the various {@link #METHOD_HTTP_GET METHOD}
293      * values, although please note that many of these values are only implemented in
294      * Acrobat 5.0 or later.
295      * </p>
296      * @param url the URL to submit the form to
297      * @param method the method to use when submitting the form
298      * @since 1.1.23
299      * @see Form
300      */
301     public static PDFAction formSubmit(String   url, int method)
302     {
303     int newmethod;
304     if (method==METHOD_FDF)             newmethod=org.faceless.pdf2.PDFAction.METHOD_FDF;
305     else if (method==METHOD_PDF)            newmethod=org.faceless.pdf2.PDFAction.METHOD_PDF;
306     else if (method==METHOD_HTTP_POST)      newmethod=org.faceless.pdf2.PDFAction.METHOD_HTTP_POST;
307     else if (method==METHOD_HTTP_IMAGEMAP_POST) newmethod=org.faceless.pdf2.PDFAction.METHOD_HTTP_IMAGEMAP_POST;
308     else if (method==METHOD_XML)            newmethod=org.faceless.pdf2.PDFAction.METHOD_XML;
309     else if (method==METHOD_FDF_WITH_ALL_ANNOTATIONS)   newmethod=org.faceless.pdf2.PDFAction.METHOD_FDF_WITH_ALL_ANNOTATIONS;
310     else if (method==METHOD_FDF_WITH_MY_ANNOTATIONS)    newmethod=org.faceless.pdf2.PDFAction.METHOD_FDF_WITH_MY_ANNOTATIONS;
311     else throw new IllegalArgumentException  ("No such method type");
312 
313     return new PDFAction(org.faceless.pdf2.PDFAction.formSubmit(url, newmethod));
314     }
315 
316     /**
317      * Return a new <code>PDFAction</code> which resets the documents AcroForm,
318      * setting every field to its default values.
319      * @since 1.1.23
320      * @see Form
321      */
322     public static PDFAction formReset()
323     {
324     return new PDFAction(org.faceless.pdf2.PDFAction.formReset());
325     }
326 
327     /**
328      * Return a new <code>PDFAction</code> which imports a Forms Data Format (FDF)
329      * file into the document AcroForm, setting some or all of the forms values.
330      * @param file the name of the file containing the FDF. The file is relative to
331      * the location of the current document
332      * @since 1.1.23
333      * @see Form
334      */
335     public static PDFAction formImportData(String   file)
336     {
337     return new PDFAction(org.faceless.pdf2.PDFAction.formImportData(file));
338     }
339 
340     /**
341      * <p>
342      * Return a new <code>PDFAction</code> which executes a JavaScript action.
343      * This is generally used with AcroForms, although in theory it doesn't
344      * have to be. It's generally better design to create functions in the
345      * document-wide JavaScript (as set by {@link PDF#setJavaScript}) and just
346      * use these actions to call those methods.
347      * </p>
348      * @param javascript the JavaScript action to perform
349      * @since 1.1.23
350      * @see PDF#setJavaScript
351      * @see PDF#getJavaScript
352      * @see Form
353      */
354     public static PDFAction formJavaScript(String   javascript)
355     {
356     return new PDFAction(org.faceless.pdf2.PDFAction.formJavaScript(javascript));
357     }
358 
359     /**
360      * The <code>setNext</code> method allows you to create "chains" of actions
361      * which are executed whenever the first entry in the chain is run. This
362      * allows more complicated processing - for example, clicking on a button
363      * could play a sound and then jump to a specific page.
364      * </p><p>
365      * Avoiding infinite action loops is the responsibility of the programmer.
366      * </p>
367      * @param action the action to execute after the current one, or
368      * <code>null</code> to clear it.
369      * @since 1.1
370      */
371     public void setNext(PDFAction a)
372     {
373     action.setNext(a==null ? null : a.action);
374     }
375 
376     /**
377      * Return the action that's next in the chain after this one, or
378      * <code>null</code> if no further actions are defined.
379      * @since 1.1
380      */
381     public PDFAction getNext()
382     {
383     return (PDFAction)PeeredObject.getPeer(action.getNext());
384     }
385 
386     /**
387      * <p>
388      * Return the type of action. Can be "Named:<i>value</i>" (where "value" is the
389      * named action that's performed), "URL", "Sound", "GoTo", 
390      * "GoToFitRectangle", "GoToFit", "GoToFitHeight", "GoToFitWidth",
391      * "ShowElement", "HideElement", "FormReset", "FormImportData", "FormSubmit",
392      * "FormJavaScript" or one of another type of action supported by
393      * the PDF specification but not by this library ("Launch", "Thread" or "Movie").
394      * </p><p>
395      * Note since 1.1.23 the URL value no longer includes the URL being referenced - use
396      * the {@link #getURL} method to retrieve that value
397      * </p>
398      * @return the type of action this object represents
399      * @since 1.1.12
400      */
401     public String   getType()
402     {
403     return action.getType();
404     }
405 
406     /**
407      * For actions that refer to a page - any of the "GoTo" actions except "GoToURL" -
408      * return the page the action refers to. For other types of action, returns
409      * <tt>null</tt>.
410      * @return the page this action refers to, or <tt>null</tt> if not applicable.
411      * @since 1.1.12
412      */
413     public PDFPage getPage()
414     {
415     return (PDFPage)PeeredObject.getPeer(action.getPage());
416     }
417 
418     /**
419      * For "Sound" actions, return the PDFSound object this action refers to.
420      * For other types of action this returns <tt>null</tt>
421      * @return the sound this action refers to, or <tt>null</tt> if not applicable.
422      * @since 1.1.12
423      */
424     public PDFSound getSound()
425     {
426     return (PDFSound)PeeredObject.getPeer(action.getSound());
427     }
428 
429     /**
430      * For <code>toggleAnnotation</code> type annotations,
431      * return the annotation that is being toggled.
432      * @return the annotation this action refers to, or <tt>null</tt> if not applicable.
433      * @since 1.1.22
434      */
435     public PDFAnnotation getAnnotation()
436     {
437     return (PDFAnnotation)PeeredObject.getPeer(action.getAnnotation());
438     }
439 
440     /**
441      * For <code>JavaScript</code> type annotations, return the JavaScript
442      * that is being executed. For other annotations, return <code>null</code>.
443      * @return the JavaScript that is executed or <tt>null</tt> if not applicable.
444      * @since 1.1.23
445      */
446     public String   getJavaScript()
447     {
448     return action.getJavaScript();
449     }
450 
451     /**
452      * For <tt>formSubmit</tt>, <tt>goToURL</tt> and <tt>formImportData</tt>
453      * actions, return the URL that is the destination of the action (or source
454      * of the data). For other annotations, return <code>null</code>
455      * @return the URL of the action
456      * @since 1.1.23
457      */
458     public String   getURL()
459     {
460     return action.getURL();
461     }
462 
463     /**
464      * For <tt>formSubmit</tt> actions, return the method by which the
465      * form is submitted - one of the {@link #METHOD_HTTP_GET METHOD} parameters
466      * defined in this class. For other action types the return is -1
467      * @return the submit method for this <code>formSubmit</code> action
468      * @since 1.1.23
469      */
470     public int getFormSubmitMethod()
471     {
472     return action.getFormSubmitMethod();
473     }
474 
475     /**
476      * Return the co-ordinates of a GoTo action. Some "GoTo" actions take
477      * one or more coordinates which determine which section of the specified
478      * page should be displayed. Examples of this are the
479      * {@link #goToFitRectangle goToFitRectangle} method, which takes four parameters,
480      * and the {@link #goToFitWidth goToFitWidth} method, which takes one. These
481      * coordinates can be read by calling this method, which returns an array
482      * of floats, the length of which varies depending on the type of GoTo
483      * action. Specifically, "GoToFitWidth" and "GoToFitHeight" methods
484      * return an array of one float, "GoToFitRectangle" will return four and
485      * "GoTo" will return three. For this last one, the first number represents
486      * the "X" coordinate, the second the "Y" and the third the zoom level, but
487      * it's important to remember that any one of these may be unspecified -
488      * in this case the value is set to <code>Float.NaN</code>.
489      * @since 1.2
490      */
491     public float[] getGoToCoordinates()
492     {
493     return action.getGoToCoordinates();
494     }
495 
496     public String   toString()
497     {
498     String   t = getType();
499     String   out = "<action type=\""+t+"\"";
500     if (getJavaScript()!=null) out+=" javascript=\""+getJavaScript()+"\"";
501     if (getSound()!=null) out+=" sound=\""+getSound()+"\"";
502     if (getPage()!=null) out+=" page=\""+getPage()+"\"";
503     if (getNext()!=null) out+=" next=\""+getNext()+"\"";
504     float[] f = getGoToCoordinates();
505     if (f.length>0) {
506         out+=" coords=";
507         for (int i=0;i<f.length;i++) {
508             out += (i==0 ? "\"" : ",")+f[i];
509         }
510         out+="\"";
511     }
512     return out+"/>";
513     }
514 }
515
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags