CTS logo
hazy blue Catskill Mountains in distance


Online documentation and examples output are now available for our products

A Thought…

One thing that humbles me deeply is to see that human genius has its limits while human stupidity does not.

   — Alexandre Dumas


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


    # 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);


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

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

Examine the Outline Tree

$boolean = $outline->has_children()

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

$integer = $outline->count()

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

$child = $outline->first()

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

$child = $outline->last()

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

$parent = $outline->parent()

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

$sibling = $outline->prev()

Return the previous item of the current level of the outline tree.

$sibling = $outline->next()

Return the next item of the current level of the outline tree.

Modify the Outline Tree

$child_outline = $parent_outline->outline()

Returns a new sub-outline (nested outline) added at the end of the current outline's children.

$sibling = $outline->insert_after()

Add an outline item immediately following the current item.

$sibling = $outline->insert_before()

Add an outline item immediately preceding the current item.


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.

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

Get/set whether the outline is expanded (open) or collapsed (closed).


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

This is an alternate method to using is_open(true).


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 = $outline->title() # Get
$outline = $outline->title($text) # Set

Get/set the title of the outline item.

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

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)

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

Destination targets


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.


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.

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


Up (Parents)

Master Index 
PDF::Builder -- Facilitates the creation and modification of PDF files


PDF::Builder::Annotation -- Add annotations to a PDF
PDF::Builder::Basic::PDF -- Various utilities and support routines
PDF::Builder::Content -- Methods for adding graphics and text to a PDF
PDF::Builder::Docs -- additional documentation for Builder module
PDF::Builder::FontManager -- Managing the font library for PDF::Builder
PDF::Builder::Lite -- Lightweight PDF creation methods
PDF::Builder::Matrix -- matrix operations library
PDF::Builder::NamedDestination -- Add named destinations (views) to a PDF
PDF::Builder::Outlines -- further Outline handling. Inherits from PDF::Builder::Outline
PDF::Builder::Page -- Methods to interact with individual pages
PDF::Builder::Resource -- Base class for PDF resources. Inherit from PDF::Builder::Basic::PDF::Dict
PDF::Builder::UniWrap -- support routines for finding line breakpoints with Unicode text
PDF::Builder::Util -- utility package for often-used methods across the package.
PDF::Builder::ViewerPreferences -- How the PDF should be displayed or printed


All content © copyright 2005 – 2023 by Catskill Technology Services, LLC.
All rights reserved.
Note that Third Party software (whether Open Source or proprietary) on this site remains under the copyright and license of its owners. Catskill Technology Services, LLC does not claim copyright over such software.


This page is https://www.catskilltech.com/Documentation/PDF/Builder/Outline.html

Search Quotations database.

Last updated Wed, 08 Nov 2023 at 10:46 PM

Valid HTML 5

Wed, 29 Nov 2023 at 11:32 PM EST