PDFAnnotation


1   // $Id: PDFAnnotation.java,v 1.4 2003/11/04 17:16:01 mike Exp $
2   
3   package org.faceless.pdf;
4   
5   import java.util.*;
6   import java.awt.Color  ;
7   
8   /**
9    * <p>
10   * A PDFAnnotation allows the user to interact with the generated
11   * PDF document, by adding / viewing rubber-stamps and popup notes
12   * or following hyperlinks. A special class of annotation, called a
13   * "Widget", is also used to display {@link Form} Fields on the page.
14   * </p>
15   * @version $Revision: 1.4 $
16   * @since 1.1
17   */
18  public class PDFAnnotation extends PeeredObject
19  {
20      final org.faceless.pdf2.PDFAnnotation annot;
21  
22      Object   getPeer()
23      {
24          return annot;
25      }
26  
27      /**
28       * Value for {@link #setEventAction} representing the event that occurs
29       * when the annotation is clicked.
30       * @since 1.1.23
31       */
32      public static final int EVENT_ONCLICK   =-1;
33  
34      /**
35       * Value for {@link #setEventAction} representing the event that occurs
36       * when the mouse pointer is moved over the annotation rectangle
37       * @since 1.1.23
38       */
39      public static final int EVENT_ONMOUSEOVER   =0;
40  
41      /**
42       * Value for {@link #setEventAction} representing the event that occurs
43       * when the mouse pointer is moved out of the annotation rectangle
44       * @since 1.1.23
45       */
46      public static final int EVENT_ONMOUSEOUT    =1;
47  
48      /**
49       * Value for {@link #setEventAction} representing the event that occurs
50       * when the mouse button is pressed over the annotation
51       * @since 1.1.23
52       */
53      public static final int EVENT_ONMOUSEDOWN   =2;
54  
55      /**
56       * Value for {@link #setEventAction} representing the event that occurs
57       * when the mouse button is released over the annotation.
58       * @since 1.1.23
59       */
60      public static final int EVENT_ONMOUSEUP =3;
61  
62      /**
63       * Value for {@link #setEventAction} representing the event that occurs
64       * when the annotation gains focus.
65       * Does not apply to buttons.
66       * @since 1.1.23
67       */
68      public static final int EVENT_ONFOCUS   =4;
69  
70      /**
71       * Value for {@link #setEventAction} representing the event that occurs
72       * when the annotation loses focus.
73       * Does not apply to buttons.
74       * @since 1.1.23
75       */
76      public static final int EVENT_ONBLUR    =5;
77  
78      /**
79       * Value for {@link #setEventAction} representing the event that occurs
80       * when the annotation value changes.
81       * Does not apply to buttons.
82       * @since 1.1.23
83       */
84      public static final int EVENT_ONCHANGE  =6;
85  
86      /**
87       * Value for {@link #setEventAction} representing the event that occurs
88       * when a key is pressed and the annotation has focus.
89       * Only applies to text boxes.
90       * @since 1.1.23
91       */
92      public static final int EVENT_ONKEYPRESS    =7;
93  
94      /**
95       * Value for {@link #setEventAction} representing the event that occurs
96       * when a the contents of the annotation is being formatted for display.
97       * Only applies to text boxes.
98       * @since 1.1.23
99       */
100     public static final int EVENT_ONFORMAT  =8;
101 
102     /**
103      * Value for {@link #setEventAction} representing the event that occurs
104      * when <i>another</i> annotation changes - which makes this event a
105      * little bit different to the others. You may set a JavaScript action
106      * on this event which can recalculate the value of this field based on
107      * the value of other fields (for example). Only applies to text boxes
108      * @since 1.1.23
109      */
110     public static final int EVENT_ONOTHERCHANGE =9;
111 
112 
113     /**
114      * A style of text annotation whose icon represents a "note" (the default).
115      * The PDF spec doesn't define this any further. 
116      */
117     public static final int TEXT_NOTE = 0;
118 
119     /**
120      * A style of text annotation whose icon represents "comment"
121      * The PDF spec doesn't define this any further.
122      */
123     public static final int TEXT_COMMENT = 1;
124 
125     /**
126      * A style of text annotation whose icon represents "help". The PDF
127      * spec doesn't define this any further.
128      */
129     public static final int TEXT_HELP = 2;
130 
131     /**
132      * A style of text annotation whose icon represents "insert". The PDF
133      * spec doesn't define this any further.
134      */
135     public static final int TEXT_INSERT = 3;
136 
137     /**
138      * A style of text annotation whose icon represents "key". The PDF
139      * spec doesn't define this any further.
140      */
141     public static final int TEXT_KEY = 4;
142 
143     /**
144      * A style of text annotation whose icon represents "new paragraph".
145      * The PDF spec doesn't define this any further.
146      */
147     public static final int TEXT_NEWPARAGRAPH = 5;
148 
149     /**
150      * A style of text annotation whose icon represents "paragraph".
151      * The PDF spec doesn't define this any further.
152      */
153     public static final int TEXT_PARAGRAPH = 6;
154 
155     PDFAnnotation(org.faceless.pdf2.PDFAnnotation annot)
156     {
157     this.annot=annot;
158     }
159 
160     /**
161      * <p>
162      * Return a new PDFAnnotation that performs the specified action
163      * when clicked. This can be used to create an HTML-style hyperlink,
164      * play a sound, or perform some other {@link PDFAction}. Although this
165      * method can be called directly to mark a portion of the page as a
166      * hyperlink, for text hyperlinks the {@link PDFPage#beginTextLink}
167      * method is probably more convenient.
168      * </p><p>
169      * Remember to set the co-ordinates of the annotation using the
170      * <code>setRectangle</code> method.
171      * </p>
172      * 
173      * @param action the {@link PDFAction} to perform when the link is clicked
174      * @param border whether to display a border around the link area
175      */
176     public static PDFAnnotation link(PDFAction action, boolean border)
177     {
178     org.faceless.pdf2.AnnotationLink link = new org.faceless.pdf2.AnnotationLink();
179     link.setAction(action.action);
180     if (border) {
181         org.faceless.pdf2.PDFStyle style = new org.faceless.pdf2.PDFStyle();
182         link.setStyle(style);
183     }
184     return new PDFAnnotation(link);
185     }
186 
187     /**
188      * Return a new PDFAnnotation that holds a text message. When the user clicks
189      * on the annotation, a window pops up and displays the contents.
190      * @param label the label to give of the popup window
191      * @param contents The text to display in the window. May contain newline
192      * characters for formatting.
193      * @param open whether the window is open by default
194      * @param type The visual appearance of the annotation when closed. May be
195      * {@link #TEXT_NOTE}, {@link #TEXT_COMMENT}, {@link #TEXT_HELP},
196      * {@link #TEXT_INSERT}, {@link #TEXT_KEY}, {@link #TEXT_NEWPARAGRAPH} or
197      * {@link #TEXT_PARAGRAPH}
198      */
199     public static PDFAnnotation text(String   label, String   contents, boolean open, int type)
200     {
201     org.faceless.pdf2.AnnotationNote note = new org.faceless.pdf2.AnnotationNote();
202 
203     String   newtype;
204     if (type==TEXT_COMMENT) newtype = "Comment";
205     else if (type==TEXT_HELP) newtype = "Help";
206     else if (type==TEXT_INSERT) newtype = "Insert";
207     else if (type==TEXT_KEY) newtype = "Key";
208     else if (type==TEXT_NEWPARAGRAPH) newtype = "New Paragraph";
209     else if (type==TEXT_PARAGRAPH) newtype = "Paragraph";
210     else newtype = "Note";
211 
212     if (newtype!=null) {
213         note.setType(newtype, Color.yellow);
214     }
215     note.setOpen(open);
216     note.setAuthor(label);
217     note.setContents(contents);
218 
219     return new PDFAnnotation(note);
220     }
221 
222     /**
223      * Create a rubber-stamp annotation which can be added to the page.
224      * Fourteen different rubber stamps are available - the parameter "type"
225      * must be one of <code>Approved</code>, <code>AsIs</code>,
226      * <code>Confidential</code>, <code>Departmental</code>, <code>Draft</code>,
227      * <code>Experimental</code>, <code>Expired</code>, <code>Final</code>,
228      * <code>ForComment</code>, <code>ForPublicRelease</code>,
229      * <code>NotApproved</code>, <code>NotForPublicRelease</code>, <code>Sold</code>
230      * or <code>TopSecret</code>. Any other value will result in an
231      * <code>IllegalArgumengException</code> being thrown.
232      * @param type the type of stamp - one of the values listed above
233      * @throws IllegalArgumentException if the stamp type is unknown
234      * @since 1.1.23
235      */
236     public static PDFAnnotation stamp(String   type)
237         throws IllegalArgumentException  
238     {
239     org.faceless.pdf2.AnnotationStamp stamp = new org.faceless.pdf2.AnnotationStamp("stamp.stencil."+type, 1);
240     return new PDFAnnotation(stamp);
241     }
242 
243     /**
244      * Set the rectangle for the annotation.
245      * <ul>
246      * <li>For <b>link</b> annotations, this is the rectangle that must be clicked
247      * in to activate the action.</li>
248      * <li>For <b>text</b> annotations, this is the rectangle describing the popup
249      * window when it's opened. When it's closed, the icon is positioned at <i>x1,y1</i>.
250      * </li>
251      * </ul>
252      * <p>
253      * Note that all co-ordinates are in <b>absolute page co-ordinates</b>.
254      * This means they are measured in points from the bottom-left hand
255      * corner of the page, regardless of any calls to <code>rotate</code>,
256      * <code>translate</code>, <code>scale</code> or <code>setCanvas</code>
257      * that have been made. This restriction is part of the PDF specification.
258      * </p>
259      * @param x1 the X co-ordinate of the bottom-left corner of the rectangle
260      * @param y1 the Y co-ordinate of the bottom-left corner of the rectangle
261      * @param x2 the X co-ordinate of the top-right corner of the rectangle
262      * @param y2 the Y co-ordinate of the top-right corner of the rectangle
263      */
264     public void setRectangle(float x1, float y1, float x2, float y2)
265     {
266     annot.setRectangle(x1,y1,x2,y2);
267     }
268 
269     /**
270      * Return the rectangle this annotation applies to on the page, or <tt>null</tt>
271      * if no rectangle applies for this type of annotation.
272      * @return the rectangle for this annotation, in the form of an array (<i>x1</i>, <i>y1</i>, <i>x2</i>, <i>y2</i>)
273      * @since 1.1.12
274      */
275     public float[] getRectangle()
276     {
277     return annot.getRectangle();
278     }
279 
280     /**
281      * Get the type of annotation. Can be either "Link", "Text" or "Stamp:<i>type</i>"
282      * (where <i>type</i> is the type of stamp, eg "Draft"), all of
283      * which are supported by the PDF library, or one of various other annotation types
284      * supported by the PDF specification but not this library.
285      * @return the type of annotation
286      * @since 1.1.12
287      */
288     public String   getType()
289     {
290     return annot.getType();
291     }
292 
293     /**
294      * Return the page that this annotation is on, or <code>null</code>
295      * if it a new annotation which has not yet been placed on a page
296      * @since 1.1.23
297      */
298     public PDFPage getPage()
299     {
300         return (PDFPage)PeeredObject.getPeer(annot.getPage());
301     }
302 
303     /**
304      * Set the page for this annotation. This is useful when
305      * moving annotations between documents or across pages - when
306      * simply adding a new annotation to a page, this method is
307      * identical to calling {@link PDFPage#addAnnotation}
308      * @since 1.1.23
309      */
310     public void setPage(PDFPage page)
311     {
312     annot.setPage(page.page);
313     }
314 
315     /**
316      * Set whether the annotation is visible on screen. By default, all new
317      * annotations are visible
318      * @param screen whether the annotation should be displayed on the screen
319      * @param print whether the annotation should be printed
320      * @since 1.1.23
321      */
322     public void setVisible(boolean visible)
323     {
324     annot.setVisible(visible);
325     }
326 
327     /**
328      * Set whether the annotation is included when the document is printed. By
329      * default, all new annotations are printed.
330      * @param screen whether the annotation should be displayed on the screen
331      * @param print whether the annotation should be printed
332      * @since 1.1.23
333      */
334     public void setPrintable(boolean printable)
335     {
336     annot.setPrintable(printable);
337     }
338 
339     /**
340      * Returns whether the annotation is visible on the
341      * screen (true) or not (false)
342      * @since 1.1.23
343      */
344     public boolean isVisible()
345     {
346     return annot.isVisible();
347     }
348 
349     /**
350      * Returns whether the annotation is included when the document
351      * is printed (true) or not (false)
352      * @since 1.1.23
353      */
354     public boolean isPrintable()
355     {
356     return annot.isPrintable();
357     }
358 
359     /**
360      * Set the color of the annotation.
361      * <ul>
362      * <li>For <b>link</b> annotations, this is the color of the border around the
363      * annotation (assuming the border is on)</li>
364      * <li>For <b>text</b> annotations, this is color of the icon and highlights on
365      * the popup window</li>
366      * </ul>
367      */
368     public void setColor(Color   c)
369     {
370     if (annot instanceof org.faceless.pdf2.AnnotationLink) {
371         if (c==null) {
372         ((org.faceless.pdf2.AnnotationLink)annot).setStyle(null);
373         } else {
374         org.faceless.pdf2.PDFStyle style = new org.faceless.pdf2.PDFStyle();
375         style.setLineColor(c);
376         ((org.faceless.pdf2.AnnotationLink)annot).setStyle(style);
377         }
378     } else if (annot instanceof org.faceless.pdf2.AnnotationNote) {
379         ((org.faceless.pdf2.AnnotationNote)annot).setType(((org.faceless.pdf2.AnnotationNote)annot).getType(), c);
380     }
381     }
382 
383     /**
384      * For a link annotation, set the action that the annotation refers to.
385      * If this method is invoked on a non-link annotation it has no effect.
386      * Since 1.1.23, passing in a null action removes the action completely.
387      */
388     public void setAction(PDFAction action)
389     {
390     if (annot instanceof org.faceless.pdf2.AnnotationLink) {
391         ((org.faceless.pdf2.AnnotationLink)annot).setAction(action==null ? null : action.action);
392     }
393     }
394 
395     /**
396      * For a link annotation, get the action that the annotation refers to.
397      * If this method is invoked on a non-link annotation, null is returned.
398      */
399     public PDFAction getAction()
400     {
401     if (annot instanceof org.faceless.pdf2.AnnotationLink) {
402         return (PDFAction)PeeredObject.getPeer(((org.faceless.pdf2.AnnotationLink)annot).getAction());
403     } else if (annot instanceof org.faceless.pdf2.WidgetAnnotation) {
404         return (PDFAction)PeeredObject.getPeer(((org.faceless.pdf2.WidgetAnnotation)annot).getAction(org.faceless.pdf2.Event.CLICK));
405     } else {
406         return null;
407     }
408     }
409 
410     /**
411      * For a text or stamp annotation, set the contents of the annotation.
412      * The string may contain newlines.
413      * @since 1.1.12
414      */
415     public void setTextAnnotationContents(String   contents)
416     {
417     if (annot instanceof org.faceless.pdf2.AnnotationNote) {
418         ((org.faceless.pdf2.AnnotationNote)annot).setContents(contents);
419     } else if (annot instanceof org.faceless.pdf2.AnnotationStamp) {
420         ((org.faceless.pdf2.AnnotationStamp)annot).setContents(contents);
421     }
422     }
423 
424     /**
425      * For a text or stamp annotation, get the contents of the annotation.
426      * For other types of annotation, this returns <code>null</code>
427      * @return the content of the text annotation or <tt>null</tt>
428      * @since 1.1.12
429      */
430     public String   getTextAnnotationContents()
431     {
432     if (annot instanceof org.faceless.pdf2.AnnotationNote) {
433         return ((org.faceless.pdf2.AnnotationNote)annot).getContents();
434     } else if (annot instanceof org.faceless.pdf2.AnnotationStamp) {
435         return ((org.faceless.pdf2.AnnotationStamp)annot).getContents();
436     } else {
437         return null;
438     }
439     }
440 
441     /**
442      * For a text annotation, set the label of the annotation. This
443      * is also used in Acrobat to represent the "author" of an
444      * annotation, and as such may be used on any type of annotation.
445      * The specified value may contain non-ASCII Unicode characters
446      * @since 1.1.12
447      */
448     public void setTextAnnotationLabel(String   label)
449     {
450     if (annot instanceof org.faceless.pdf2.AnnotationNote) {
451         ((org.faceless.pdf2.AnnotationNote)annot).setAuthor(label);
452     }
453     }
454 
455     /**
456      * For a text annotation, get the label of the annotation. This
457      * is also used in Acrobat to represent the "author" of an
458      * annotation, and as such may be used on any type of annotation.
459      * @return the label/author of the annotation or <tt>null</tt>
460      * @since 1.1.12
461      */
462     public String   getTextAnnotationLabel()
463     {
464     if (annot instanceof org.faceless.pdf2.AnnotationNote) {
465         return ((org.faceless.pdf2.AnnotationNote)annot).getAuthor();
466     } else {
467         return null;
468     }
469     }
470 
471     /**
472      * Return the date when the annotation was last modified if
473      * specified, or <code>null</code> otherwise.
474      * @since 1.1.23
475      */
476     public Calendar getLastModified()
477     {
478         return annot.getModifyDate();
479     }
480 
481     /**
482      * <p>
483      * Set an action to occur when the specified event happens to
484      * this annotation. These event actions are only used for annotations
485      * created by form elements - those returned from {@link FormElement#getAnnotations}.
486      * </p><p>
487      * The event can be one of {@link #EVENT_ONCLICK},
488      * {@link #EVENT_ONMOUSEOVER}, {@link #EVENT_ONMOUSEOUT},
489      * {@link #EVENT_ONMOUSEDOWN}, {@link #EVENT_ONMOUSEUP},
490      * {@link #EVENT_ONFOCUS}, {@link #EVENT_ONBLUR}, {@link #EVENT_ONCHANGE},
491      * {@link #EVENT_ONKEYPRESS} or {@link #EVENT_ONFORMAT} - although not
492      * every event type is applicable for every type of form element.
493      * </p>
494      * @param event the event the action applies to
495      * @param action the action you wish to occur, or <code>null</code> to remove the action
496      * @since 1.1.23
497      * @see FormElement
498      */
499     public void setEventAction(int event, PDFAction action)
500     {
501     org.faceless.pdf2.Event newevent=null;
502     if (annot instanceof org.faceless.pdf2.WidgetAnnotation) {
503         if (event==EVENT_ONCLICK) newevent=org.faceless.pdf2.Event.CLICK;
504         else if (event==EVENT_ONMOUSEOVER) newevent=org.faceless.pdf2.Event.MOUSEOVER;
505         else if (event==EVENT_ONMOUSEOUT) newevent=org.faceless.pdf2.Event.MOUSEOUT;
506         else if (event==EVENT_ONMOUSEDOWN) newevent=org.faceless.pdf2.Event.MOUSEDOWN;
507         else if (event==EVENT_ONMOUSEUP) newevent=org.faceless.pdf2.Event.MOUSEUP;
508         else if (event==EVENT_ONBLUR) newevent=org.faceless.pdf2.Event.BLUR;
509         else if (event==EVENT_ONFOCUS) newevent=org.faceless.pdf2.Event.FOCUS;
510         else if (event==EVENT_ONCHANGE) newevent=org.faceless.pdf2.Event.CHANGE;
511         else if (event==EVENT_ONFORMAT) newevent=org.faceless.pdf2.Event.FORMAT;
512         else if (event==EVENT_ONKEYPRESS) newevent=org.faceless.pdf2.Event.KEYPRESS;
513         else if (event==EVENT_ONOTHERCHANGE) newevent=org.faceless.pdf2.Event.OTHERCHANGE;
514         if (newevent!=null) {
515         if (event==EVENT_ONKEYPRESS || event==EVENT_ONFORMAT || event==EVENT_ONCHANGE || event==EVENT_ONOTHERCHANGE) {
516             ((org.faceless.pdf2.WidgetAnnotation)annot).getField().setAction(newevent, action==null ? null : action.action);
517         } else {
518             ((org.faceless.pdf2.WidgetAnnotation)annot).setAction(newevent, action==null ? null : action.action);
519         }
520         }
521     }
522     }
523 
524     /**
525      * Return the action that occurs when the specified event happens to
526      * this annotation. This is only used with annotations returned from
527      * form fields via the {@link FormElement#getAnnotations} method.
528      * @param the event you want the action for - one of the events listed in {@link #setEventAction}
529      * @return the action for that event, or <code>null</code> if no action is specified
530      * @since 1.1.23
531      * @see FormElement
532      */
533     public PDFAction getEventAction(int event)
534     {
535     if (annot instanceof org.faceless.pdf2.WidgetAnnotation) {
536         org.faceless.pdf2.Event newevent=null;
537         if (event==EVENT_ONCLICK) newevent=org.faceless.pdf2.Event.CLICK;
538         else if (event==EVENT_ONMOUSEOVER) newevent=org.faceless.pdf2.Event.MOUSEOVER;
539         else if (event==EVENT_ONMOUSEOUT) newevent=org.faceless.pdf2.Event.MOUSEOUT;
540         else if (event==EVENT_ONMOUSEDOWN) newevent=org.faceless.pdf2.Event.MOUSEDOWN;
541         else if (event==EVENT_ONMOUSEUP) newevent=org.faceless.pdf2.Event.MOUSEUP;
542         else if (event==EVENT_ONBLUR) newevent=org.faceless.pdf2.Event.BLUR;
543         else if (event==EVENT_ONFOCUS) newevent=org.faceless.pdf2.Event.FOCUS;
544         else if (event==EVENT_ONCHANGE) newevent=org.faceless.pdf2.Event.CHANGE;
545         else if (event==EVENT_ONFORMAT) newevent=org.faceless.pdf2.Event.FORMAT;
546         else if (event==EVENT_ONKEYPRESS) newevent=org.faceless.pdf2.Event.KEYPRESS;
547         else if (event==EVENT_ONOTHERCHANGE) newevent=org.faceless.pdf2.Event.OTHERCHANGE;
548         if (newevent!=null) {
549         if (event==EVENT_ONKEYPRESS || event==EVENT_ONFORMAT || event==EVENT_ONCHANGE || event==EVENT_ONOTHERCHANGE) {
550             return (PDFAction)PeeredObject.getPeer(((org.faceless.pdf2.WidgetAnnotation)annot).getField().getAction(newevent));
551         } else {
552             return (PDFAction)PeeredObject.getPeer(((org.faceless.pdf2.WidgetAnnotation)annot).getAction(newevent));
553         }
554         } else {
555         return null;
556         }
557     } else {
558         return null;
559     }
560     }
561 
562     public String   toString()
563     {
564         String   out = "<annotation type=\""+getType()+"\" rect=\"";
565     float[] f = getRectangle();
566     out+=f[0]+","+f[1]+","+f[2]+","+f[3]+"\"";
567     if (getType().equals("Text")) {
568         out+=" label=\""+getTextAnnotationLabel()+"\" content=\""+getTextAnnotationContents()+"\"";
569     } else if (getType().equals("Widget")) {
570         String   n = ((org.faceless.pdf2.WidgetAnnotation)annot).getValue();
571         if (n!=null) {
572             out+=" value=\""+n+"\"";
573         }
574     }
575     if (!isVisible()) out+=" visible=\"false\"";
576     if (!isPrintable()) out+=" printable=\"false\"";
577     if (getAction()!=null) {
578         out+=" action=\""+getAction()+"\"";
579     }
580     String  [] triggers = { "E","X","D","U","Fo","Bl","V","K","F","C" };
581     for (int i=0;i<triggers.length;i++) {
582         final String  [] names = { "onMouseOver", "onMouseOut", "onMouseDown", "onMouseUp", "onFocus", "onBlur", "onChange", "onKeyPress", "onFormat", "onOtherChange" };
583         PDFAction a = getEventAction(i);
584         if (a!=null) {
585            out+=" "+names[i]+"=\""+a+"\"";
586         }
587     }
588     return out+"/>";
589     }
590 
591 }
592
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags