A Thought…

[Life] isn’t a boat or a roller coaster. It’s a train without a timetable or conductor, with occasional shunts to sidings for reflection, then on to the the only terminal.

— sandpiper, Non Sequitur comic letters

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.

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

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

Up (Parents)

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

Siblings

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 (UNMAINTAINED)
PDF::Builder::Matrix -- Matrix operations library
PDF::Builder::NamedDestination -- Add named destinations (views) to a PDF
PDF::Builder::Outlines -- Further Outline handling
PDF::Builder::Page -- Methods to interact with individual pages
PDF::Builder::Resource -- Base class for PDF resources
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

News: