.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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::API2::NamedDestination 3pm"
.TH PDF::API2::NamedDestination 3pm "2023-09-29" "perl v5.36.0" "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::API2::NamedDestination \- Add named destinations (views) to a PDF
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    $destination = PDF::API2::NamedDestination\->new($pdf, ...);
.Ve
.PP
Creates a new named destination object.  If any additional arguments are
present, they will be passed to \f(CW\*(C`destination()\*(C'\fR.
.SS "destination"
.IX Subsection "destination"
.Vb 1
\&    $destination = $destination\->destination($page, $location, @args);
.Ve
.PP
A destination is a particular view of a \s-1PDF,\s0 consisting of a page object, the
location of the window on that page, and possible coordinate and zoom arguments.
.PP
.Vb 3
\&    # The XYZ location takes three arguments
\&    my $dest1 = PDF::API2::NamedDestination\->new($pdf);
\&    $dest\->destination($pdf\->open_page(1), \*(Aqxyz\*(Aq => ($x, $y, $zoom));
\&
\&    # The Fit location doesn\*(Aqt require any arguments
\&    my $dest2 = PDF::API2::NamedDestination\->new($pdf);
\&    $dest\->destination($pdf\->open_page(2), \*(Aqfit\*(Aq);
.Ve
.PP
The following locations are available:
.IP "\(bu" 4
xyz ($left, \f(CW$top\fR, \f(CW$zoom\fR)
.Sp
Display the page with the coordinates (\f(CW$left\fR, \f(CW$top\fR) positioned at the
upper-left corner of the window and the contents of the page magnified by the
factor \f(CW$zoom\fR. An \f(CW\*(C`undef\*(C'\fR value for any of the arguments specifies that the
current value of that argument shall be retained unchanged.  A zoom factor of 0
has the same meaning as \f(CW\*(C`undef\*(C'\fR.
.IP "\(bu" 4
fit
.Sp
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.
.IP "\(bu" 4
fith ($top)
.Sp
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.  An \f(CW\*(C`undef\*(C'\fR value for \f(CW$top\fR
specifies that the current value of that argument shall be retained unchanged.
.IP "\(bu" 4
fitv ($left)
.Sp
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.  An \f(CW\*(C`undef\*(C'\fR value for \f(CW$left\fR
specifies that the current value of that argument shall be retained unchanged.
.IP "\(bu" 4
fitr ($left, \f(CW$bottom\fR, \f(CW$right\fR, \f(CW$top\fR)
.Sp
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 "\(bu" 4
fitb
.Sp
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.
.IP "\(bu" 4
fitbh ($top)
.Sp
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.  An \f(CW\*(C`undef\*(C'\fR value for
\&\f(CW$top\fR specifies that the current value of that argument shall be retained
unchanged.
.IP "\(bu" 4
fitbv ($left)
.Sp
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.  An \f(CW\*(C`undef\*(C'\fR value for
\&\f(CW$left\fR specifies that the current value of that argument shall be retained
unchanged.
.SS "goto"
.IX Subsection "goto"
.Vb 1
\&    $destination = $destination\->goto($page, $location, @args);
.Ve
.PP
A go-to action changes the view to a specified destination (page, location, and
magnification factor).
.PP
Parameters are as described in \f(CW\*(C`destination\*(C'\fR.
.SS "uri"
.IX Subsection "uri"
.Vb 1
\&    $destination = $destination\->uri($uri);
.Ve
.PP
A \s-1URI\s0 action indicates that a \s-1URI\s0 \*(-- typically a web page \*(-- should be launched.
.SS "launch"
.IX Subsection "launch"
.Vb 1
\&    $destination = $destination\->launch($file);
.Ve
.PP
A launch action runs an application or opens or prints a document.
.PP
\&\f(CW$file\fR contains the path to the application to be launched or the document to
be opened or printed.
.SS "pdf"
.IX Subsection "pdf"
.Vb 1
\&    $destination = $destination\->pdf($file, $page_number, $location, @args);
.Ve
.PP
Similar to \f(CW\*(C`goto\*(C'\fR, but the destination is in a different \s-1PDF\s0 file located at
\&\f(CW$file\fR.  \f(CW$page_number\fR is an integer rather than a page object, and the
other parameters are as described in \f(CW\*(C`destination\*(C'\fR.