.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Annotation 3pm"
.TH PDF::Builder::Annotation 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder::Annotation \- Add annotations to a PDF
.SH "METHODS"
.IX Header "METHODS"
Note that the handling of annotations can vary from Reader to Reader. The
available icon set may be larger or smaller than given here, and some Readers
activate an annotation on a single mouse click, while others require a double
click. Not all features provided here may be available on all \s-1PDF\s0 Readers.
.ie n .IP "$annotation = PDF::Builder::Annotation\->\fBnew()\fR" 4
.el .IP "\f(CW$annotation\fR = PDF::Builder::Annotation\->\fBnew()\fR" 4
.IX Item "$annotation = PDF::Builder::Annotation->new()"
Returns an annotation object (called from \f(CW$page\fR\->\fBannotation()\fR).
.Sp
It is normally \fInot\fR necessary to explicitly call this method (see examples).
.SS "Annotation types"
.IX Subsection "Annotation types"
.ie n .IP "$annotation\->link($page, %options)" 4
.el .IP "\f(CW$annotation\fR\->link($page, \f(CW%options\fR)" 4
.IX Item "$annotation->link($page, %options)"
.PD 0
.ie n .IP "$annotation\->link($page)" 4
.el .IP "\f(CW$annotation\fR\->link($page)" 4
.IX Item "$annotation->link($page)"
.PD
Defines the annotation as a launch-page with page \f(CW$page\fR (within \fIthis\fR
document) and options \f(CW%options\fR (\-rect, \-border, \-color, \fIfit\fR: see 
descriptions below).
.Sp
\&\fBNote\fR that \f(CW$page\fR is \fInot\fR a simple page number, but is a page structure
such as \f(CW\*(C`$pdf\->openpage(page_number)\*(C'\fR.
.ie n .IP "$annotation\->pdf_file($pdffile, $page_number, %options)" 4
.el .IP "\f(CW$annotation\fR\->pdf_file($pdffile, \f(CW$page_number\fR, \f(CW%options\fR)" 4
.IX Item "$annotation->pdf_file($pdffile, $page_number, %options)"
Defines the annotation as a PDF-file with filepath \f(CW$pdffile\fR, on page 
\&\f(CW$page_number\fR, and options \f(CW%options\fR (\-rect, \-border, \-color, \fIfit\fR: see 
descriptions below). This differs from the \f(CW\*(C`link\*(C'\fR call in that the target 
is found in a different \s-1PDF\s0 file, not the current document.
.Sp
\&\f(CW$page_number\fR is the physical page number, starting at 1: 1, 2,...
.ie n .IP "$annotation\->file($file, %options)" 4
.el .IP "\f(CW$annotation\fR\->file($file, \f(CW%options\fR)" 4
.IX Item "$annotation->file($file, %options)"
Defines the annotation as a launch-file with filepath \f(CW$file\fR (a local file)
and options \f(CW%options\fR (\-rect, \-border, \-color: see descriptions below). 
\&\fIHow\fR the file is displayed depends on the operating system, type of file, 
and local configuration or mapping.
.ie n .IP "$annotation\->url($url, %options)" 4
.el .IP "\f(CW$annotation\fR\->url($url, \f(CW%options\fR)" 4
.IX Item "$annotation->url($url, %options)"
Defines the annotation as a launch-url with url \f(CW$url\fR and
options \f(CW%options\fR (\-rect, \-border, \-color: see descriptions below). 
This page is usually brought up in a browser, and may be remote.
.ie n .IP "$annotation\->text($text, %options)" 4
.el .IP "\f(CW$annotation\fR\->text($text, \f(CW%options\fR)" 4
.IX Item "$annotation->text($text, %options)"
Defines the annotation as a text note with content string \f(CW$text\fR and
options \f(CW%options\fR (\-rect, \-color, \-text, \-open: see descriptions below). 
The \f(CW$text\fR may include newlines \en for multiple lines.
.Sp
\&\f(CW\*(C`\-text\*(C'\fR is the popup's label string, not to be confused with the main \f(CW$text\fR.
.Sp
The icon appears in the upper left corner of the \f(CW\*(C`\-rect\*(C'\fR selection rectangle,
and its active clickable area is fixed by the icon (it is \fInot\fR equal to the 
rectangle). The icon size is fixed, and its fill color set by \f(CW\*(C`\-color\*(C'\fR.
.Sp
Additional options:
.RS 4
.IP "\-icon => name_string" 4
.IX Item "-icon => name_string"
.PD 0
.IP "\-icon => reference" 4
.IX Item "-icon => reference"
.PD
Specify the \fBicon\fR to be used. The default is Reader-specific (usually 
\&\f(CW\*(C`Note\*(C'\fR), and others may be 
defined by the Reader. \f(CW\*(C`Comment\*(C'\fR, \f(CW\*(C`Key\*(C'\fR, \f(CW\*(C`Help\*(C'\fR, \f(CW\*(C`NewParagraph\*(C'\fR, 
\&\f(CW\*(C`Paragraph\*(C'\fR, and \f(CW\*(C`Insert\*(C'\fR are also supposed to 
be available on all \s-1PDF\s0 Readers. Note that the name \fIcase\fR must exactly match.
The icon is of fixed size.
Any \fI\s-1AP\s0\fR dictionary entry will override the \-icon setting.
.Sp
A \fIreference\fR to an icon may be passed instead of a name.
.RE
.RS 4
.RE
.ie n .IP "$annotation\->movie($file, $contentType, %options)" 4
.el .IP "\f(CW$annotation\fR\->movie($file, \f(CW$contentType\fR, \f(CW%options\fR)" 4
.IX Item "$annotation->movie($file, $contentType, %options)"
Defines the annotation as a movie from \f(CW$file\fR with 
content (\s-1MIME\s0) type \f(CW$contentType\fR and
options \f(CW%options\fR (\-rect, \-border, \-color: see descriptions below).
.Sp
The \f(CW\*(C`\-rect\*(C'\fR rectangle also serves as the area where the movie is played, so it
should be of usable size and aspect ratio. It does not use a separate popup
player. It is known to play .avi and .wav files \*(-- others have not been tested.
Using Adobe Reader, it will not play .mpg files (unsupported type). More work
is probably needed on this annotation method.
.ie n .IP "$annotation\->file_attachment($file, %options)" 4
.el .IP "\f(CW$annotation\fR\->file_attachment($file, \f(CW%options\fR)" 4
.IX Item "$annotation->file_attachment($file, %options)"
Defines the annotation as a file attachment with file \f(CW$file\fR and options \f(CW%options\fR
(\-rect, \-color: see descriptions below). Note that \f(CW\*(C`\-color\*(C'\fR applies to
the icon fill color, not to a selectable area outline. The icon is resized
(including aspect ratio changes) based on the selectable rectangle given by
\&\f(CW\*(C`\-rect\*(C'\fR, so watch your rectangle dimensions!
.Sp
The file, along with its name, is \fIembedded\fR in the \s-1PDF\s0 document and may be
extracted for viewing with the appropriate viewer.
.Sp
This differs from the \f(CW\*(C`file\*(C'\fR method in that \f(CW\*(C`file\*(C'\fR looks for and launches
a file \fIalready\fR on the Reader's machine, while \f(CW\*(C`file_attachment\*(C'\fR embeds the 
file in the \s-1PDF,\s0 and makes it available on the Reader's machine for actions
of the user's choosing.
.Sp
\&\fBNote 1:\fR some Readers may only permit an \*(L"open\*(R" action, and may also restrict 
file types (extensions) that will be handled. This may be configurable with
your Reader's security settings.
.Sp
\&\fBNote 2:\fR the displayed file name (pop-up during mouse rollover of the target 
rectangle) is given with the \fIpath\fR trimmed off (file name only). If you want
the displayed name to exactly match the path that was passed to the call, 
including the path, give the \f(CW\*(C`\-notrimpath\*(C'\fR option.
.Sp
Options:
.RS 4
.IP "\-icon => name_string" 4
.IX Item "-icon => name_string"
.PD 0
.IP "\-icon => reference" 4
.IX Item "-icon => reference"
.PD
Specify the \fBicon\fR to be used. The default is Reader-specific (usually 
\&\f(CW\*(C`PushPin\*(C'\fR), and others may be 
defined by the Reader. \f(CW\*(C`Paperclip\*(C'\fR, \f(CW\*(C`Graph\*(C'\fR, and \f(CW\*(C`Tag\*(C'\fR are also supposed to 
be available on all \s-1PDF\s0 Readers. Note that the name \fIcase\fR must exactly match.
\&\f(CW\*(C`None\*(C'\fR is a custom invisible icon defined by PDF::Builder.
The icon is stretched/squashed to fill the defined target rectangle, so take
care when defining \f(CW\*(C`\-rect\*(C'\fR dimensions.
Any \fI\s-1AP\s0\fR dictionary entry will override the \-icon setting.
.Sp
A \fIreference\fR to an icon may be passed instead of a name.
.IP "\-notrimpath => 1" 4
.IX Item "-notrimpath => 1"
If given, show the entire path and file name on mouse rollover, rather than
just the file name.
.IP "\-text => string" 4
.IX Item "-text => string"
A text label for the popup (on mouseover) that contains the file name.
.RE
.RS 4
.RE
.SS "Internal routines and common options"
.IX Subsection "Internal routines and common options"
.ie n .IP "$annotation\->rect($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$annotation\fR\->rect($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$annotation->rect($llx,$lly, $urx,$ury)"
Sets the rectangle (active click area) of the annotation, given by \-rect option.
This is any pair of diagonally opposite corners of the rectangle.
.Sp
The default clickable area is the icon itself.
.Sp
Defining option. \fINote that this \*(L"option\*(R" is actually \f(BIrequired\fI.\fR
.RS 4
.IP "\-rect => [LLx, LLy, URx, URy]" 4
.IX Item "-rect => [LLx, LLy, URx, URy]"
Set annotation rectangle at \f(CW\*(C`[LLx,LLy]\*(C'\fR to \f(CW\*(C`[URx,URy]\*(C'\fR (lower left and
upper right coordinates). \s-1LL\s0 to \s-1UR\s0 is customary, but any diagonal is allowed.
.RE
.RS 4
.RE
.ie n .IP "$annotation\->border(@b)" 4
.el .IP "\f(CW$annotation\fR\->border(@b)" 4
.IX Item "$annotation->border(@b)"
Sets the border-style of the annotation, if applicable, as given by the
\&\-border option. There are three entries in the array:
horizontal and vertical corner radii, and border width.
.Sp
A border is used in annotations where text or some other material is put down,
and a clickable rectangle is defined over it (\-rect). A border is not used
when an icon is being used to mark the clickable area.
.Sp
The default is [0 0 1] (solid line of width 1, with sharp corners).
.Sp
Defining option:
.RS 4
.IP "\-border => [CRh, CRv, W]" 4
.IX Item "-border => [CRh, CRv, W]"
.PD 0
.IP "\-border => [CRh, CRv, W [, on, off...]]" 4
.IX Item "-border => [CRh, CRv, W [, on, off...]]"
.PD
Set annotation \fBborder style\fR of horizontal and vertical corner radii \f(CW\*(C`CRh\*(C'\fR 
and \f(CW\*(C`CRv\*(C'\fR (value 0 for squared corners) and width \f(CW\*(C`W\*(C'\fR (value 0 for no border).
The default is squared corners and a solid line of width 1 ([0 0 1]).
Optionally, a dash pattern array may be given (\f(CW\*(C`on\*(C'\fR length, \f(CW\*(C`off\*(C'\fR length,
as one or more \fIpairs\fR). The default is a solid line.
.Sp
The border vector seems to ignore the first two settings (corner radii), but 
the line thickness works, on basic Readers. 
The radii \fImay\fR work on some other Readers.
.RE
.RS 4
.RE
.ie n .IP "$annotation\->content(@lines)" 4
.el .IP "\f(CW$annotation\fR\->content(@lines)" 4
.IX Item "$annotation->content(@lines)"
Sets the text-content of the \f(CW\*(C`text()\*(C'\fR annotation.
This is a text string or array of strings.
.ie n .IP "$annotation\->open($bool)" 4
.el .IP "\f(CW$annotation\fR\->open($bool)" 4
.IX Item "$annotation->open($bool)"
Display the \f(CW\*(C`text()\*(C'\fR annotation either open or closed, if applicable.
.Sp
Both are editable; the \*(L"open\*(R" form brings up the page with the entry area
already open for editing, while \*(L"closed\*(R" has to be clicked on to edit it.
.Sp
Defining option:
.RS 4
.IP "\-open => boolean" 4
.IX Item "-open => boolean"
If true (1), the annotation will be marked as initially \*(L"open\*(R".
If false (0), or the option is not given, the annotation is initially \*(L"closed\*(R".
.RE
.RS 4
.RE
.ie n .IP "$annotation\->dest($page, \fIfit_setting\fR)" 4
.el .IP "\f(CW$annotation\fR\->dest($page, \fIfit_setting\fR)" 4
.IX Item "$annotation->dest($page, fit_setting)"
For certain annotation types (\f(CW\*(C`link\*(C'\fR or \f(CW\*(C`pdf_file\*(C'\fR), the \fIfit_setting\fR 
specifies how the content of the page \f(CW$page\fR is to be fit to the window,
while preserving its aspect ratio. 
These fit settings are:
.RS 4
.IP "\-fit => 1" 4
.IX Item "-fit => 1"
Display the page with its contents magnified just enough
to fit the entire page within the window both horizontally and vertically. If 
the required horizontal and vertical magnification factors are different, use 
the smaller of the two, centering the page within the window in the other 
dimension.
.ie n .IP "\-fith => $top" 4
.el .IP "\-fith => \f(CW$top\fR" 4
.IX Item "-fith => $top"
Display the page with the vertical coordinate \f(CW$top\fR 
positioned at the top edge of the window and the contents of the page magnified 
just enough to fit the entire width of the page within the window.
.ie n .IP "\-fitv => $left" 4
.el .IP "\-fitv => \f(CW$left\fR" 4
.IX Item "-fitv => $left"
Display the page with the horizontal coordinate \f(CW$left\fR
positioned at the left edge of the window and the contents of the page magnified
just enough to fit the entire height of the page within the window.
.ie n .IP "\-fitr => [$left, $bottom, $right, $top]" 4
.el .IP "\-fitr => [$left, \f(CW$bottom\fR, \f(CW$right\fR, \f(CW$top\fR]" 4
.IX Item "-fitr => [$left, $bottom, $right, $top]"
Display the page with its contents magnified just enough
to fit the rectangle specified by the coordinates \f(CW$left\fR, \f(CW$bottom\fR, 
\&\f(CW$right\fR, and \f(CW$top\fR entirely within the window both horizontally and 
vertically. If the required horizontal and vertical magnification factors are 
different, use the smaller of the two, centering the rectangle within the window
in the other dimension.
.IP "\-fitb => 1" 4
.IX Item "-fitb => 1"
Display the page with its contents magnified 
just enough to fit its bounding box entirely within the window both horizontally
and vertically. If the required horizontal and vertical magnification factors 
are different, use the smaller of the two, centering the bounding box within the
window in the other dimension.
.ie n .IP "\-fitbh => $top" 4
.el .IP "\-fitbh => \f(CW$top\fR" 4
.IX Item "-fitbh => $top"
Display the page with the vertical coordinate 
\&\f(CW$top\fR positioned at the top edge of the window and the contents of the page 
magnified just enough to fit the entire width of its bounding box within the 
window.
.ie n .IP "\-fitbv => $left" 4
.el .IP "\-fitbv => \f(CW$left\fR" 4
.IX Item "-fitbv => $left"
Display the page with the horizontal 
coordinate \f(CW$left\fR positioned at the left edge of the window and the contents 
of the page magnified just enough to fit the entire height of its bounding box 
within the window.
.ie n .IP "\-xyz => [$left, $top, $zoom]" 4
.el .IP "\-xyz => [$left, \f(CW$top\fR, \f(CW$zoom\fR]" 4
.IX Item "-xyz => [$left, $top, $zoom]"
Display the page with the coordinates \f(CW\*(C`[$left, $top]\*(C'\fR 
positioned at the top-left corner of the window and the contents of the page 
magnified by the factor \f(CW$zoom\fR. A zero (0) value for any of the parameters 
\&\f(CW$left\fR, \f(CW$top\fR, or \f(CW$zoom\fR specifies that the current value of that 
parameter is to be retained unchanged.
.Sp
This is the \fBdefault\fR fit setting, with position (left and top) and zoom
the same as the calling page's ([undef, undef, undef]).
.RE
.RS 4
.RE
.ie n .IP "$annotation\->dest($name)" 4
.el .IP "\f(CW$annotation\fR\->dest($name)" 4
.IX Item "$annotation->dest($name)"
Connect the Annotation to a \*(L"Named Destination\*(R" defined elsewhere, including
the optional desired \fIfit\fR (default: \-xyz undef*3).
.ie n .IP "$annotation\->Color(@color)" 4
.el .IP "\f(CW$annotation\fR\->Color(@color)" 4
.IX Item "$annotation->Color(@color)"
Set the icon's fill color. The color is an array of 1, 3, or 4 numbers, each
in the range 0.0 to 1.0. If 1 number is given, it is the grayscale value (0 = 
black to 1 = white). If 3 numbers are given, it is an \s-1RGB\s0 color value. If 4
numbers are given, it is a \s-1CMYK\s0 color value. Currently, named colors (strings)
are not handled.
.Sp
For link and url annotations, this is the color of the rectangle border 
(\-border given with a width of at least 1).
.Sp
If an invalid array length or numeric value is given, a medium gray ( [0.5] ) 
value is used, without any message. If no color is given, the usual fill color
is black.
.Sp
Defining option:
.RS 4
.IP "\-color => [ ] or not 1, 3, or 4 numbers 0.0\-1.0" 4
.IX Item "-color => [ ] or not 1, 3, or 4 numbers 0.0-1.0"
A medium gray (0.5 value) will be used if an invalid color is given.
.IP "\-color => [ g ]" 4
.IX Item "-color => [ g ]"
If \fIg\fR is between 0.0 (black) and 1.0 (white), the fill color will be gray.
.IP "\-color => [ r, g, b ]" 4
.IX Item "-color => [ r, g, b ]"
If \fIr\fR (red), \fIg\fR (green), and \fIb\fR (blue) are all between 0.0 and 1.0, the 
fill color will be the defined \s-1RGB\s0 hue. [ 0, 0, 0 ] is black, [ 1, 1, 0 ] is
yellow, and [ 1, 1, 1 ] is white.
.IP "\-color => [ c, m, y, k ]" 4
.IX Item "-color => [ c, m, y, k ]"
If \fIc\fR (red), \fIm\fR (magenta), \fIy\fR (yellow), and \fIk\fR (black) are all between 
0.0 and 1.0, the fill color will be the defined \s-1CMYK\s0 hue. [ 0, 0, 0, 0 ] is
white, [ 1, 0, 1, 0 ] is green, and [ 1, 1, 1, 1 ] is black.
.RE
.RS 4
.RE
.IP "\-text => string" 4
.IX Item "-text => string"
Specify an optional \fBtext label\fR for annotation. This text or comment only
shows up \fIas a title\fR in the pop-up containing the file or text.