.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::NamedDestination 3"
.TH PDF::Builder::NamedDestination 3 2023-12-21 "perl v5.38.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::NamedDestination \- Add named destinations (views) to a PDF
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    $dest = PDF::Builder::NamedDestination\->new($pdf, ...)
.Ve
.Sp
.RS 4
Creates a new named destination object. Any optional additional arguments
will be passed on to \f(CW\*(C`destination\*(C'\fR.
.RE
.SS "Destination types"
.IX Subsection "Destination types"
\fIdest\fR
.IX Subsection "dest"
.PP
.Vb 1
\&    $dest\->dest($page, %opts)
.Ve
.Sp
.RS 4
A destination (dest) is a particular view of a PDF, consisting of a page 
object, the
location of the window on that page, and possible coordinate and zoom arguments.
.Sp
.Vb 3
\&    # The XYZ location takes three arguments
\&    my $dest1 = PDF::Builder::NamedDestination\->new($pdf);
\&    $dest\->dest($pdf\->open_page(1), \*(Aqxyz\*(Aq => [$x, $y, $zoom]);
\&
\&    # The Fit location doesn\*(Aqt require any arguments, but one is still
\&    # needed for the hash array
\&    my $dest2 = PDF::Builder::NamedDestination\->new($pdf);
\&    $dest\->dest($pdf\->open_page(2), \*(Aqfit\*(Aq => 1);
.Ve
.Sp
See "Page Fit Options" in PDF::Builder::Docs for a listing of the available
locations and their syntax.
.Sp
"xyz" is the \fBdefault\fR fit setting, with position (left and top) and zoom
the same as the calling page's.
.RE
.SS "Target Destinations"
.IX Subsection "Target Destinations"
\fIlink, goto\fR
.IX Subsection "link, goto"
.PP
.Vb 1
\&    $dest\->link($page, %opts)
.Ve
.Sp
.RS 4
A go-to (link) action changes the view to a specified destination (page, 
location, and magnification factor).
.Sp
Parameters are as described in \f(CW\*(C`dest\*(C'\fR.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`goto\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`link\*(C'\fR, but recently PDF::API2 changed the name
to \f(CW\*(C`goto\*(C'\fR. "goto" is added for compatibility.
.RE
.PP
\fIuri, url\fR
.IX Subsection "uri, url"
.PP
.Vb 1
\&    $dest\->uri($url)
.Ve
.Sp
.RS 4
Defines the destination as launch-url with uri \f(CW$url\fR.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`url\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`url\*(C'\fR, but recently PDF::API2 changed the name
to \f(CW\*(C`uri\*(C'\fR. "url" is retained for compatibility.
.RE
.PP
\fIlaunch, file\fR
.IX Subsection "launch, file"
.PP
.Vb 1
\&    $dest\->launch($file)
.Ve
.Sp
.RS 4
Defines the destination as launch-file with filepath \f(CW$file\fR and
page-fit options \f(CW%opts\fR. The target application is run. Note that this is
\&\fBnot\fR a PDF \fIor\fR a browser file \-\- it is a local application.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`file\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`file\*(C'\fR, but recently PDF::API2 changed the name
to \f(CW\*(C`launch\*(C'\fR. "file" is retained for compatibility.
.RE
.PP
\fIpdf, pdf_file, pdfile\fR
.IX Subsection "pdf, pdf_file, pdfile"
.PP
.Vb 1
\&    $dest\->pdf($pdf_file, $pagenum, %opts)
.Ve
.Sp
.RS 4
Defines the destination as a PDF-file with filepath \f(CW$pdf_file\fR, on page
\&\f(CW$pagenum\fR, and options \f(CW%opts\fR (same as \fBdest()\fR).
.Sp
\&\fBAlternate names:\fR \f(CW\*(C`pdf_file\*(C'\fR and \f(CW\*(C`pdfile\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`pdfile\*(C'\fR, and had been earlier renamed to 
\&\f(CW\*(C`pdf_file\*(C'\fR, but recently PDF::API2 changed the name to \f(CW\*(C`pdf\*(C'\fR. "pdfile" and 
"pdf_file" are retained for compatibility. \fBNote that\fR the position and zoom
information is still given as a hash element in PDF::Builder, while PDF::API2
has changed to a position string and an array of dimensions.
.RE