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