PDF::API2::Outline(3)

💖 PDF::API2::Outline 💖

okay bestie, so this is the PDF::API2::Outline page from the Perl docs — the one and only place to manage PDF outlines (which, for the uninitiated, are literally just bookmarks, the little sidebar tree of links in a PDF reader 💅). no cap, this module is the whole personality of your PDF's navigation.

---

✨ SYNOPSIS ✨

here's the vibe, straight up:

# Get/create the top-level outline tree
my $outline = $pdf->outline();

# Add an entry
my $item = $outline->outline();
$item->title('First Page');
$item->destination($pdf->open_page(1));

so you grab the top-level outline tree with $pdf->outline(), then you keep calling ->outline() on it to add entries like it's a little nesting-doll situation 🪆, and you set a title and a destination and boom. bookmark. iconic.

---

🦋 METHODS 🦋

🌸 Examine the Outline Tree 🌸

basically the "let me look at it" era of methods. no touching, just observing 👀

• has_children

my $boolean = $outline->has_children();

returns true if the outline item you're on has child items. like, does it have its own little family. does it have lore.

• count

my $integer = $outline->count();

returns the number of descendants that are visible when the current outline item is open (expanded). so when it's unfolded, this is how many little ones you can see.

• first

my $child = $outline->first();

returns the first child of the current outline level, if one exists. if there's no child, well. nothing. moving on.

• last

my $child = $outline->last();

returns the last child of the current outline level, if one exists. the final girl of the sibling lineup 😭

• parent

my $parent = $outline->parent();

returns the parent of the current item — but only if you're not at the top level of the outline tree. top level? no parent. you're the parent. main character energy 👑

• prev

my $sibling = $outline->prev();

returns the previous item at the current level of the outline tree.

• next

my $sibling = $outline->next();

returns the next item at the current level of the outline tree.

---

💜 Modify the Outline Tree 💜

now we're building. this is the construction era 🏗️✨

• outline

my $child = $outline->outline();

adds an outline item at the end of the current outline's list of children. appending. no queue-jumping.

• insert_after

my $sibling = $outline->insert_after();

adds an outline item immediately following the current item. sneaky little guy, sliding in right behind you.

• insert_before

$sibling = $outline->insert_before();

adds an outline item immediately preceding the current item. cutting the line, but politely.

• delete

$outline->delete();

removes the current outline item from the outline tree.

⚠️ heads up bestie: if the item has any children, they get effectively deleted too, since they'll no longer be linked. not a drill. the whole little family goes 💀

• is_open

# Get
my $boolean = $outline->is_open();

# Set
my $outline = $outline->is_open($boolean);

get/set whether the outline is expanded or collapsed. open or closed. unfolded or folded. the toggle of it all.

---

🎀 Set Outline Attributes 🎀

the glow-up section. let's make it cute ✨

• title

# Get
my $title = $outline->title();

# Set
$outline = $outline->title($text);

get/set the title of the outline item. the name on the label. the whole identity.

• destination

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

sets the destination page and the optional position of the outline. $location and @args work exactly as defined in "destination" in PDF::API2::NamedDestination — go read that page, iykyk.

also, $destination can optionally just be the name of a named destination defined somewhere else. flexible queen.

• uri

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

launches a URI — typically a web page — when the outline item is activated. click the bookmark, go to the internet. slay.

• launch

$outline->launch($file);

launches an application or file when the outline item is activated. yes, it really just opens a thing. careful with that one 🙈

• pdf

$outline = $outline->pdf($filename, $page_number, $location, @args);

opens another PDF file to a particular page number. heads up: the first page is zero, and that's also the default, because zero-indexing is just how it is here.

the page can optionally be positioned at a particular location if $location and @args are set — see "destination" in PDF::API2::NamedDestination for all the possible settings. same rules, different file 💫

---

that's the whole page, bestie 🫶 go forth and build the most organized bookmark tree anyone has ever seen. no notes.

---

perl v5.42.0 · 2025-09-01 — that's the version and date from the bottom of the page, mwah 💋