1PDF::Builder::AnnotatioUns(e3r)Contributed Perl DocumentPaDtFi:o:nBuilder::Annotation(3)
2
6 PDF::Builder::Annotation - Add annotations to a PDF
7
9 my $pdf = PDF::Builder->new();
10 my $font = $pdf->font('Helvetica');
11 my $page1 = $pdf->page();
12 my $page2 = $pdf->page();
13 my $content = $page1->text();
14 my $message = 'Go to Page 2';
15 my $size = 18;
16 $content->distance(1 * 72, 9 * 72);
17 $content->font($font, $size);
18 $content->text($message);
19 my $annotation = $page1->annotation();
20 my $width = $content->text_width($message);
21 $annotation->rect(1 * 72, 9 * 72, 1 * 72 + $width, 9 * 72 + $size);
22 $annotation->link($page2);
23 $pdf->save('sample.pdf');
24
26 Note that the handling of annotations can vary from Reader to Reader.
27 The available icon set may be larger or smaller than given here, and
28 some Readers activate an annotation on a single mouse click, while
29 others require a double click. Not all features provided here may be
30 available on all PDF Readers.
31 $annotation = PDF::Builder::Annotation->new()
33 Returns an annotation object (called from $page->annotation()).
34 It is normally not necessary to explicitly call this method (see
36 examples).
37 Annotation types
39 $annotation->goto($page, %opts)
40 Defines the annotation as a launch-page with page $page (within
41 this document) and opts %opts (rect, border, color, fit: see
42 descriptions below).
43 Note that $page is not a simple page number, but is a page
45 structure such as "$pdf->openpage(page_number)".
46 Alternate name: "link"
48 Originally this method was named "link", but a recent PDF::API2
50 change made it "goto". For compatibility, it has been changed to
51 "goto", with "link" still available as an alias.
52 $annotation->pdf($pdffile, $page_number, %opts)
54 Defines the annotation as a PDF-file with filepath $pdffile, on
55 page $page_number, and opts %opts (rect, border, color, fit: see
56 descriptions below). This differs from the "goto" ("link" call in
57 that the target is found in a different PDF file, not the current
58 document.
59 $page_number is the physical page number, starting at 1: 1, 2,...
61 Alternate names: "pdfile" and "pdf_file"
63 Originally this method was named "pdfile", and then "pdf_file" but
65 a recent PDF::API2 change made it "pdf". For compatibility, it has
66 been changed to "pdf", with "pdfile" and "pdf_file" still available
67 as aliases.
68 $annotation->launch($file, %opts)
70 Defines the annotation as a launch-file with filepath $file (a
71 local file) and options %opts (rect, border, color: see
72 descriptions below). How the file is displayed depends on the
73 operating system, type of file, and local configuration or mapping.
74 Alternate name: "file"
76 Originally this method was named "file", but a recent PDF::API2
78 change made it "launch". For compatibility, it has been changed to
79 "launch", with "file" still available as an alias.
80 $annotation->uri($url, %opts)
82 Defines the annotation as a launch-url with url $url and options
83 %opts (rect, border, color: see descriptions below). This page is
84 usually brought up in a browser, and may be remote.
85 Alternate name: "url"
87 Originally this method was named "url", but a recent PDF::API2
89 change made it "uri". For compatibility, it has been changed to
90 "uri", with "url" still available as an alias.
91 $annotation->text($text, %opts)
93 Defines the annotation as a text note with content string $text and
94 options %opts (rect, color, text, open: see descriptions below).
95 The $text may include newlines \n for multiple lines. The option
96 border is ignored, since an icon is used.
97 The option "text" is the popup's label string, not to be confused
99 with the main $text.
100 The icon appears in the upper left corner of the "rect" selection
102 rectangle, and its active clickable area is fixed by the icon (it
103 is not equal to the rectangle). The icon size is fixed, and its
104 fill color set by "color".
105 Additional options:
107 icon => name_string
109 icon => reference
110 Specify the icon to be used. The default is Reader-specific
111 (usually "Note"), and others may be defined by the Reader.
112 "Comment", "Key", "Help", "NewParagraph", "Paragraph", and
113 "Insert" are also supposed to be available on all PDF Readers.
114 Note that the name case must exactly match. The icon is of
115 fixed size. Any AP dictionary entry will override the icon
116 setting.
117 A reference to an icon may be passed instead of a name.
119 opacity => value
121 Define the opacity (non-transparency, opaqueness) of the icon.
122 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
123 and applies to both the outline and the fill color. The default
124 is 1.0.
125 $annotation->markup($text, $PointList, $highlight, %opts)
127 Defines the annotation as a text note with content string $text and
128 options %opts (color, text, open, opacity: see descriptions below).
129 The $text may include newlines \n for multiple lines.
130 "text" is the popup's label string, not to be confused with the
132 main $text.
133 There is no icon. Instead, the annotated text marked by $PointList
135 is highlighted in one of four ways specified by $highlight.
136 $PointList => [ 8n numbers ]
138 One or more sets of numeric coordinates are given, defining the
139 quadrilateral (usually a rectangle) around the text to be
140 highlighted and selectable (clickable, to bring up the
141 annotation text). These are four sets of "x,y" coordinates,
142 given (for Left-to-Right text) as the upper bound Upper Left to
143 Upper Right and then the lower bound Lower Left to Lower Right.
144 Note that this is different from what is (erroneously)
145 documented in the PDF specification! It is important that the
146 coordinates be given in this order.
147 Multiple sets of quadrilateral corners may be given, such as
149 for highlighted text that wraps around to new line(s). The
150 minimum is one set (8 numbers). Any AP dictionary entry will
151 override the $PointList setting. Finally, the "Rect" selection
152 rectangle is created just outside the convex bounding box
153 defined by $PointList.
154 $highlight => 'string'
156 The following highlighting effects are permitted. The "string"
157 must be spelled and capitalized exactly as given:
158 Highlight
160 The effect of a translucent "highlighter" marker.
161 Squiggly
163 The effect is an underline written in a "squiggly" manner.
164 StrikeOut
166 The text is struck-through with a straight line.
167 Underline
169 The text is marked by a straight underline.
170 color => array of values
172 If "color" is not given (an array of numbers in the range
173 0.0-1.0), a medium gray should be used by default. Named
174 colors are not supported at this time.
175 opacity => value
177 Define the opacity (non-transparency, opaqueness) of the icon.
178 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
179 and applies to both the outline and the fill color. The default
180 is 1.0.
181 $annotation->movie($file, $contentType, %opts)
183 Defines the annotation as a movie from $file with content (MIME)
184 type $contentType and options %opts (rect, border, color, text: see
185 descriptions below).
186 The "rect" rectangle also serves as the area where the movie is
188 played, so it should be of usable size and aspect ratio. It does
189 not use a separate popup player. It is known to play .avi and .wav
190 files -- others have not been tested. Using Adobe Reader, it will
191 not play .mpg files (unsupported type). More work is probably
192 needed on this annotation method.
193 $annotation->file_attachment($file, %opts)
195 Defines the annotation as a file attachment with file $file and
196 options %opts (rect, color: see descriptions below). Note that
197 "color" applies to the icon fill color, not to a selectable area
198 outline. The icon is resized (including aspect ratio changes) based
199 on the selectable rectangle given by "rect", so watch your
200 rectangle dimensions!
201 The file, along with its name, is embedded in the PDF document and
203 may be extracted for viewing with the appropriate viewer.
204 This differs from the "file" method in that "file" looks for and
206 launches a file already on the Reader's machine, while
207 "file_attachment" embeds the file in the PDF, and makes it
208 available on the Reader's machine for actions of the user's
209 choosing.
210 Note 1: some Readers may only permit an "open" action, and may also
212 restrict file types (extensions) that will be handled. This may be
213 configurable with your Reader's security settings.
214 Note 2: the displayed file name (pop-up during mouse rollover of
216 the target rectangle) is given with the path trimmed off (file name
217 only). If you want the displayed name to exactly match the path
218 that was passed to the call, including the path, give the
219 "notrimpath" option.
220 Options:
222 icon => name_string
224 icon => reference
225 Specify the icon to be used. The default is Reader-specific
226 (usually "PushPin"), and others may be defined by the Reader.
227 "Paperclip", "Graph", and "Tag" are also supposed to be
228 available on all PDF Readers. Note that the name case must
229 exactly match. "None" is a custom invisible icon defined by
230 PDF::Builder. The icon is stretched/squashed to fill the
231 defined target rectangle, so take care when defining "rect"
232 dimensions. Any AP dictionary entry will override the icon
233 setting.
234 A reference to an icon may be passed instead of a name.
236 opacity => value
238 Define the opacity (non-transparency, opaqueness) of the icon.
239 This value ranges from 0.0 (transparent) to 1.0 (fully opaque),
240 and applies to both the outline and the fill color. The default
241 is 1.0.
242 notrimpath => 1
244 If given, show the entire path and file name on mouse rollover,
245 rather than just the file name.
246 text => string
248 A text label for the popup (on mouseover) that contains the
249 file name.
250 Note that while PDF permits different specifications (paths) to
252 DOS/Windows, Mac, and Unix (including Linux) versions of a file,
253 and different format copies to be embedded, at this time
254 PDF::Builder only permits a single file (format of your choice) to
255 be embedded. If there is user demand for multiple file formats to
256 be referenced and/or embedded, we could look into providing this,
257 although separate OS version paths may be considered obsolescent!.
258 Internal routines and common options
260 $annotation->rect($llx,$lly, $urx,$ury)
261 Sets the rectangle (active click area) of the annotation, given by
262 'rect' option. This is any pair of diagonally opposite corners of
263 the rectangle.
264 The default clickable area is the icon itself.
266 Defining option. Note that this "option" is actually required.
268 rect => [LLx, LLy, URx, URy]
270 Set annotation rectangle at "[LLx,LLy]" to "[URx,URy]" (lower
271 left and upper right coordinates). LL to UR is customary, but
272 any diagonal is allowed.
273 $annotation->border(@b)
275 Sets the border-style of the annotation, if applicable, as given by
276 the border option. There are three entries in the array: horizontal
277 and vertical corner radii, and border width. An optional fourth
278 entry (described below) may be used for a dashed or dotted line.
279 A border is used in annotations where text or some other material
281 is put down, and a clickable rectangle is defined over it (rect). A
282 border is not shown when an icon is being used to mark the
283 clickable area.
284 A PDF Reader normally defaults to [0 0 1] (solid line of width 1,
286 with sharp corners) if no border ("/Border") is specified. Keeping
287 compatibility with PDF::API2's longstanding practice, PDF::Builder
288 defaults to no visible border "[0 0 0]" (solid line of width 0, and
289 thus invisible).
290 Defining option:
292 border => [CRh, CRv, W]
294 border => [CRh, CRv, W, [on, off...]]
295 Note that the square brackets [ and ] are literally there,
296 indicating a vector or array of values. They do not indicate
297 optional values!
298 Set annotation border style of horizontal and vertical corner
300 radii "CRh" and "CRv" (value 0 for squared corners) and width
301 "W" (value 0 for no border). The PDF::Builder default is no
302 border (while a PDF Reader typically defaults to no border ([0
303 0 0]), if no /Border entry is given). Optionally, a dash
304 pattern array may be given ("on" length, "off" length, as one
305 or more pairs). The default is a solid line.
306 The border vector seems to ignore the first two settings
308 (corner radii), but the line thickness works, on basic Readers.
309 The corner radii may work on some other Readers.
310 $annotation->content(@lines)
312 Sets the text-content of the "text()" annotation. This is a text
313 string or array of strings.
314 $annotation->open($bool)
316 Display the "text()" annotation either open or closed, if
317 applicable.
318 Both are editable; the "open" form brings up the page with the
320 entry area already open for editing, while "closed" has to be
321 clicked on to edit it.
322 Defining option:
324 open => boolean
326 If true (1), the annotation will be marked as initially "open".
327 If false (0), or the option is not given, the annotation is
328 initially "closed".
329 $annotation->dest($page, fit_setting)
331 For certain annotation types ("link" or "pdf_file"), the
332 fit_setting specifies how the content of the page $page is to be
333 fit to the window, while preserving its aspect ratio. These fit
334 settings are listed in "Page Fit Options" in PDF::Builder::Docs.
335 "xyz" is the default fit setting, with position (left and top) and
337 zoom the same as the calling page's ([undef, undef, undef]).
338 $annotation->dest($name)
340 Connect the Annotation to a "Named Destination" defined elsewhere,
341 including the optional desired fit (default: xyz undef*3).
342 $annotation->Color(@color)
344 Set the icon's fill color. The color is an array of 1, 3, or 4
345 numbers, each in the range 0.0 to 1.0. If 1 number is given, it is
346 the grayscale value (0 = black to 1 = white). If 3 numbers are
347 given, it is an RGB color value. If 4 numbers are given, it is a
348 CMYK color value. Currently, named colors (strings) are not
349 handled.
350 For link and url annotations, this is the color of the rectangle
352 border (border given with a width of at least 1).
353 If an invalid array length or numeric value is given, a medium gray
355 ( [0.5] ) value is used, without any message. If no color is given,
356 the usual fill color is black.
357 Defining option:
359 Named colors are not supported at this time.
361 color => [ ] or not 1, 3, or 4 numbers 0.0-1.0
363 A medium gray (0.5 value) will be used if an invalid color is
364 given.
365 color => [ g ]
367 If g is between 0.0 (black) and 1.0 (white), the fill color
368 will be gray.
369 color => [ r, g, b ]
371 If r (red), g (green), and b (blue) are all between 0.0 and
372 1.0, the fill color will be the defined RGB hue. [ 0, 0, 0 ] is
373 black, [ 1, 1, 0 ] is yellow, and [ 1, 1, 1 ] is white.
374 color => [ c, m, y, k ]
376 If c (red), m (magenta), y (yellow), and k (black) are all
377 between 0.0 and 1.0, the fill color will be the defined CMYK
378 hue. [ 0, 0, 0, 0 ] is white, [ 1, 0, 1, 0 ] is green, and [ 1,
379 1, 1, 1 ] is black.
380 text => string
382 Specify an optional text label for annotation. This text or comment
383 only shows up as a title in the pop-up containing the file or text.
384perl v5.36.0 2022-09-13 PDF::Builder::Annotation(3)