1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.pdfbox.pdmodel.interactive.annotation;
18
19 import java.io.IOException;
20
21 import org.apache.pdfbox.cos.COSBase;
22 import org.apache.pdfbox.cos.COSDictionary;
23 import org.apache.pdfbox.cos.COSName;
24 import org.apache.pdfbox.pdmodel.interactive.action.PDActionFactory;
25 import org.apache.pdfbox.pdmodel.interactive.action.PDAnnotationAdditionalActions;
26 import org.apache.pdfbox.pdmodel.interactive.action.type.PDAction;
27
28 /**
29 * This is the class that represents a widget.
30 *
31 * @author <a href="mailto:ben@benlitchfield.com">Ben Litchfield</a>
32 * @version $Revision: 1.3 $
33 */
34 public class PDAnnotationWidget extends PDAnnotation
35 {
36 /**
37 * The type of annotation.
38 */
39 public static final String SUB_TYPE = "Widget";
40
41
42 /**
43 * Constructor.
44 */
45 public PDAnnotationWidget()
46 {
47 super();
48 getDictionary().setName( COSName.SUBTYPE, SUB_TYPE);
49 }
50
51
52 /**
53 * Creates a PDWidget from a COSDictionary, expected to be
54 * a correct object definition for a field in PDF.
55 *
56 * @param field the PDF objet to represent as a field.
57 */
58 public PDAnnotationWidget(COSDictionary field)
59 {
60 super( field );
61 }
62
63 /**
64 * Returns the highlighting mode. Default value: <code>I</code>
65 * <dl>
66 * <dt><code>N</code></dt>
67 * <dd>(None) No highlighting.</dd>
68 * <dt><code>I</code></dt>
69 * <dd>(Invert) Invert the contents of the annotation rectangle.</dd>
70 * <dt><code>O</code></dt>
71 * <dd>(Outline) Invert the annotation's border.</dd>
72 * <dt><code>P</code></dt>
73 * <dd>(Push) Display the annotation's down appearance, if any. If no
74 * down appearance is defined, the contents of the annotation rectangle
75 * shall be offset to appear as if it were pushed below the surface of
76 * the page</dd>
77 * <dt><code>T</code></dt>
78 * <dd>(Toggle) Same as <code>P</code> (which is preferred).</dd>
79 * </dl>
80 *
81 * @return the highlighting mode
82 */
83 public String getHighlightingMode()
84 {
85 return this.getDictionary().getNameAsString(COSName.H, "I");
86 }
87
88 /**
89 * Sets the highlighting mode.
90 * <dl>
91 * <dt><code>N</code></dt>
92 * <dd>(None) No highlighting.</dd>
93 * <dt><code>I</code></dt>
94 * <dd>(Invert) Invert the contents of the annotation rectangle.</dd>
95 * <dt><code>O</code></dt>
96 * <dd>(Outline) Invert the annotation's border.</dd>
97 * <dt><code>P</code></dt>
98 * <dd>(Push) Display the annotation's down appearance, if any. If no
99 * down appearance is defined, the contents of the annotation rectangle
100 * shall be offset to appear as if it were pushed below the surface of
101 * the page</dd>
102 * <dt><code>T</code></dt>
103 * <dd>(Toggle) Same as <code>P</code> (which is preferred).</dd>
104 * </dl>
105 *
106 * @param highlightingMode the highlighting mode
107 * the defined values
108 */
109 public void setHighlightingMode(String highlightingMode)
110 {
111 if ((highlightingMode == null)
112 || "N".equals(highlightingMode) || "I".equals(highlightingMode)
113 || "O".equals(highlightingMode) || "P".equals(highlightingMode)
114 || "T".equals(highlightingMode))
115 {
116 this.getDictionary().setName(COSName.H, highlightingMode);
117 }
118 else
119 {
120 throw new IllegalArgumentException( "Valid values for highlighting mode are " +
121 "'N', 'N', 'O', 'P' or 'T'" );
122 }
123 }
124
125 /**
126 * Returns the appearance characteristics dictionary.
127 *
128 * @return the appearance characteristics dictionary
129 */
130 public PDAppearanceCharacteristicsDictionary getAppearanceCharacteristics()
131 {
132 COSBase mk = this.getDictionary().getDictionaryObject(COSName.getPDFName("MK"));
133 if (mk instanceof COSDictionary)
134 {
135 return new PDAppearanceCharacteristicsDictionary((COSDictionary) mk);
136 }
137 return null;
138 }
139
140 /**
141 * Sets the appearance characteristics dictionary.
142 *
143 * @param appearanceCharacteristics the appearance characteristics dictionary
144 */
145 public void setAppearanceCharacteristics(PDAppearanceCharacteristicsDictionary appearanceCharacteristics)
146 {
147 this.getDictionary().setItem("MK", appearanceCharacteristics);
148 }
149
150 /**
151 * Get the action to be performed when this annotation is to be activated.
152 *
153 * @return The action to be performed when this annotation is activated.
154 *
155 * @throws IOException If there is an error creating the action.
156 */
157 public PDAction getAction() throws IOException
158 {
159 COSDictionary action = (COSDictionary)
160 this.getDictionary().getDictionaryObject( COSName.A );
161 return PDActionFactory.createAction( action );
162 }
163
164 /**
165 * Set the annotation action.
166 * As of PDF 1.6 this is only used for Widget Annotations
167 * @param action The annotation action.
168 */
169 public void setAction( PDAction action )
170 {
171 this.getDictionary().setItem( COSName.A, action );
172 }
173
174 /**
175 * Get the additional actions for this field. This will return null
176 * if there are no additional actions for this field.
177 * As of PDF 1.6 this is only used for Widget Annotations.
178 *
179 * @return The actions of the field.
180 */
181 public PDAnnotationAdditionalActions getActions()
182 {
183 COSDictionary aa = (COSDictionary)this.getDictionary().getDictionaryObject( "AA" );
184 PDAnnotationAdditionalActions retval = null;
185 if( aa != null )
186 {
187 retval = new PDAnnotationAdditionalActions( aa );
188 }
189 return retval;
190 }
191
192 /**
193 * Set the actions of the field.
194 *
195 * @param actions The field actions.
196 */
197 public void setActions( PDAnnotationAdditionalActions actions )
198 {
199 this.getDictionary().setItem( "AA", actions );
200 }
201
202 /**
203 * This will set the border style dictionary, specifying the width and dash
204 * pattern used in drawing the line.
205 *
206 * @param bs the border style dictionary to set.
207 *
208 */
209 public void setBorderStyle( PDBorderStyleDictionary bs )
210 {
211 this.getDictionary().setItem( "BS", bs);
212 }
213
214 /**
215 * This will retrieve the border style dictionary, specifying the width and
216 * dash pattern used in drawing the line.
217 *
218 * @return the border style dictionary.
219 */
220 public PDBorderStyleDictionary getBorderStyle()
221 {
222 COSDictionary bs = (COSDictionary) this.getDictionary().getItem(
223 COSName.getPDFName( "BS" ) );
224 if (bs != null)
225 {
226 return new PDBorderStyleDictionary( bs );
227 }
228 else
229 {
230 return null;
231 }
232 }
233
234 // TODO where to get acroForm from?
235 // public PDField getParent() throws IOException
236 // {
237 // COSBase parent = this.getDictionary().getDictionaryObject(COSName.PARENT);
238 // if (parent instanceof COSDictionary)
239 // {
240 // PDAcroForm acroForm = null;
241 // return PDFieldFactory.createField(acroForm, (COSDictionary) parent);
242 // }
243 // return null;
244 // }
245 }