.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "PDF::Builder::NamedDestination 3"
.TH PDF::Builder::NamedDestination 3 2026-02-08 "perl v5.42.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::Builder::NamedDestination \- Add named destinations (views) to a PDF
.PP
Inherits from PDF::Builder::Basic::PDF::Dict
.SS Usage
.IX Subsection "Usage"
A Named Destination is defined in a PDF which is intended to be the target of
a specified Name (string), from within the same PDF, from another PDF, or
from a PDF Reader command line (e.g, MyBigPDF.pdf#nameddest=foo). The advantage
over going to a specific \fIpage\fR is that a Named Destination always points to
the same content in the document, even if that location moves around (i.e., to
a different page number).
.PP
Some Operating Systems support command line invocation (e.g., 
> MyPDF.pdf#name=bar), and some browsers\*(Aq PDF readers also support it. 
\&\f(CW\*(C`#nameddest=foo\*(C'\fR is the most basic form, and if Named Destinations are 
supported, this form should work. Some readers support the shortcut 
\&\f(CW\*(C`#name=foo\*(C'\fR, and some even support the bare name: \f(CW\*(C`#foo\*(C'\fR (similar to HTML). 
Named Destination syntax on the command line can vary widely by Reader.
.PP
A Named Destination must be unique within a given PDF, and is defined at the
top level in the \f(CW$pdf\fR object. There are often limitations on the length of
a Named Destination string (name), including the length of whatever means is 
used to invoke it (e.g., \f(CW\*(C`#nameddest=foo\*(C'\fR takes up 11 characters before you 
even get to the name \*(Aqfoo\*(Aq itself, so if the limit is 32, you\*(Aqre left with
perhaps 21 characters for the name itself). Be aware of this, and keep the 
names as short as reasonably possible. Spaces within a name are not permitted, 
and allowable punctuation is limited. Consult the PDF documentation for 
specifics, but A\-Z, a\-z, 0\-9, and \*(Aq_\*(Aq (underscore) are generally permitted. 
Usually names are case\-sensitive (\*(Aqfoo\*(Aq is a different destination than \*(AqFoo\*(Aq).
.PP
.Vb 6
\&    # create a Named Destination \*(Aqfoo\*(Aq in this PDF file on page $page
\&    my $dest = PDF::Builder::NamedDestination\->new($pdf);
\&    # its action will be to go to this page object $page, and a window within it
\&    # (various \*(Aqfits\*(Aq can be defined
\&    $dest\->goto($page, \*(Aqxyz\*(Aq, (undef, undef, undef));
\&    $pdf\->named_destination(\*(AqDests\*(Aq, \*(Aqfoo\*(Aq, $dest);
.Ve
.PP
See "named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs
for information on named destinations.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    $dest = PDF::Builder::NamedDestination\->new($pdf)
\&
\&    $dest = PDF::Builder::NamedDestination\->new($pdf, @args)
.Ve
.Sp
.RS 4
Creates a new named destination object. Any optional additional arguments
will be passed on to destination processing for "goto".
.Sp
.Vb 1
\&    $dest = PDF::Builder::NamedDestination\->new($pdf, $page, \*(Aqxyz\*(Aq, 0,700, 1.5);
.Ve
.Sp
This will create a Named Destination which goes to ("goto") page object 
\&\f(CW$page\fR, with fit XYZ at position 0,700 and zoom factor 1.5.
.Sp
It is possible to then call \`\fBgoto()\fR\` to override the \`\fBnew()\fR\` defined \fIfit\fR:
.Sp
.Vb 1
\&    $dest\->goto($page, \*(Aqfitb\*(Aq); # overrides XYZ fit
.Ve
.Sp
If you did \fBnot\fR give \fIfit\fR options in the \`\fBnew()\fR\` call (just \`$pdf\`), it 
will be necessary to call \`\fBgoto()\fR\` with \fIfit\fR settings, anyway:
.Sp
.Vb 2
\&    $dest = PDF::Builder::NamedDestination\->new($pdf);
\&    $dest\->goto($page, \*(Aqfit\*(Aq);
.Ve
.Sp
Finally, however you created the Named Destination, its action, and its page
fit, you need to tell the system 
to insert an entry into the Named Destination directory:
.Sp
.Vb 1
\&    $pdf\->named_destination(\*(AqDests\*(Aq, "foo", $dest);
.Ve
.Sp
This is where you actually \fIname\fR the destination. Consult 
"named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs 
for more information.
.RE
.SS "Target Destinations"
.IX Subsection "Target Destinations"
Note that the usual practice for a Named Destination, invoked when the PDF is
opened with a Named Destination specified, is to \fIgoto\fR a point in the 
document. It is \fIpossible\fR, though unusual, to go to a point in another 
document (\f(CWpdf()\fR), launch a local application (\f(CWlaunch()\fR), or launch a web 
browser (\f(CWuri()\fR).
.PP
The only "options" supported for \f(CW\*(C`goto\*(C'\fR and \f(CW\*(C`pdf\*(C'\fR are if you wish to give
the location and its arguments (data) in the form of a hash element (anonymous
array if more than one value). Unlike Annotation\*(Aqs "action" methods (\f(CW\*(C`goto\*(C'\fR, 
\&\f(CW\*(C`pdf\*(C'\fR, \f(CW\*(C`uri\*(C'\fR, and \f(CW\*(C`launch\*(C'\fR), there is no defining a "click area" (button)
for the user interaction; thus, no \fBrect\fR, \fBborder\fR, or \fBcolor\fR entries
are recognized in NamedDestination. Any found will be ignored.
.PP
See "Page Fit Options" in PDF::Builder::Docs for a listing of the available
locations and their syntax.
.PP
"xyz" is the \fBdefault\fR fit setting, with position (left and top) and zoom
all the same as the calling page\*(Aqs.
.PP
\fIgoto, link\fR
.IX Subsection "goto, link"
.PP
.Vb 1
\&    $dest\->goto($page, $location, @args)  # preferred
\&
\&    $dest\->goto($page, %opts)  # opts including location and data
.Ve
.Sp
.RS 4
A go\-to (link) action changes the view to a specified destination (page object, 
location code, and various pieces of data for it). This is a jump \fIwithin\fR
the current PDF document (\fBinternal\fR), and is the usual way of doing things.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`link\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`link\*(C'\fR, but PDF::API2 changed the name
to \f(CW\*(C`goto\*(C'\fR, to match the internal PDF command \f(CW\*(C`GoTo\*(C'\fR. "link" is retained 
for compatibility.
.Sp
\&\fBNotes:\fR \f(CW\*(C`goto\*(C'\fR is a reserved Perl keyword (go to a label), so take care when
using this in code that the Perl interpreter doesn\*(Aqt see this as a Perl \*(Aqgoto\*(Aq.
If you receive an error message about a "missing label" or something equally
puzzling, this may have happened. \f(CW\*(C`link\*(C'\fR is a built\-in Perl function (Unix
\&\f(CW\*(C`ln\*(C'\fR style command), so take care when using this code that the Perl 
interpreter doesn\*(Aqt see this as a Perl \*(Aqlink\*(Aq call (e.g., error message about
"not enough arguments for link").
.RE
.PP
\fIpdf, pdf_file, pdfile\fR
.IX Subsection "pdf, pdf_file, pdfile"
.PP
.Vb 1
\&    $dest\->pdf($pdffile, $page_number, $location, @args) # preferred
\&
\&    $dest\->pdf($pdffile, $page_number, %opts) # location is a hash element
.Ve
.Sp
.RS 4
Defines the destination as an \fBexternal\fR PDF\-file with filepath \f(CW$pdffile\fR, 
on page \f(CW$page_number\fR (numeric value), and 
either options \f(CW%opts\fR (location/fit => any data for it as a scalar or anonymous 
array) or one of two formats: an array of location/fit string and any data for 
it, or a location/fit string and an array with any data needed for it.
.Sp
To go to a Named Destination and then immediately jump to a point in another
PDF document is unusual, but possible.
.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 PDF::API2 changed the name to \f(CW\*(C`pdf\*(C'\fR. "pdfile" and 
"pdf_file" are retained 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 (typically a web page) with uri \f(CW$url\fR.
There are no options available.
.Sp
To go to a Named Destination and then immediately launch a web browser
is unusual, but possible.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`url\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`url\*(C'\fR, but PDF::API2 changed the name
to \f(CW\*(C`uri\*(C'\fR to match the PDF command. "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 usually a local application, 
such as a text editor or photo viewer.
There are no options available.
.Sp
To go to a Named Destination and then immediately launch a local application
is unusual, but possible.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`file\*(C'\fR
.Sp
Originally this method was \f(CW\*(C`file\*(C'\fR, but PDF::API2 changed the name
to \f(CW\*(C`launch\*(C'\fR to match the PDF command. "file" is retained for compatibility.
.RE