PdfAction


1   /*
2    * $Id: PdfAction.java 2526 2007-01-14 09:43:13Z blowagie $
3    * $Name$
4    *
5    * Copyright 2001, 2002 by Bruno Lowagie.
6    *
7    * The contents of this file are subject to the Mozilla Public License Version 1.1
8    * (the "License"); you may not use this file except in compliance with the License.
9    * You may obtain a copy of the License at http://www.mozilla.org/MPL/
10   *
11   * Software distributed under the License is distributed on an "AS IS" basis,
12   * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13   * for the specific language governing rights and limitations under the License.
14   *
15   * The Original Code is 'iText, a free JAVA-PDF library'.
16   *
17   * The Initial Developer of the Original Code is Bruno Lowagie. Portions created by
18   * the Initial Developer are Copyright (C) 1999, 2000, 2001, 2002 by Bruno Lowagie.
19   * All Rights Reserved.
20   * Co-Developer of the code is Paulo Soares. Portions created by the Co-Developer
21   * are Copyright (C) 2000, 2001, 2002 by Paulo Soares. All Rights Reserved.
22   *
23   * Contributor(s): all the names of the contributors are added in the source code
24   * where applicable.
25   *
26   * Alternatively, the contents of this file may be used under the terms of the
27   * LGPL license (the "GNU LIBRARY GENERAL PUBLIC LICENSE"), in which case the
28   * provisions of LGPL are applicable instead of those above.  If you wish to
29   * allow use of your version of this file only under the terms of the LGPL
30   * License and not to allow others to use your version of this file under
31   * the MPL, indicate your decision by deleting the provisions above and
32   * replace them with the notice and other provisions required by the LGPL.
33   * If you do not delete the provisions above, a recipient may use your version
34   * of this file under either the MPL or the GNU LIBRARY GENERAL PUBLIC LICENSE.
35   *
36   * This library is free software; you can redistribute it and/or modify it
37   * under the terms of the MPL as stated above or under the terms of the GNU
38   * Library General Public License as published by the Free Software Foundation;
39   * either version 2 of the License, or any later version.
40   *
41   * This library is distributed in the hope that it will be useful, but WITHOUT
42   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
43   * FOR A PARTICULAR PURPOSE. See the GNU Library general Public License for more
44   * details.
45   *
46   * If you didn't download this code from the following link, you should check if
47   * you aren't using an obsolete version:
48   * http://www.lowagie.com/iText/
49   */
50  
51  package com.lowagie.text.pdf;
52  
53  import java.io.IOException  ;
54  import java.net.URL  ;
55  import java.util.ArrayList  ;
56  
57  import com.lowagie.text.ExceptionConverter;
58  import com.lowagie.text.pdf.collection.PdfTargetDictionary;
59  
60  /**
61   * A <CODE>PdfAction</CODE> defines an action that can be triggered from a PDF file.
62   *
63   * @see     PdfDictionary
64   */
65  
66  public class PdfAction extends PdfDictionary {
67      
68      /** A named action to go to the first page.
69       */
70      public static final int FIRSTPAGE = 1;
71      /** A named action to go to the previous page.
72       */
73      public static final int PREVPAGE = 2;
74      /** A named action to go to the next page.
75       */
76      public static final int NEXTPAGE = 3;
77      /** A named action to go to the last page.
78       */
79      public static final int LASTPAGE = 4;
80  
81      /** A named action to open a print dialog.
82       */
83      public static final int PRINTDIALOG = 5;
84  
85      /** a possible submitvalue */
86      public static final int SUBMIT_EXCLUDE = 1;
87      /** a possible submitvalue */
88      public static final int SUBMIT_INCLUDE_NO_VALUE_FIELDS = 2;
89      /** a possible submitvalue */
90      public static final int SUBMIT_HTML_FORMAT = 4;
91      /** a possible submitvalue */
92      public static final int SUBMIT_HTML_GET = 8;
93      /** a possible submitvalue */
94      public static final int SUBMIT_COORDINATES = 16;
95      /** a possible submitvalue */
96      public static final int SUBMIT_XFDF = 32;
97      /** a possible submitvalue */
98      public static final int SUBMIT_INCLUDE_APPEND_SAVES = 64;
99      /** a possible submitvalue */
100     public static final int SUBMIT_INCLUDE_ANNOTATIONS = 128;
101     /** a possible submitvalue */
102     public static final int SUBMIT_PDF = 256;
103     /** a possible submitvalue */
104     public static final int SUBMIT_CANONICAL_FORMAT = 512;
105     /** a possible submitvalue */
106     public static final int SUBMIT_EXCL_NON_USER_ANNOTS = 1024;
107     /** a possible submitvalue */
108     public static final int SUBMIT_EXCL_F_KEY = 2048;
109     /** a possible submitvalue */
110     public static final int SUBMIT_EMBED_FORM = 8196;
111     /** a possible submitvalue */
112     public static final int RESET_EXCLUDE = 1;
113 
114     // constructors
115     
116     /** Create an empty action.
117      */    
118     public PdfAction() {
119     }
120     
121     /**
122      * Constructs a new <CODE>PdfAction</CODE> of Subtype URI.
123      *
124      * @param url the Url to go to
125      */
126     
127     public PdfAction(URL   url) {
128         this(url.toExternalForm());
129     }
130     
131     /**
132      * Construct a new <CODE>PdfAction</CODE> of Subtype URI that accepts the x and y coordinate of the position that was clicked.
133      * @param url
134      * @param isMap
135      */
136     public PdfAction(URL   url, boolean isMap) {
137         this(url.toExternalForm(), isMap);
138     }
139     
140     /**
141      * Constructs a new <CODE>PdfAction</CODE> of Subtype URI.
142      *
143      * @param url the url to go to
144      */
145     
146     public PdfAction(String   url) {
147         this(url, false);
148     }
149     
150     /**
151      * Construct a new <CODE>PdfAction</CODE> of Subtype URI that accepts the x and y coordinate of the position that was clicked.
152      * @param url
153      * @param isMap
154      */
155     
156     public PdfAction(String   url, boolean isMap) {
157         put(PdfName.S, PdfName.URI);
158         put(PdfName.URI, new PdfString(url));
159         if (isMap)
160             put(PdfName.ISMAP, PdfBoolean.PDFTRUE);
161     }
162     
163     /**
164      * Constructs a new <CODE>PdfAction</CODE> of Subtype GoTo.
165      * @param destination the destination to go to
166      */
167     
168     PdfAction(PdfIndirectReference destination) {
169         put(PdfName.S, PdfName.GOTO);
170         put(PdfName.D, destination);
171     }
172     
173     /**
174      * Constructs a new <CODE>PdfAction</CODE> of Subtype GoToR.
175      * @param filename the file name to go to
176      * @param name the named destination to go to
177      */
178     
179     public PdfAction(String   filename, String   name) {
180         put(PdfName.S, PdfName.GOTOR);
181         put(PdfName.F, new PdfString(filename));
182         put(PdfName.D, new PdfString(name));
183     }
184     
185     /**
186      * Constructs a new <CODE>PdfAction</CODE> of Subtype GoToR.
187      * @param filename the file name to go to
188      * @param page the page destination to go to
189      */
190     
191     public PdfAction(String   filename, int page) {
192         put(PdfName.S, PdfName.GOTOR);
193         put(PdfName.F, new PdfString(filename));
194         put(PdfName.D, new PdfLiteral("[" + (page - 1) + " /FitH 10000]"));
195     }
196     
197     /** Implements name actions. The action can be FIRSTPAGE, LASTPAGE,
198      * NEXTPAGE, PREVPAGE and PRINTDIALOG.
199      * @param named the named action
200      */
201     public PdfAction(int named) {
202         put(PdfName.S, PdfName.NAMED);
203         switch (named) {
204             case FIRSTPAGE:
205                 put(PdfName.N, PdfName.FIRSTPAGE);
206                 break;
207             case LASTPAGE:
208                 put(PdfName.N, PdfName.LASTPAGE);
209                 break;
210             case NEXTPAGE:
211                 put(PdfName.N, PdfName.NEXTPAGE);
212                 break;
213             case PREVPAGE:
214                 put(PdfName.N, PdfName.PREVPAGE);
215                 break;
216             case PRINTDIALOG:
217                 put(PdfName.S, PdfName.JAVASCRIPT);
218                 put(PdfName.JS, new PdfString("this.print(true);\r"));
219                 break;
220             default:
221                 throw new RuntimeException  ("Invalid named action.");
222         }
223     }
224     
225     /** Launchs an application or a document.
226      * @param application the application to be launched or the document to be opened or printed.
227      * @param parameters (Windows-specific) A parameter string to be passed to the application.
228      * It can be <CODE>null</CODE>.
229      * @param operation (Windows-specific) the operation to perform: "open" - Open a document,
230      * "print" - Print a document.
231      * It can be <CODE>null</CODE>.
232      * @param defaultDir (Windows-specific) the default directory in standard DOS syntax.
233      * It can be <CODE>null</CODE>.
234      */
235     public PdfAction(String   application, String   parameters, String   operation, String   defaultDir) {
236         put(PdfName.S, PdfName.LAUNCH);
237         if (parameters == null && operation == null && defaultDir == null)
238             put(PdfName.F, new PdfString(application));
239         else {
240             PdfDictionary dic = new PdfDictionary();
241             dic.put(PdfName.F, new PdfString(application));
242             if (parameters != null)
243                 dic.put(PdfName.P, new PdfString(parameters));
244             if (operation != null)
245                 dic.put(PdfName.O, new PdfString(operation));
246             if (defaultDir != null)
247                 dic.put(PdfName.D, new PdfString(defaultDir));
248             put(PdfName.WIN, dic);
249         }
250     }
251     
252     /** Launchs an application or a document.
253      * @param application the application to be launched or the document to be opened or printed.
254      * @param parameters (Windows-specific) A parameter string to be passed to the application.
255      * It can be <CODE>null</CODE>.
256      * @param operation (Windows-specific) the operation to perform: "open" - Open a document,
257      * "print" - Print a document.
258      * It can be <CODE>null</CODE>.
259      * @param defaultDir (Windows-specific) the default directory in standard DOS syntax.
260      * It can be <CODE>null</CODE>.
261      * @return a Launch action
262      */
263     public static PdfAction createLaunch(String   application, String   parameters, String   operation, String   defaultDir) {
264         return new PdfAction(application, parameters, operation, defaultDir);
265     }
266     
267      /**Creates a Rendition action
268      * @param file
269      * @param fs
270      * @param mimeType
271      * @param ref
272      * @return a Media Clip action
273      * @throws IOException
274      */
275     public static PdfAction rendition(String   file, PdfFileSpecification fs, String   mimeType, PdfIndirectReference ref) throws IOException   {
276         PdfAction js = new PdfAction();
277         js.put(PdfName.S, PdfName.RENDITION);
278         js.put(PdfName.R, new PdfRendition(file, fs, mimeType));
279         js.put(new PdfName("OP"), new PdfNumber(0));
280         js.put(new PdfName("AN"), ref);
281         return js;
282      }
283   
284     /** Creates a JavaScript action. If the JavaScript is smaller than
285      * 50 characters it will be placed as a string, otherwise it will
286      * be placed as a compressed stream.
287      * @param code the JavaScript code
288      * @param writer the writer for this action
289      * @param unicode select JavaScript unicode. Note that the internal
290      * Acrobat JavaScript engine does not support unicode,
291      * so this may or may not work for you
292      * @return the JavaScript action
293      */    
294     public static PdfAction javaScript(String   code, PdfWriter writer, boolean unicode) {
295         PdfAction js = new PdfAction();
296         js.put(PdfName.S, PdfName.JAVASCRIPT);
297         if (unicode && code.length() < 50) {
298                 js.put(PdfName.JS, new PdfString(code, PdfObject.TEXT_UNICODE));
299         }
300         else if (!unicode && code.length() < 100) {
301                 js.put(PdfName.JS, new PdfString(code));
302         }
303         else {
304             try {
305                 byte b[] = PdfEncodings.convertToBytes(code, unicode ? PdfObject.TEXT_UNICODE : PdfObject.TEXT_PDFDOCENCODING);
306                 PdfStream stream = new PdfStream(b);
307                 stream.flateCompress();
308                 js.put(PdfName.JS, writer.addToBody(stream).getIndirectReference());
309             }
310             catch (Exception   e) {
311                 throw new ExceptionConverter(e);
312             }
313         }
314         return js;
315     }
316 
317     /** Creates a JavaScript action. If the JavaScript is smaller than
318      * 50 characters it will be place as a string, otherwise it will
319      * be placed as a compressed stream.
320      * @param code the JavaScript code
321      * @param writer the writer for this action
322      * @return the JavaScript action
323      */    
324     public static PdfAction javaScript(String   code, PdfWriter writer) {
325         return javaScript(code, writer, false);
326     }
327     
328     /**
329      * A Hide action hides or shows an object.
330      * @param obj object to hide or show
331      * @param hide true is hide, false is show
332      * @return a Hide Action
333      */
334     static PdfAction createHide(PdfObject obj, boolean hide) {
335         PdfAction action = new PdfAction();
336         action.put(PdfName.S, PdfName.HIDE);
337         action.put(PdfName.T, obj);
338         if (!hide)
339             action.put(PdfName.H, PdfBoolean.PDFFALSE);
340         return action;
341     }
342     
343     /**
344      * A Hide action hides or shows an annotation.
345      * @param annot
346      * @param hide
347      * @return A Hide Action
348      */
349     public static PdfAction createHide(PdfAnnotation annot, boolean hide) {
350         return createHide(annot.getIndirectReference(), hide);
351     }
352     
353     /**
354      * A Hide action hides or shows an annotation.
355      * @param name
356      * @param hide
357      * @return A Hide Action
358      */
359     public static PdfAction createHide(String   name, boolean hide) {
360         return createHide(new PdfString(name), hide);
361     }
362     
363     static PdfArray buildArray(Object   names[]) {
364         PdfArray array = new PdfArray();
365         for (int k = 0; k < names.length; ++k) {
366             Object   obj = names[k];
367             if (obj instanceof String  )
368                 array.add(new PdfString((String  )obj));
369             else if (obj instanceof PdfAnnotation)
370                 array.add(((PdfAnnotation)obj).getIndirectReference());
371             else
372                 throw new RuntimeException  ("The array must contain String or PdfAnnotation.");
373         }
374         return array;
375     }
376     
377     /**
378      * A Hide action hides or shows objects.
379      * @param names
380      * @param hide
381      * @return A Hide Action
382      */
383     public static PdfAction createHide(Object   names[], boolean hide) {
384         return createHide(buildArray(names), hide);
385     }
386     
387     /**
388      * Creates a submit form.
389      * @param file  the URI to submit the form to
390      * @param names the objects to submit
391      * @param flags submit properties
392      * @return A PdfAction
393      */
394     public static PdfAction createSubmitForm(String   file, Object   names[], int flags) {
395         PdfAction action = new PdfAction();
396         action.put(PdfName.S, PdfName.SUBMITFORM);
397         PdfDictionary dic = new PdfDictionary();
398         dic.put(PdfName.F, new PdfString(file));
399         dic.put(PdfName.FS, PdfName.URL);
400         action.put(PdfName.F, dic);
401         if (names != null)
402             action.put(PdfName.FIELDS, buildArray(names));
403         action.put(PdfName.FLAGS, new PdfNumber(flags));
404         return action;
405     }
406     
407     /**
408      * Creates a resetform.
409      * @param names the objects to reset
410      * @param flags submit properties
411      * @return A PdfAction
412      */
413     public static PdfAction createResetForm(Object   names[], int flags) {
414         PdfAction action = new PdfAction();
415         action.put(PdfName.S, PdfName.RESETFORM);
416         if (names != null)
417             action.put(PdfName.FIELDS, buildArray(names));
418         action.put(PdfName.FLAGS, new PdfNumber(flags));
419         return action;
420     }
421     
422     /**
423      * Creates an Import field.
424      * @param file
425      * @return A PdfAction
426      */
427     public static PdfAction createImportData(String   file) {
428         PdfAction action = new PdfAction();
429         action.put(PdfName.S, PdfName.IMPORTDATA);
430         action.put(PdfName.F, new PdfString(file));
431         return action;
432     }
433     
434     /** Add a chained action.
435      * @param na the next action
436      */    
437     public void next(PdfAction na) {
438         PdfObject nextAction = get(PdfName.NEXT);
439         if (nextAction == null)
440             put(PdfName.NEXT, na);
441         else if (nextAction.isDictionary()) {
442             PdfArray array = new PdfArray(nextAction);
443             array.add(na);
444             put(PdfName.NEXT, array);
445         }
446         else {
447             ((PdfArray)nextAction).add(na);
448         }
449     }
450     
451     /** Creates a GoTo action to an internal page.
452      * @param page the page to go. First page is 1
453      * @param dest the destination for the page
454      * @param writer the writer for this action
455      * @return a GoTo action
456      */    
457     public static PdfAction gotoLocalPage(int page, PdfDestination dest, PdfWriter writer) {
458         PdfIndirectReference ref = writer.getPageReference(page);
459         dest.addPage(ref);
460         PdfAction action = new PdfAction();
461         action.put(PdfName.S, PdfName.GOTO);
462         action.put(PdfName.D, dest);
463         return action;
464     }
465 
466     /**
467      * Creates a GoTo action to a named destination.
468      * @param dest the named destination
469      * @param isName if true sets the destination as a name, if false sets it as a String
470      * @return a GoTo action
471      */
472     public static PdfAction gotoLocalPage(String   dest, boolean isName) {
473         PdfAction action = new PdfAction();
474         action.put(PdfName.S, PdfName.GOTO);
475         if (isName)
476             action.put(PdfName.D, new PdfName(dest));
477         else
478             action.put(PdfName.D, new PdfString(dest, null));
479         return action;
480     }
481 
482     /**
483      * Creates a GoToR action to a named destination.
484      * @param filename the file name to go to
485      * @param dest the destination name
486      * @param isName if true sets the destination as a name, if false sets it as a String
487      * @param newWindow open the document in a new window if <CODE>true</CODE>, if false the current document is replaced by the new document.
488      * @return a GoToR action
489      */
490     public static PdfAction gotoRemotePage(String   filename, String   dest, boolean isName, boolean newWindow) {
491         PdfAction action = new PdfAction();
492         action.put(PdfName.F, new PdfString(filename));
493         action.put(PdfName.S, PdfName.GOTOR);
494         if (isName)
495             action.put(PdfName.D, new PdfName(dest));
496         else
497             action.put(PdfName.D, new PdfString(dest, null));
498         if (newWindow)
499             action.put(PdfName.NEWWINDOW, PdfBoolean.PDFTRUE);
500         return action;
501     }
502 
503     /**
504      * Creates a GoToE action to an embedded file.
505      * @param filename  the root document of the target (null if the target is in the same document)
506      * @param dest the named destination
507      * @param isName if true sets the destination as a name, if false sets it as a String
508      * @return a GoToE action
509      */
510     public static PdfAction gotoEmbedded(String   filename, PdfTargetDictionary target, String   dest, boolean isName, boolean newWindow) {
511         if (isName)
512             return gotoEmbedded(filename, target, new PdfName(dest), newWindow);
513         else
514             return gotoEmbedded(filename, target, new PdfString(dest, null), newWindow);
515     }
516 
517     /**
518      * Creates a GoToE action to an embedded file.
519      * @param filename  the root document of the target (null if the target is in the same document)
520      * @param target    a path to the target document of this action
521      * @param dest      the destination inside the target document, can be of type PdfDestination, PdfName, or PdfString
522      * @param newWindow if true, the destination document should be opened in a new window
523      * @return a GoToE action
524      */
525     public static PdfAction gotoEmbedded(String   filename, PdfTargetDictionary target, PdfObject dest, boolean newWindow) {
526         PdfAction action = new PdfAction();
527         action.put(PdfName.S, PdfName.GOTOE);
528         action.put(PdfName.T, target);
529         action.put(PdfName.D, dest);
530         action.put(PdfName.NEWWINDOW, new PdfBoolean(newWindow));
531         if (filename != null) {
532             action.put(PdfName.F, new PdfString(filename));
533         }
534         return action;
535     }
536 
537     /**
538      * A set-OCG-state action (PDF 1.5) sets the state of one or more optional content
539      * groups.
540      * @param state an array consisting of any number of sequences beginning with a <CODE>PdfName</CODE>
541      * or <CODE>String</CODE> (ON, OFF, or Toggle) followed by one or more optional content group dictionaries
542      * <CODE>PdfLayer</CODE> or a <CODE>PdfIndirectReference</CODE> to a <CODE>PdfLayer</CODE>.<br>
543      * The array elements are processed from left to right; each name is applied
544      * to the subsequent groups until the next name is encountered:
545      * <ul>
546      * <li>ON sets the state of subsequent groups to ON</li>
547      * <li>OFF sets the state of subsequent groups to OFF</li>
548      * <li>Toggle reverses the state of subsequent groups</li>
549      * </ul>
550      * @param preserveRB if <CODE>true</CODE>, indicates that radio-button state relationships between optional
551      * content groups (as specified by the RBGroups entry in the current configuration
552      * dictionary) should be preserved when the states in the
553      * <CODE>state</CODE> array are applied. That is, if a group is set to ON (either by ON or Toggle) during
554      * processing of the <CODE>state</CODE> array, any other groups belong to the same radio-button
555      * group are turned OFF. If a group is set to OFF, there is no effect on other groups.<br>
556      * If <CODE>false</CODE>, radio-button state relationships, if any, are ignored
557      * @return the action
558      */    
559     public static PdfAction setOCGstate(ArrayList   state, boolean preserveRB) {
560         PdfAction action = new PdfAction();
561         action.put(PdfName.S, PdfName.SETOCGSTATE);
562         PdfArray a = new PdfArray();
563         for (int k = 0; k < state.size(); ++k) {
564             Object   o = state.get(k);
565             if (o == null)
566                 continue;
567             if (o instanceof PdfIndirectReference)
568                 a.add((PdfIndirectReference)o);
569             else if (o instanceof PdfLayer)
570                 a.add(((PdfLayer)o).getRef());
571             else if (o instanceof PdfName)
572                 a.add((PdfName)o);
573             else if (o instanceof String  ) {
574                 PdfName name = null;
575                 String   s = (String  )o;
576                 if (s.equalsIgnoreCase("on"))
577                     name = PdfName.ON;
578                 else if (s.equalsIgnoreCase("off"))
579                     name = PdfName.OFF;
580                 else if (s.equalsIgnoreCase("toggle"))
581                     name = PdfName.TOGGLE;
582                 else
583                     throw new IllegalArgumentException  ("A string '" + s + " was passed in state. Only 'ON', 'OFF' and 'Toggle' are allowed.");
584                 a.add(name);
585             }
586             else
587                 throw new IllegalArgumentException  ("Invalid type was passed in state: " + o.getClass().getName());
588         }
589         action.put(PdfName.STATE, a);
590         if (!preserveRB)
591             action.put(PdfName.PRESERVERB, PdfBoolean.PDFFALSE);
592         return action;
593     }
594 }
595
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags