PDAnnotation


1   /**
2    * Copyright (c) 2003-2005, www.pdfbox.org
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions are met:
7    *
8    * 1. Redistributions of source code must retain the above copyright notice,
9    *    this list of conditions and the following disclaimer.
10   * 2. Redistributions in binary form must reproduce the above copyright notice,
11   *    this list of conditions and the following disclaimer in the documentation
12   *    and/or other materials provided with the distribution.
13   * 3. Neither the name of pdfbox; nor the names of its
14   *    contributors may be used to endorse or promote products derived from this
15   *    software without specific prior written permission.
16   *
17   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20   * DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
21   * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23   * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24   * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27   *
28   * http://www.pdfbox.org
29   *
30   */
31  package org.pdfbox.pdmodel.interactive.annotation;
32  
33  import java.io.IOException  ;
34  
35  import org.pdfbox.cos.COSArray;
36  import org.pdfbox.cos.COSDictionary;
37  import org.pdfbox.cos.COSName;
38  
39  import org.pdfbox.pdmodel.common.COSObjectable;
40  import org.pdfbox.pdmodel.common.PDRectangle;
41  import org.pdfbox.pdmodel.graphics.color.PDGamma;
42  import org.pdfbox.pdmodel.interactive.action.PDActionFactory;
43  import org.pdfbox.pdmodel.interactive.action.PDAdditionalActions;
44  import org.pdfbox.pdmodel.interactive.action.type.PDAction;
45  import org.pdfbox.util.BitFlagHelper;
46  import org.pdfbox.cos.COSBase;
47  
48  /**
49   * This class represents a PDF annotation.
50   *
51   * @author <a HREF="mailto:ben@benlitchfield.com">Ben Litchfield</a>
52   * @version $Revision: 1.14 $
53   */
54  public abstract class PDAnnotation implements COSObjectable
55  {
56      /**
57       * An annotation flag.
58       */
59      public static final int FLAG_INVISIBLE = 1 << 0;
60      /**
61       * An annotation flag.
62       */
63      public static final int FLAG_HIDDEN = 1 << 1;
64      /**
65       * An annotation flag.
66       */
67      public static final int FLAG_PRINTED = 1 << 2;
68      /**
69       * An annotation flag.
70       */
71      public static final int FLAG_NO_ZOOM = 1 << 3;
72      /**
73       * An annotation flag.
74       */
75      public static final int FLAG_NO_ROTATE = 1 << 4;
76      /**
77       * An annotation flag.
78       */
79      public static final int FLAG_NO_VIEW = 1 << 5;
80      /**
81       * An annotation flag.
82       */
83      public static final int FLAG_READ_ONLY = 1 << 6;
84      /**
85       * An annotation flag.
86       */
87      public static final int FLAG_LOCKED = 1 << 7;
88      /**
89       * An annotation flag.
90       */
91      public static final int FLAG_TOGGLE_NO_VIEW = 1 << 8;
92      
93      
94      
95      private COSDictionary dictionary;
96      
97      /**
98       * Create the correct annotation from the base COS object.
99       * 
100      * @param base The COS object that is the annotation.
101      * @return The correctly typed annotation object.
102      * @throws IOException If there is an error while creating the annotation.
103      */
104     public static PDAnnotation createAnnotation( COSBase base ) throws IOException  
105     {
106         PDAnnotation annot = null;
107         if( base instanceof COSDictionary )
108         {
109             COSDictionary annotDic = (COSDictionary)base;
110             String   subtype = annotDic.getNameAsString( COSName.SUBTYPE );
111             if( subtype.equals( PDAnnotationRubberStamp.SUB_TYPE ) )
112             {
113                 annot = new PDAnnotationRubberStamp(annotDic);
114             }
115             else if( subtype.equals( PDAnnotationLink.SUB_TYPE ) )
116             {
117                 annot = new PDAnnotationLink(annotDic);
118             }
119             else if( subtype.equals( PDAnnotationText.SUB_TYPE ) )
120             {
121                 annot = new PDAnnotationText( annotDic);
122             }
123             else if( subtype.equals( PDAnnotationLine.SUB_TYPE ) )
124             {
125                 annot = new PDAnnotationLine( annotDic );
126             }
127             else if( subtype.equals( PDAnnotationSquareCircle.SUB_TYPE_SQUARE ) || 
128                      subtype.equals( PDAnnotationSquareCircle.SUB_TYPE_CIRCLE ) )
129             {
130                 annot = new PDAnnotationSquareCircle( annotDic );
131             }
132             else if( subtype.equals( PDAnnotationLink.SUB_TYPE ) )
133             {
134                 annot = new PDAnnotationLink( annotDic );
135             }
136             else if( subtype.equals( PDAnnotationFileAttachment.SUB_TYPE ) )
137             {
138                 annot = new PDAnnotationFileAttachment( annotDic );
139             }
140             else if( subtype.equals( PDAnnotationTextMarkup.SUB_TYPE_HIGHLIGHT ) || 
141                      subtype.equals( PDAnnotationTextMarkup.SUB_TYPE_UNDERLINE ) || 
142                      subtype.equals( PDAnnotationTextMarkup.SUB_TYPE_SQUIGGLY ) || 
143                      subtype.equals( PDAnnotationTextMarkup.SUB_TYPE_STRIKEOUT ))
144             {
145                 annot = new PDAnnotationTextMarkup( annotDic );
146             }
147             else
148             {
149                 annot = new PDAnnotationUnknown( annotDic );
150             }
151         }
152         else
153         {
154             throw new IOException  ( "Error: Unknown annotation type " + base );
155         }
156         
157         return annot;
158     }
159 
160     /** 
161      * Constructor.
162      */
163     public PDAnnotation()
164     {
165         dictionary = new COSDictionary();
166         dictionary.setItem( COSName.TYPE, COSName.getPDFName( "Annot" ) );
167     }
168 
169     /**
170      * Constructor.
171      *
172      * @param dict The annotations dictionary.
173      */
174     public PDAnnotation( COSDictionary dict )
175     {
176         dictionary = dict;
177     }
178 
179     /**
180      * returns the dictionary.
181      * @return the dictionary
182      */
183     public COSDictionary getDictionary()
184     {
185         return dictionary;
186     }
187 
188     /**
189      * The annotation rectangle, defining the location of the annotation
190      * on the page in default user space units.  This is usually required and should
191      * not return null on valid PDF documents.  But where this is a parent form field
192      * with children, such as radio button collections then the rectangle will be null.
193      *
194      * @return The Rect value of this annotation.
195      */
196     public PDRectangle getRectangle()
197     {
198         COSArray rectArray = (COSArray)dictionary.getDictionaryObject( COSName.getPDFName( "Rect" ) );
199         PDRectangle rectangle = null;
200         if( rectArray != null )
201         {
202             rectangle = new PDRectangle( rectArray );
203         }
204         return rectangle;
205     }
206 
207     /**
208      * This will set the rectangle for this annotation.
209      *
210      * @param rectangle The new rectangle values.
211      */
212     public void setRectangle( PDRectangle rectangle )
213     {
214         dictionary.setItem( COSName.getPDFName( "Rect" ), rectangle.getCOSArray() );
215     }
216 
217    /**
218      * This will get the flags for this field.
219      *
220      * @return flags The set of flags.
221      */
222     public int getAnnotationFlags()
223     {
224         return getDictionary().getInt( "F", 0 );
225     }
226 
227     /**
228      * This will set the flags for this field.
229      *
230      * @param flags The new flags.
231      */
232     public void setAnnotationFlags( int flags )
233     {
234         getDictionary().setInt( "F", flags );
235     }
236 
237     /**
238      * Interface method for COSObjectable.
239      *
240      * @return This object as a standard COS object.
241      */
242     public COSBase getCOSObject()
243     {
244         return getDictionary();
245     }
246 
247     /**
248      * This will get the name of the current appearance stream if any.
249      *
250      * @return The name of the appearance stream.
251      */
252     public String   getAppearanceStream()
253     {
254         String   retval = null;
255         COSName name = (COSName)getDictionary().getDictionaryObject( COSName.getPDFName( "AS" ) );
256         if( name != null )
257         {
258             retval = name.getName();
259         }
260         return retval;
261     }
262 
263     /**
264      * This will set the annotations appearance stream name.
265      *
266      * @param as The name of the appearance stream.
267      */
268     public void setAppearanceStream( String   as )
269     {
270         if( as == null )
271         {
272             getDictionary().removeItem( COSName.getPDFName( "AS" ) );
273         }
274         else
275         {
276             getDictionary().setItem( COSName.getPDFName( "AS" ), COSName.getPDFName( as ) );
277         }
278     }
279 
280     /**
281      * This will get the appearance dictionary associated with this annotation.
282      * This may return null.
283      *
284      * @return This annotations appearance.
285      */
286     public PDAppearanceDictionary getAppearance()
287     {
288         PDAppearanceDictionary ap = null;
289         COSDictionary apDic = (COSDictionary)dictionary.getDictionaryObject( COSName.getPDFName( "AP" ) );
290         if( apDic != null )
291         {
292             ap = new PDAppearanceDictionary( apDic );
293         }
294         return ap;
295     }
296 
297     /**
298      * This will set the appearance associated with this annotation.
299      *
300      * @param appearance The appearance dictionary for this annotation.
301      */
302     public void setAppearance( PDAppearanceDictionary appearance )
303     {
304         COSDictionary ap = null;
305         if( appearance != null )
306         {
307             ap = appearance.getDictionary();
308         }
309         dictionary.setItem( COSName.getPDFName( "AP" ), ap );
310     }
311     
312     /**
313      * Get the invisible flag.
314      * 
315      * @return The invisible flag.
316      */
317     public boolean isInvisible()
318     {
319         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_INVISIBLE );
320     }
321     
322     /**
323      * Set the invisible flag.
324      * 
325      * @param invisible The new invisible flag.
326      */
327     public void setInvisible( boolean invisible )
328     {
329         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_INVISIBLE, invisible );
330     }
331     
332     /**
333      * Get the hidden flag.
334      * 
335      * @return The hidden flag.
336      */
337     public boolean isHidden()
338     {
339         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_HIDDEN );
340     }
341     
342     /**
343      * Set the hidden flag.
344      * 
345      * @param hidden The new hidden flag.
346      */
347     public void setHidden( boolean hidden )
348     {
349         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_HIDDEN, hidden );
350     }
351     
352     /**
353      * Get the printed flag.
354      * 
355      * @return The printed flag.
356      */
357     public boolean isPrinted()
358     {
359         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_PRINTED );
360     }
361     
362     /**
363      * Set the printed flag.
364      * 
365      * @param printed The new printed flag.
366      */
367     public void setPrinted( boolean printed )
368     {
369         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_PRINTED, printed );
370     }
371     
372     /**
373      * Get the noZoom flag.
374      * 
375      * @return The noZoom flag.
376      */
377     public boolean isNoZoom()
378     {
379         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_NO_ZOOM );
380     }
381     
382     /**
383      * Set the noZoom flag.
384      * 
385      * @param noZoom The new noZoom flag.
386      */
387     public void setNoZoom( boolean noZoom )
388     {
389         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_NO_ZOOM, noZoom );
390     }
391     
392     /**
393      * Get the noRotate flag.
394      * 
395      * @return The noRotate flag.
396      */
397     public boolean isNoRotate()
398     {
399         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_NO_ROTATE );
400     }
401     
402     /**
403      * Set the noRotate flag.
404      * 
405      * @param noRotate The new noRotate flag.
406      */
407     public void setNoRotate( boolean noRotate )
408     {
409         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_NO_ROTATE, noRotate );
410     }
411     
412     /**
413      * Get the noView flag.
414      * 
415      * @return The noView flag.
416      */
417     public boolean isNoView()
418     {
419         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_NO_VIEW );
420     }
421     
422     /**
423      * Set the noView flag.
424      * 
425      * @param noView The new noView flag.
426      */
427     public void setNoView( boolean noView )
428     {
429         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_NO_VIEW, noView );
430     }
431     
432     /**
433      * Get the readOnly flag.
434      * 
435      * @return The readOnly flag.
436      */
437     public boolean isReadOnly()
438     {
439         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_READ_ONLY );
440     }
441     
442     /**
443      * Set the readOnly flag.
444      * 
445      * @param readOnly The new readOnly flag.
446      */
447     public void setReadOnly( boolean readOnly )
448     {
449         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_READ_ONLY, readOnly );
450     }
451     
452     /**
453      * Get the locked flag.
454      * 
455      * @return The locked flag.
456      */
457     public boolean isLocked()
458     {
459         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_LOCKED );
460     }
461     
462     /**
463      * Set the locked flag.
464      * 
465      * @param locked The new locked flag.
466      */
467     public void setLocked( boolean locked )
468     {
469         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_LOCKED, locked );
470     }
471     
472     /**
473      * Get the toggleNoView flag.
474      * 
475      * @return The toggleNoView flag.
476      */
477     public boolean isToggleNoView()
478     {
479         return BitFlagHelper.getFlag( getDictionary(), "F", FLAG_TOGGLE_NO_VIEW );
480     }
481     
482     /**
483      * Set the toggleNoView flag.
484      * 
485      * @param toggleNoView The new toggleNoView flag.
486      */
487     public void setToggleNoView( boolean toggleNoView )
488     {
489         BitFlagHelper.setFlag( getDictionary(), "F", FLAG_TOGGLE_NO_VIEW, toggleNoView );
490     }
491     
492     /**
493      * Get the action to be performed when this annotation is to be activated.
494      * 
495      * @return The action to be performed when this annotation is activated.
496      * 
497      * @throws IOException If there is an error creating the action.
498      */
499     public PDAction getAction() throws IOException  
500     {
501         COSDictionary action = (COSDictionary)
502             getDictionary().getDictionaryObject( COSName.A );
503         return PDActionFactory.createAction( action );
504     }
505     
506     /**
507      * Set the annotation action.
508      * As of PDF 1.6 this is only used for Widget Annotations 
509      * @param action The annotation action.
510      */
511     public void setAction( PDAction action )
512     {
513         getDictionary().setItem( COSName.A, action );
514     }
515     
516     /**
517      * Get the additional actions for this field.  This will return null
518      * if there are no additional actions for this field.
519      * As of PDF 1.6 this is only used for Widget Annotations.
520      * 
521      * @return The actions of the field.
522      */
523     public PDAdditionalActions getActions()
524     {
525         COSDictionary aa = (COSDictionary)dictionary.getDictionaryObject( "AA" );
526         PDAdditionalActions retval = null;
527         if( aa != null )
528         {
529             retval = new PDAdditionalActions( aa );
530         }
531         return retval;
532     }
533     
534     /**
535      * Set the actions of the field.
536      * 
537      * @param actions The field actions.
538      */
539     public void setActions( PDAdditionalActions actions )
540     {
541         dictionary.setItem( "AA", actions );
542     }
543     
544     /**
545      * Get the "contents" of the field.
546      * 
547      * @return the value of the contents.
548      */
549     public String   getContents()
550     {
551         return dictionary.getString(COSName.CONTENTS);
552     }
553     
554     /**
555      * Set the "contents" of the field.
556      * 
557      * @param value the value of the contents.
558      */
559     public void setContents( String   value)
560     {
561         dictionary.setString(COSName.CONTENTS, value);
562     }
563     
564     /**
565      * This will set the border style dictionary, specifying the width and dash
566      * pattern used in drawing the line.
567      * 
568      * @param bs the border style dictionary to set.
569      * 
570      */
571     public void setBorderStyle( PDBorderStyleDictionary bs )
572     {
573         getDictionary().setItem( "BS", bs);
574     }
575 
576     /**
577      * This will retrieve the border style dictionary, specifying the width and
578      * dash pattern used in drawing the line.
579      * 
580      * @return the border style dictionary.
581      */
582     public PDBorderStyleDictionary getBoderStyle()
583     {
584         COSDictionary bs = (COSDictionary) getDictionary().getItem(
585                 COSName.getPDFName( "BS" ) );
586         if (bs != null)
587         {
588             return new PDBorderStyleDictionary( bs );
589         } 
590         else
591         {
592             return null;
593         }
594     }
595 
596     /**
597      * This will retrieve the date and time the annotation was modified.
598      * 
599      * @return the modified date/time (often in date format, but can be an arbitary string).
600      */
601     public String   getModifiedDate() 
602     {
603         return getDictionary().getString( "M" );
604     }
605 
606     /**
607      * This will set the the date and time the annotation was modified.
608      * 
609      * @param m
610      *            the date and time the annotation was created.
611      */
612     public void setModifiedDate( String   m )
613     {
614         getDictionary().setString( "M", m );
615     }
616 
617     /**
618      * This will get the name, a string intended to uniquely identify each annotatoin
619      * within a page. Not to be confused with some annotations Name entry which 
620      * impact the default image drawn for them.
621      * 
622      * @return The identifying name for the Annotion.
623      */
624     public String   getAnnotationName() 
625     {
626         return getDictionary().getString( "NM" );
627     }
628 
629     /**
630      * This will set the name, a string intended to uniquely identify each annotatoin
631      * within a page. Not to be confused with some annotations Name entry which 
632      * impact the default image drawn for them.
633      *
634      * @param nm The identifying name for the annotation.
635      */
636     public void setAnnotationName( String   nm )
637     {
638         getDictionary().setString( "NM", nm );
639     }
640     
641     /**
642      * This will set the colour used in drawing various elements.
643      * As of PDF 1.6 these are : Background of icon when closed
644      *                           Title bar of popup window
645      *                           Border of a link annotation
646      *          
647      * Colour is in DeviceRGB colourspace
648      * 
649      * @param c
650      *            colour in the DeviceRGB colourspace
651      * 
652      */
653     public void setColour( PDGamma c )
654     {
655         getDictionary().setItem( "C", c );
656     }
657 
658     /**
659      * This will retrieve the colour used in drawing various elements.
660      * As of PDF 1.6 these are : Background of icon when closed
661      *                           Title bar of popup window
662      *                           Border of a link annotation
663      *          
664      * Colour is in DeviceRGB colourspace
665      * 
666      * @return PDGamma object representing the colour
667      * 
668      */
669     public PDGamma getColour()
670     {
671         COSArray c = (COSArray) getDictionary().getItem(COSName.getPDFName( "C" ) );
672         if (c != null)
673         {
674             return new PDGamma( c );
675         } 
676         else
677         {
678             return null;
679         }
680     }
681 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags