CTS logo
hazy blue Catskill Mountains in distance


A Thought…

A foreign businessman goes to Russia on behalf of a large company, looking to build a factory. He contacts several construction companies to get quotes.

The Germans tell him that they can build the plant with top of the line materials and engineering for 2 million euros.

The Turks tell him they can build the plant cheap, for only 1 million euros — but quality will obviously suffer.

Then along comes a Russian contractor. He tells the businessman that he has the best solution! Pay him 3 million. He will hire the Turks to build the plant for 1 mil, and he and the rep each get 1 mil for themselves!

   — AndreiROM, worldbuilding.stackexchange.com


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

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


    # 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

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

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


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


All content © copyright 2005 – 2024 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 Sat, 09 Dec 2023 at 10:59 PM

Valid HTML 5

Thu, 18 Apr 2024 at 10:04 AM EDT