/ 
PDF-Builder-3.028
River stage one • 2 direct dependents • 2 total dependents
⭐ Starred 6 GitHub stars
/ PDF::Builder::NamedDestination

NAME

PDF::Builder::NamedDestination - Add named destinations (views) to a PDF

Inherits from PDF::Builder::Basic::PDF::Dict

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 page 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).

Some Operating Systems support command line invocation (e.g., > MyPDF.pdf#name=bar), and some browsers' PDF readers also support it. #nameddest=foo is the most basic form, and if Named Destinations are supported, this form should work. Some readers support the shortcut #name=foo, and some even support the bare name: #foo (similar to HTML). Named Destination syntax on the command line can vary widely by Reader.

A Named Destination must be unique within a given PDF, and is defined at the top level in the $pdf 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., #nameddest=foo takes up 11 characters before you even get to the name 'foo' itself, so if the limit is 32, you're 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 '_' (underscore) are generally permitted. Usually names are case-sensitive ('foo' is a different destination than 'Foo').

# create a Named Destination 'foo' 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 'fits' can be defined
$dest->goto($page, 'xyz', (undef, undef, undef));
$pdf->named_destination('Dests', 'foo', $dest);

See "named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs for information on named destinations.

METHODS

new

$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.

Target Destinations

Note that the usual practice for a Named Destination, invoked when the PDF is opened with a Named Destination specified, is to goto a point in the document. It is possible, though unusual, to go to a point in another document (pdf()), launch a local application (launch()), or launch a web browser (uri()).

The only "options" supported for goto and pdf 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's "action" methods (goto, pdf, uri, and launch), there is no defining a "click area" (button) for the user interaction; thus, no rect, border, or color entries are recognized in NamedDestination. Any found will be ignored.

See "Page Fit Options" in PDF::Builder::Docs for a listing of the available locations and their syntax.

"xyz" is the default fit setting, with position (left and top) and zoom all the same as the calling page's.

$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").

pdf, pdf_file, pdfile

$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.

uri, url

$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.

launch, file

$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.