PDF::Builder::NamedDestination3pm

    $dest = PDF::Builder::NamedDestination->new($pdf)
    $dest = PDF::Builder::NamedDestination->new($pdf, @args)

Creates a new named destination object. Any optional additional arguments will be passed on to destination processing for "goto".

    $dest = PDF::Builder::NamedDestination->new($pdf, $page, 'xyz', 0,700, 1.5);

This will create a Named Destination which goes to ("goto") page object $page, with fit XYZ at position 0,700 and zoom factor 1.5.

It is possible to then call `goto()` to override the `new()` defined fit:

    $dest->goto($page, 'fitb'); # overrides XYZ fit

If you did not give fit options in the `new()` call (just `$pdf`), it will be necessary to call `goto()` with fit settings, anyway:

    $dest = PDF::Builder::NamedDestination->new($pdf);
    $dest->goto($page, 'fit');

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:

    $pdf->named_destination('Dests', "foo", $dest);

This is where you actually name the destination. Consult "named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs for more information.

    $dest->goto($page, $location, @args)  # preferred
    $dest->goto($page, %opts)  # opts including location and data

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 within the current PDF document (internal), and is the usual way of doing things.

Alternate name: "link"

Originally this method was "link", but PDF::API2 changed the name to "goto", to match the internal PDF command "GoTo". "link" is retained for compatibility.

Notes: "goto" is a reserved Perl keyword (go to a label), so take care when using this in code that the Perl interpreter doesn't see this as a Perl 'goto'. If you receive an error message about a "missing label" or something equally puzzling, this may have happened. "link" is a built-in Perl function (Unix "ln" style command), so take care when using this code that the Perl interpreter doesn't see this as a Perl 'link' call (e.g., error message about "not enough arguments for link").

    $dest->pdf($pdffile, $page_number, $location, @args) # preferred
    $dest->pdf($pdffile, $page_number, %opts) # location is a hash element

Defines the destination as an external PDF-file with filepath $pdffile, on page $page_number (numeric value), and either options %opts (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.

To go to a Named Destination and then immediately jump to a point in another PDF document is unusual, but possible.

Alternate names: "pdf_file" and "pdfile"

Originally this method was "pdfile", and had been earlier renamed to "pdf_file", but PDF::API2 changed the name to "pdf". "pdfile" and "pdf_file" are retained for compatibility.

    $dest->uri($url)

Defines the destination as launch-url (typically a web page) with uri $url. There are no options available.

To go to a Named Destination and then immediately launch a web browser is unusual, but possible.

Alternate name: "url"

Originally this method was "url", but PDF::API2 changed the name to "uri" to match the PDF command. "url" is retained for compatibility.

    $dest->launch($file)

Defines the destination as launch-file with filepath $file and page-fit options %opts. The target application is run. Note that this is not a PDF or a browser file -- it is a usually a local application, such as a text editor or photo viewer. There are no options available.

To go to a Named Destination and then immediately launch a local application is unusual, but possible.

Alternate name: "file"

Originally this method was "file", but PDF::API2 changed the name to "launch" to match the PDF command. "file" is retained for compatibility.