1PDF::Builder::AnnotatioUns(e3r)Contributed Perl DocumentPaDtFi:o:nBuilder::Annotation(3)
2
6 PDF::Builder::Annotation - Add annotations to a PDF
7
9 Note that the handling of annotations can vary from Reader to Reader.
10 The available icon set may be larger or smaller than given here, and
11 some Readers activate an annotation on a single mouse click, while
12 others require a double click. Not all features provided here may be
13 available on all PDF Readers.
14 $annotation = PDF::Builder::Annotation->new()
16 Returns an annotation object (called from $page->annotation()).
17 It is normally not necessary to explicitly call this method (see
19 examples).
20 Annotation types
22 $annotation->link($page, %options)
23 $annotation->link($page)
24 Defines the annotation as a launch-page with page $page (within
25 this document) and options %options (-rect, -border, -color, fit:
26 see descriptions below).
27 Note that $page is not a simple page number, but is a page
29 structure such as "$pdf->openpage(page_number)".
30 $annotation->pdf_file($pdffile, $page_number, %options)
32 Defines the annotation as a PDF-file with filepath $pdffile, on
33 page $page_number, and options %options (-rect, -border, -color,
34 fit: see descriptions below). This differs from the "link" call in
35 that the target is found in a different PDF file, not the current
36 document.
37 $page_number is the physical page number, starting at 1: 1, 2,...
39 $annotation->file($file, %options)
41 Defines the annotation as a launch-file with filepath $file (a
42 local file) and options %options (-rect, -border, -color: see
43 descriptions below). How the file is displayed depends on the
44 operating system, type of file, and local configuration or mapping.
45 $annotation->url($url, %options)
47 Defines the annotation as a launch-url with url $url and options
48 %options (-rect, -border, -color: see descriptions below). This
49 page is usually brought up in a browser, and may be remote.
50 $annotation->text($text, %options)
52 Defines the annotation as a text note with content string $text and
53 options %options (-rect, -color, -text, -open: see descriptions
54 below). The $text may include newlines \n for multiple lines.
55 "-text" is the popup's label string, not to be confused with the
57 main $text.
58 The icon appears in the upper left corner of the "-rect" selection
60 rectangle, and its active clickable area is fixed by the icon (it
61 is not equal to the rectangle). The icon size is fixed, and its
62 fill color set by "-color".
63 Additional options:
65 -icon => name_string
67 -icon => reference
68 Specify the icon to be used. The default is Reader-specific
69 (usually "Note"), and others may be defined by the Reader.
70 "Comment", "Key", "Help", "NewParagraph", "Paragraph", and
71 "Insert" are also supposed to be available on all PDF Readers.
72 Note that the name case must exactly match. The icon is of
73 fixed size. Any AP dictionary entry will override the -icon
74 setting.
75 A reference to an icon may be passed instead of a name.
77 -opacity => value
79 Define the opacity (non-transparency, opaqueness) of the icon.
80 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
81 and applies to both the outline and the fill color. The default
82 is 1.0.
83 $annotation->markup($text, $PointList, $highlight, %options)
85 Defines the annotation as a text note with content string $text and
86 options %options (-rect, -color, -text, -open: see descriptions
87 below). The $text may include newlines \n for multiple lines.
88 "-text" is the popup's label string, not to be confused with the
90 main $text.
91 There is no icon. Instead, the annotated text marked by $PointList
93 is highlighted in one of four ways specified by $highlight.
94 $PointList => [ 8n numbers ]
96 One or more sets of numeric coordinates are given, defining the
97 quadrilateral (usually a rectangle) around the text to be
98 highlighted and selectable (clickable, to bring up the
99 annotation text). These are four sets of "x,y" coordinates,
100 given (for Left-to-Right text) as the upper bound Upper Left to
101 Upper Right and then the lower bound Lower Left to Lower Right.
102 Note that this is different from what is (erroneously)
103 documented in the PDF specification! It is important that the
104 coordinates be given in this order.
105 Multiple sets of quadrilateral corners may be given, such as
107 for highlighted text that wraps around to new line(s). The
108 minimum is one set (8 numbers). Any AP dictionary entry will
109 override the $PointList setting. Finally, the "Rect" selection
110 rectangle is created just outside the convex bounding box
111 defined by $PointList.
112 $highlight => 'string'
114 The following highlighting effects are permitted. The "string"
115 must be spelled and capitalized exactly as given:
116 Highlight
118 The effect of a translucent "highlighter" marker.
119 Squiggly
121 The effect is an underline written in a "squiggly" manner.
122 StrikeOut
124 The text is struck-through with a straight line.
125 Underline
127 The text is marked by a straight underline.
128 -color => array of values
130 If "-color" is not given (an array of numbers in the range
131 0.0-1.0), a medium gray should be used by default. Named
132 colors are not supported at this time.
133 -opacity => value
135 Define the opacity (non-transparency, opaqueness) of the icon.
136 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
137 and applies to both the outline and the fill color. The default
138 is 1.0.
139 $annotation->movie($file, $contentType, %options)
141 Defines the annotation as a movie from $file with content (MIME)
142 type $contentType and options %options (-rect, -border, -color: see
143 descriptions below).
144 The "-rect" rectangle also serves as the area where the movie is
146 played, so it should be of usable size and aspect ratio. It does
147 not use a separate popup player. It is known to play .avi and .wav
148 files -- others have not been tested. Using Adobe Reader, it will
149 not play .mpg files (unsupported type). More work is probably
150 needed on this annotation method.
151 $annotation->file_attachment($file, %options)
153 Defines the annotation as a file attachment with file $file and
154 options %options (-rect, -color: see descriptions below). Note that
155 "-color" applies to the icon fill color, not to a selectable area
156 outline. The icon is resized (including aspect ratio changes) based
157 on the selectable rectangle given by "-rect", so watch your
158 rectangle dimensions!
159 The file, along with its name, is embedded in the PDF document and
161 may be extracted for viewing with the appropriate viewer.
162 This differs from the "file" method in that "file" looks for and
164 launches a file already on the Reader's machine, while
165 "file_attachment" embeds the file in the PDF, and makes it
166 available on the Reader's machine for actions of the user's
167 choosing.
168 Note 1: some Readers may only permit an "open" action, and may also
170 restrict file types (extensions) that will be handled. This may be
171 configurable with your Reader's security settings.
172 Note 2: the displayed file name (pop-up during mouse rollover of
174 the target rectangle) is given with the path trimmed off (file name
175 only). If you want the displayed name to exactly match the path
176 that was passed to the call, including the path, give the
177 "-notrimpath" option.
178 Options:
180 -icon => name_string
182 -icon => reference
183 Specify the icon to be used. The default is Reader-specific
184 (usually "PushPin"), and others may be defined by the Reader.
185 "Paperclip", "Graph", and "Tag" are also supposed to be
186 available on all PDF Readers. Note that the name case must
187 exactly match. "None" is a custom invisible icon defined by
188 PDF::Builder. The icon is stretched/squashed to fill the
189 defined target rectangle, so take care when defining "-rect"
190 dimensions. Any AP dictionary entry will override the -icon
191 setting.
192 A reference to an icon may be passed instead of a name.
194 -opacity => value
196 Define the opacity (non-transparency, opaqueness) of the icon.
197 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
198 and applies to both the outline and the fill color. The default
199 is 1.0.
200 -notrimpath => 1
202 If given, show the entire path and file name on mouse rollover,
203 rather than just the file name.
204 -text => string
206 A text label for the popup (on mouseover) that contains the
207 file name.
208 Note that while PDF permits different specifications (paths) to
210 DOS/Windows, Mac, and Unix (including Linux) versions of a file,
211 and different format copies to be embedded, at this time
212 PDF::Builder only permits a single file (format of your choice) to
213 be embedded. If there is user demand for multiple file formats to
214 be referenced and/or embedded, we could look into providing this,
215 although separate OS version paths may be considered obsolescent!.
216 Internal routines and common options
218 $annotation->rect($llx,$lly, $urx,$ury)
219 Sets the rectangle (active click area) of the annotation, given by
220 -rect option. This is any pair of diagonally opposite corners of
221 the rectangle.
222 The default clickable area is the icon itself.
224 Defining option. Note that this "option" is actually required.
226 -rect => [LLx, LLy, URx, URy]
228 Set annotation rectangle at "[LLx,LLy]" to "[URx,URy]" (lower
229 left and upper right coordinates). LL to UR is customary, but
230 any diagonal is allowed.
231 $annotation->border(@b)
233 Sets the border-style of the annotation, if applicable, as given by
234 the -border option. There are three entries in the array:
235 horizontal and vertical corner radii, and border width.
236 A border is used in annotations where text or some other material
238 is put down, and a clickable rectangle is defined over it (-rect).
239 A border is not used when an icon is being used to mark the
240 clickable area.
241 The default is [0 0 1] (solid line of width 1, with sharp corners).
243 Defining option:
245 -border => [CRh, CRv, W]
247 -border => [CRh, CRv, W [, on, off...]]
248 Set annotation border style of horizontal and vertical corner
249 radii "CRh" and "CRv" (value 0 for squared corners) and width
250 "W" (value 0 for no border). The default is squared corners
251 and a solid line of width 1 ([0 0 1]). Optionally, a dash
252 pattern array may be given ("on" length, "off" length, as one
253 or more pairs). The default is a solid line.
254 The border vector seems to ignore the first two settings
256 (corner radii), but the line thickness works, on basic Readers.
257 The radii may work on some other Readers.
258 $annotation->content(@lines)
260 Sets the text-content of the "text()" annotation. This is a text
261 string or array of strings.
262 $annotation->open($bool)
264 Display the "text()" annotation either open or closed, if
265 applicable.
266 Both are editable; the "open" form brings up the page with the
268 entry area already open for editing, while "closed" has to be
269 clicked on to edit it.
270 Defining option:
272 -open => boolean
274 If true (1), the annotation will be marked as initially "open".
275 If false (0), or the option is not given, the annotation is
276 initially "closed".
277 $annotation->dest($page, fit_setting)
279 For certain annotation types ("link" or "pdf_file"), the
280 fit_setting specifies how the content of the page $page is to be
281 fit to the window, while preserving its aspect ratio. These fit
282 settings are:
283 -fit => 1
285 Display the page with its contents magnified just enough to fit
286 the entire page within the window both horizontally and
287 vertically. If the required horizontal and vertical
288 magnification factors are different, use the smaller of the
289 two, centering the page within the window in the other
290 dimension.
291 -fith => $top
293 Display the page with the vertical coordinate $top positioned
294 at the top edge of the window and the contents of the page
295 magnified just enough to fit the entire width of the page
296 within the window.
297 -fitv => $left
299 Display the page with the horizontal coordinate $left
300 positioned at the left edge of the window and the contents of
301 the page magnified just enough to fit the entire height of the
302 page within the window.
303 -fitr => [$left, $bottom, $right, $top]
305 Display the page with its contents magnified just enough to fit
306 the rectangle specified by the coordinates $left, $bottom,
307 $right, and $top entirely within the window both horizontally
308 and vertically. If the required horizontal and vertical
309 magnification factors are different, use the smaller of the
310 two, centering the rectangle within the window in the other
311 dimension.
312 -fitb => 1
314 Display the page with its contents magnified just enough to fit
315 its bounding box entirely within the window both horizontally
316 and vertically. If the required horizontal and vertical
317 magnification factors are different, use the smaller of the
318 two, centering the bounding box within the window in the other
319 dimension.
320 -fitbh => $top
322 Display the page with the vertical coordinate $top positioned
323 at the top edge of the window and the contents of the page
324 magnified just enough to fit the entire width of its bounding
325 box within the window.
326 -fitbv => $left
328 Display the page with the horizontal coordinate $left
329 positioned at the left edge of the window and the contents of
330 the page magnified just enough to fit the entire height of its
331 bounding box within the window.
332 -xyz => [$left, $top, $zoom]
334 Display the page with the coordinates "[$left, $top]"
335 positioned at the top-left corner of the window and the
336 contents of the page magnified by the factor $zoom. A zero (0)
337 value for any of the parameters $left, $top, or $zoom specifies
338 that the current value of that parameter is to be retained
339 unchanged.
340 This is the default fit setting, with position (left and top)
342 and zoom the same as the calling page's ([undef, undef,
343 undef]).
344 $annotation->dest($name)
346 Connect the Annotation to a "Named Destination" defined elsewhere,
347 including the optional desired fit (default: -xyz undef*3).
348 $annotation->Color(@color)
350 Set the icon's fill color. The color is an array of 1, 3, or 4
351 numbers, each in the range 0.0 to 1.0. If 1 number is given, it is
352 the grayscale value (0 = black to 1 = white). If 3 numbers are
353 given, it is an RGB color value. If 4 numbers are given, it is a
354 CMYK color value. Currently, named colors (strings) are not
355 handled.
356 For link and url annotations, this is the color of the rectangle
358 border (-border given with a width of at least 1).
359 If an invalid array length or numeric value is given, a medium gray
361 ( [0.5] ) value is used, without any message. If no color is given,
362 the usual fill color is black.
363 Defining option:
365 Named colors are not supported at this time.
367 -color => [ ] or not 1, 3, or 4 numbers 0.0-1.0
369 A medium gray (0.5 value) will be used if an invalid color is
370 given.
371 -color => [ g ]
373 If g is between 0.0 (black) and 1.0 (white), the fill color
374 will be gray.
375 -color => [ r, g, b ]
377 If r (red), g (green), and b (blue) are all between 0.0 and
378 1.0, the fill color will be the defined RGB hue. [ 0, 0, 0 ] is
379 black, [ 1, 1, 0 ] is yellow, and [ 1, 1, 1 ] is white.
380 -color => [ c, m, y, k ]
382 If c (red), m (magenta), y (yellow), and k (black) are all
383 between 0.0 and 1.0, the fill color will be the defined CMYK
384 hue. [ 0, 0, 0, 0 ] is white, [ 1, 0, 1, 0 ] is green, and [ 1,
385 1, 1, 1 ] is black.
386 -text => string
388 Specify an optional text label for annotation. This text or comment
389 only shows up as a title in the pop-up containing the file or text.
390perl v5.34.0 2022-01-21 PDF::Builder::Annotation(3)