---
name: "PDF::Builder::Outline"
section: "3pm"
platform: "linux"
package: "perl-pdf-builder"
version: "3.028-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/PDF::Builder::Outline"
---

# PDF::Builder::Outline(3pm)

Manage PDF outlines (a.k.a. bookmarks) Inherits from PDF::Builder::Basic::PDF::Dict

## NAME

PDF::Builder::Outline - Manage PDF outlines (a.k.a. bookmarks)

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

## SYNOPSIS

```
    # Get/create the top-level outline tree
    my $outlines = $pdf->outline();
    # Add an entry
    my $item = $outlines->outline();
    $item->title('First Page');
    $item->dest($pdf->open_page(1), fit-def);
```

## METHODS

### new

```
    $outline = PDF::Builder::Outline->new($api, $parent)
    $outline = PDF::Builder::Outline->new($api)
```

Returns a new outline object (called from `$outlines`-\>**outline()**).

By default, if `$parent` is omitted, the new bookmark is placed at the end of any existing list of bookmarks. Otherwise, it becomes the child of the `$parent` bookmark.

### Examine the Outline Tree

*has\_children*

```
    $boolean = $outline->has_children()
```

Return true if the current outline item has children (child items).

*count*

```
    $integer = $outline->count()
```

Return the number of descendants that are visible when the current outline item is open (expanded).

*first*

```
    $child = $outline->first()
```

Return the first child of the current outline level, if one exists.

*last*

```
    $child = $outline->last()
```

Return the last child of the current outline level, if one exists.

*parent*

```
    $parent = $outline->parent()
```

Return the parent of the current item, if not at the top level of the outline tree.

*prev*

```
    $sibling = $outline->prev() # Get
    $sibling = $outline->prev(outline_obj) # Set
```

Return the previous item of the current level of the outline tree  (`"undef"` if already at the first item).

*next*

```
    $sibling = $outline->next() # Get
    $sibling = $outline->next(outline_obj) # Set
```

Return the next item of the current level of the outline tree  (`"undef"` if already at the last item).

### Modify the Outline Tree

*outline*

```
    $child_outline = $parent_outline->outline()
```

Returns a new sub-outline (nested outline) added at the end of the `$parent_outline`'s children. If there are no existing children, create the first one.

*insert\_after*

```
    $sibling = $outline->insert_after()
```

Add an outline item immediately following the `$outline` item.

*insert\_before*

```
    $sibling = $outline->insert_before()
```

Add an outline item immediately preceding the `$outline` item.

*delete*

```
    $outline->delete()
```

Remove the current outline item from the outline tree. If the item has any children, they will effectively be deleted as well, since they will no longer  be linked.

*is\_open*

```
    $boolean = $outline->is_open() # Get
    $outline = $outline->is_open($boolean) # Set
```

Get/set whether the outline is expanded (open) or collapsed (closed). `$boolean` is 0/false to close (collapse) the outline (hide its children), or 1/true to open (expand) it (make its children visible).

*open*

```
    $outline->open()
```

Set the status of the outline to open (i.e., expanded).

This is an **alternate** method to using is\_open(true).

*closed*

```
    $outline->closed()
```

Set the status of the outline to closed (i.e., collapsed).

This is an **alternate** method to using is\_open(false).

### Set Outline Attributes

*title*

```
    $title = $outline->title() # Get
    $outline = $outline->title($text) # Set
```

Get/set the title of the outline item.

*dest*

```
    $outline->dest($page_object, %position)
    $outline->dest($page_object)
```

Sets the destination page and optional position of the outline.

`%position` can be any of those listed in "Page Fit Options" in PDF::Builder::Docs.

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

```
    $outline->dest($name, %position)
    $outline->dest($name)
```

Connect the Outline to a "Named Destination" defined elsewhere, and optional positioning as described above.

Note that PDF::Builder's `dest()` is **not** the same (i.e., an alias) as PDF::API2's `destination()`. The argument lists are quite different.

### Destination targets

*uri, url*

```
    $outline->uri($url)
```

Defines the outline as launch-url with url `$url`, typically a web page.

**Alternate name:** `"url"`

Either `"uri"` or `"url"` may be used; `"uri"` is for compatibility with PDF::API2.

*launch, file*

```
    $outline->launch($file)
```

Defines the outline as launch-file with filepath `$file`. This is typically a local application or file.

**Alternate name:** `"file"`

Either `"launch"` or `"file"` may be used; `"launch"` is for compatibility with PDF::API2.

*pdf, pdf\_file, pdfile*

```
    $outline->pdf($pdffile, $page_number, %position, %args)
    $outline->pdf($pdffile, $page_number)
```

Defines the destination of the outline as a PDF-file with filepath  `$pdffile`, on page `$pagenum` (default 0), and position `%position`  (same as **dest()**).

**Alternate names:** `"pdf_file"` and `"pdfile"`

Either `"pdf"` or `"pdf_file"` (or the older `"pdfile"`) may be used; `"pdf"` is  for compatibility with PDF::API2.