1PDF::Builder::AnnotatioUns(e3r)Contributed Perl DocumentPaDtFi:o:nBuilder::Annotation(3)
2
3
4

NAME

6       PDF::Builder::Annotation - Add annotations to a PDF
7

SYNOPSIS

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

METHODS

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
32       $annotation = PDF::Builder::Annotation->new()
33           Returns an annotation object (called from $page->annotation()).
34
35           It is normally not necessary to explicitly call this method (see
36           examples).
37
38   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
44           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
48       $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
54           $page_number is the physical page number, starting at 1: 1, 2,...
55
56           Alternate names: "pdfile" and "pdf_file"
57
58           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
63       $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
69           Alternate name: "file"
70
71           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
75       $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
80           Alternate name: "url"
81
82           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
86       $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
92           The option "text" is the popup's label string, not to be confused
93           with the main $text.
94
95           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
100           Additional options:
101
102           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
112               A reference to an icon may be passed instead of a name.
113
114           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
120       $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
125           "text" is the popup's label string, not to be confused with the
126           main $text.
127
128           There is no icon. Instead, the annotated text marked by $PointList
129           is highlighted in one of four ways specified by $highlight.
130
131           $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
142               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
149           $highlight => 'string'
150               The following highlighting effects are permitted. The "string"
151               must be spelled and capitalized exactly as given:
152
153               Highlight
154                   The effect of a translucent "highlighter" marker.
155
156               Squiggly
157                   The effect is an underline written in a "squiggly" manner.
158
159               StrikeOut
160                   The text is struck-through with a straight line.
161
162               Underline
163                   The text is marked by a straight underline.
164
165           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
170           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
176       $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
181           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
188       $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
196           The file, along with its name, is embedded in the PDF document and
197           may be extracted for viewing with the appropriate viewer.
198
199           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
205           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
209           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
215           Options:
216
217           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
229               A reference to an icon may be passed instead of a name.
230
231           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
237           notrimpath => 1
238               If given, show the entire path and file name on mouse rollover,
239               rather than just the file name.
240
241           text => string
242               A text label for the popup (on mouseover) that contains the
243               file name.
244
245           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
253   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
259           The default clickable area is the icon itself.
260
261           Defining option. Note that this "option" is actually required.
262
263           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
268       $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
274           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
279           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
285           Defining option:
286
287           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
293               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
301               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
305       $annotation->content(@lines)
306           Sets the text-content of the text() annotation.  This is a text
307           string or array of strings.
308
309       $annotation->open($bool)
310           Display the text() annotation either open or closed, if applicable.
311
312           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
316           Defining option:
317
318           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
323       $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
329           "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
332       $annotation->dest($name)
333           Connect the Annotation to a "Named Destination" defined elsewhere,
334           including the optional desired fit (default: xyz undef*3).
335
336       $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
344           For link and url annotations, this is the color of the rectangle
345           border (border given with a width of at least 1).
346
347           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
351           Defining option:
352
353           Named colors are not supported at this time.
354
355           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
359           color => [ g ]
360               If g is between 0.0 (black) and 1.0 (white), the fill color
361               will be gray.
362
363           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
368           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
374       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.
377
378
379
380perl v5.36.0                      2023-01-23       PDF::Builder::Annotation(3)
Impressum