PDF::AP...tination(3)

💖 PDF::API2::NamedDestination — the manual page, but make it cute 💖

okay bestie, gather round 🫶 this is the PDF::API2::NamedDestination page from the User Contributed Perl Documentation, section 3. It's the module that lets you drop named destinations (aka saved views) into a PDF, so your readers can jump straight to the good part instead of doom-scrolling page 47. iconic behaviour, honestly.

---

✨ NAME ✨

PDF::API2::NamedDestination — Add named destinations (views) to a PDF 💅

---

🎀 METHODS 🎀

🌸 new

$destination = PDF::API2::NamedDestination->new($pdf, ...);

Creates a brand-new named destination object, slay. And if you pass any extra arguments after that? They get handed straight off to destination(). no notes. ✨

---

🦋 destination

$destination = $destination->destination($page, $location, @args);

So a destination is basically one specific view of a PDF — it's a page object + where the window sits on that page + possibly some coordinate and zoom args. the full trio, okay?

# The XYZ location takes three arguments
my $dest1 = PDF::API2::NamedDestination->new($pdf);
$dest->destination($pdf->open_page(1), 'xyz' => ($x, $y, $zoom));

# The Fit location doesn't require any arguments
my $dest2 = PDF::API2::NamedDestination->new($pdf);
$dest->destination($pdf->open_page(2), 'fit');

Here's every location you can pick from, bestie 👇

• xyz ($left, $top, $zoom) — shows the page with the coordinates ($left, $top) parked at the upper-left corner of the window, and the page contents magnified by the factor $zoom. If any of those args is undef, that means the current value of that argument gets kept exactly as it is, unchanged. And a zoom factor of 0? Same meaning as undef. periodt. 💅
• fit — shows the page with its contents magnified just enough to fit the entire page inside the window, both horizontally and vertically. If the horizontal and vertical magnification factors you'd need are different, it uses the smaller of the two and centers the page within the window in the other dimension. math queen behaviour 🧚
• fith ($top) — shows the page with the vertical coordinate $top positioned at the top edge of the window, contents magnified just enough to fit the entire width of the page within the window. An undef for $top means that argument's current value stays retained, unchanged. 🫶
• fitv ($left) — shows the page with the horizontal coordinate $left positioned at the left edge of the window, contents magnified just enough to fit the entire height of the page within the window. An undef for $left means the current value of that argument is retained unchanged. ✨
• fitr ($left, $bottom, $right, $top) — shows the page with its contents magnified just enough to fit the rectangle defined by $left, $bottom, $right and $top entirely within the window, both horizontally and vertically. If the required horizontal and vertical magnification factors differ, it takes the smaller one and centers the rectangle within the window in the other dimension. 🔥
• fitb — shows 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 differ, use the smaller of the two, centering the bounding box within the window in the other dimension. 👑
• fitbh ($top) — shows the page with the vertical coordinate $top at the top edge of the window, contents magnified just enough to fit the entire width of its bounding box within the window. An undef for $top means the current value of that argument shall be retained unchanged. 💜
• fitbv ($left) — shows the page with the horizontal coordinate $left at the left edge of the window, contents magnified just enough to fit the entire height of its bounding box within the window. An undef for $left means the current value of that argument shall be retained unchanged. 🌈

---

🌟 goto

$destination = $destination->goto($page, $location, @args);

A go-to action switches the view over to a specified destination — that's page, location, and magnification factor, the whole little bundle. 🎀

The parameters? Exactly as described in "destination". no cap.

---

🍓 uri

$destination = $destination->uri($uri);

A URI action means a URI — typically a web page — should be launched. it's giving "click here and go somewhere else entirely" 🌐✨

---

💀 launch

$destination = $destination->launch($file);

A launch action runs an application, or opens or prints a document. very main character of it.

$file holds the path to the application to be launched, or the document to be opened or printed. 🫶

---

🧚 pdf

$destination = $destination->pdf($file, $page_number, $location, @args);

Basically goto's cousin, except the destination lives in a different PDF file, located at $file. Heads up: $page_number here is an integer, not a page object (different vibe, same energy), and all the other parameters are as described in "destination". 💖

---

💖 that's the whole page bestie, every method, every location, every undef caveat, nothing skipped 💖

This one came to you courtesy of the User Contributed Perl Documentation, generated by perl v5.42.0 on 2025-09-01. mwah, go make some gorgeous PDFs 💅✨🎀