PDF::AP...notation(3)

✨ NAME ✨

PDF::API2::Annotation — the part of PDF::API2 that lets you slap annotations onto a PDF 💅 (yes bestie, that's the whole vibe of this page, and it's from the User Contributed Perl Documentation corner of the universe 🫶)

---

🌸 SYNOPSIS 🌸

Okay so here's the whole lil ritual, look:

my $pdf = PDF::API2->new();
my $font = $pdf->font('Helvetica');
my $page1 = $pdf->page();
my $page2 = $pdf->page();

my $content = $page1->text();
my $message = 'Go to Page 2';
my $size = 18;
$content->distance(1 * 72, 9 * 72);
$content->font($font, $size);
$content->text($message);

my $annotation = $page1->annotation();
my $width = $content->text_width($message);
$annotation->rect(1 * 72, 9 * 72, 1 * 72 + $width, 9 * 72 + $size);
$annotation->link($page2);

$pdf->save('sample.pdf');

That's you making a page, writing "Go to Page 2" on it, drawing a rectangle around that text, and turning the rectangle into a link to page 2. Iconic. Clickable. Slay 💖

---

👑 METHODS 👑

🎀 Annotation Types

Pick your fighter. Each of these turns your annotation into a specific kind of annotation, and honestly each one is giving main character energy:

🦋 link

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

Links the annotation to another page in this same PDF. 💫

$location and @args are optional, and they control which part of the page actually gets shown — exactly as defined in "destination" in PDF::API2::NamedDestination (iykyk, go read that one too).

$destination can be either a PDF::API2::Page object, or the name of a named destination that's been defined somewhere else. Either way, you're good. 🫶

🍓 url

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

Launches $uri — usually a web page — the moment the annotation gets selected. Click it, browser go brrr 🌈

🧚 file

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

Opens $file when the annotation is selected. Local file bestie, come through 💜

💀 pdf

$annotation = $annotation->pdf($file, $dest, $location, @args);

Opens the PDF file sitting at $file, jumping straight to the specified destination. Nested PDFs, we love to see it.

$location and @args are optional, and they set which part of the page gets displayed, as defined in "destination" in PDF::API2::NamedDestination.

$dest can be a page number, or a named destination prefixed with "#". Don't forget that hash, bestie, fr fr. 🙈

✨ text

$annotation = $annotation->text($text);

Defines the annotation as a text note with the content you specify. Lil sticky note behavior 📝

🎬 movie

$annotation = $annotation->movie($filename, $content_type);

Embeds the movie at $filename and links to it, with the MIME type you pass as $content_type. Cinema. 🍿

---

💅 Common Annotation Attributes

These ones are the shared settings — every annotation type can use them, so learn them once and you're set forever.

🔲 rect

$annotation = $annotation->rect($llx, $lly, $urx, $ury);

Defines the rectangle around the annotation. Lower-left x, lower-left y, upper-right x, upper-right y — that's the whole shape of it. 📐

🎀 border

$annotation = $annotation->border($h_radius, $v_radius, $width);

Defines the border style. Defaults to 0, 0, 0 — which means no border at all, so if you want one you gotta say so.

📝 content

$annotation = $annotation->content(@lines);

Defines the text content of the annotation — if applicable, so don't come for me if your annotation type doesn't have a body, bestie 😭

🚪 open

$annotation = $annotation->open($boolean);

Sets whether the annotation starts out open or closed. Heads up: this is only relevant for text annotations, so don't try it on the other types. ⭐

---

Lowkey important: this is a User Contributed Perl Documentation page, so it's the community doing the lord's work, not some faceless corpo. Treat it with respect 🫶

---

k bye bestie, go annotate something gorgeous 💖 This page came to you courtesy of perl v5.42.0, dated 2025-09-01 — and PDF::AP...notation(3) is absolutely the name, no cap. Mwah 💋