class HexaPDF::Type::PageTreeNode


Represents a node in the page tree of the PDF's document.

The page tree is a tree structure containing page tree nodes for the root and intermediate nodes and page objects for the leaf nodes (see Page). The root node of the page tree is linked via the /Pages entry in the Catalog.

All operations except add_page on the page tree are rather expensive because page tree nodes and page objects can be mixed. This means that for finding a page at a specific index we have to go through all objects that come before it.

Page indices are zero-based, not one-based. Therefore the first page has an index of 0!

Since the page tree needs a certain structure it is not advised to directly modify page tree nodes. The validation feature can correct most problems but until the page tree is in order the methods may not work correctly!

Newly created pages use the 'page.default_media_box' configuration option for the /MediaBox value. If an inherited /Resources dictionary does not exist, an empty one is created for the page.

See: PDF1.7 s7.7.3.2, Page

Public Instance Methods

add_page(page = nil)

Adds the page or a new empty page at the end and returns it.

See: insert_page

delete_page(page) → page or nil
delete_page(index) → page or nil

Deletes the given page or the page at the position specified by the zero-based index from the page tree and returns the deleted page object. If the page was not deleted, nil is returned.

Note that the page is not deleted from the document itself, only from the page tree! This also means that the /Parent entry of the page is set to nil if deleted.

Negative indices count backwards from the end, i.e. -1 is the last page.

each_page {|page| block } → pages
each_page → Enumerator

Iterates over all pages that are beneath this page tree node, from the first to the last page.

insert_page(index, page = nil)

Inserts the page or a new empty page at the zero-based index and returns it.

Negative indices count backwards from the end, i.e. -1 is the last page. When using negative indices, the page will be inserted after that element. So using an index of -1 will insert the page after the last page.

Must be called on the root of the page tree, otherwise the /Count entries are not correctly updated!

If an existing page is inserted, it may be necessary to use Page#copy_inherited_values before insertion so that the page dictionary contains all necessary information.


Returns true since page tree objects must always be indirect.


Returns the page for the zero-based index or nil if no such page exists.

Negative indices count backwards from the end, i.e. -1 is the last page.


Returns the number of pages under this page tree.

Note: If this methods is not called on the root object of the page tree, the returned number is not the total number of pages in the document!