# -*- encoding: utf-8; frozen_string_literal: true -*-
#
#--
# This file is part of HexaPDF.
#
# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
# Copyright (C) 2014-2025 Thomas Leitner
#
# HexaPDF is free software: you can redistribute it and/or modify it
# under the terms of the GNU Affero General Public License version 3 as
# published by the Free Software Foundation with the addition of the
# following permission added to Section 15 as permitted in Section 7(a):
# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
# INFRINGEMENT OF THIRD PARTY RIGHTS.
#
# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
# License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
#
# The interactive user interfaces in modified source and object code
# versions of HexaPDF must display Appropriate Legal Notices, as required
# under Section 5 of the GNU Affero General Public License version 3.
#
# In accordance with Section 7(b) of the GNU Affero General Public
# License, a covered work must retain the producer line in every PDF that
# is created or manipulated using HexaPDF.
#
# If the GNU Affero General Public License doesn't fit your need,
# commercial licenses are available at <https://gettalong.at/hexapdf/>.
#++
require 'hexapdf/dictionary'
require 'hexapdf/error'
module HexaPDF
module Type
# 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: PDF2.0 s7.7.3.2, Page
class PageTreeNode < Dictionary
define_type :Pages
define_field :Type, type: Symbol, required: true, default: type
define_field :Parent, type: Dictionary, indirect: true
define_field :Kids, type: PDFArray, required: true, default: []
define_field :Count, type: Integer, required: true, default: 0
# Inheritable page fields
define_field :Resources, type: :XXResources
define_field :MediaBox, type: Rectangle
define_field :CropBox, type: Rectangle
define_field :Rotate, type: Integer
# Returns +true+ since page tree objects must always be indirect.
def must_be_indirect?
true
end
# 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!
def page_count
self[:Count]
end
# 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.
def page(index)
index = self[:Count] + index if index < 0
return nil if index < 0 || index >= self[:Count]
self[:Kids].each do |kid|
if kid.type == :Page
if index == 0
return kid
else
index -= 1
end
elsif index < kid[:Count]
return kid.page(index)
else
index -= kid[:Count]
end
end
end
# 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.
def insert_page(index, page = nil)
page ||= new_page
index = self[:Count] + index + 1 if index < 0
if index >= self[:Count]
self[:Kids] << page
page[:Parent] = self
page[:Resources] ||= {}
else
self[:Kids].each_with_index do |kid, kid_index|
if index == 0
self[:Kids].insert(kid_index, page)
page[:Parent] = self
break
elsif kid.type == :Page
index -= 1
elsif index <= kid[:Count]
kid.insert_page(index, page)
break
else
index -= kid[:Count]
end
end
end
self[:Count] += 1
page
end
# Adds the page or a new empty page at the end and returns it.
#
# See: #insert_page
def add_page(page = nil)
insert_page(-1, page)
end
# :call-seq:
# pages.delete_page(page)
# pages.delete_page(index)
#
# Deletes the given page or the page at the position specified by the zero-based index from
# the page tree and the document.
#
# Negative indices count backwards from the end, i.e. -1 is the last page.
def delete_page(page)
page = self.page(page) if page.kind_of?(Integer)
return unless page && !page.null? && page[:Parent]
parent = page[:Parent]
index = parent[:Kids].index(page)
if index
ancestors = page.ancestor_nodes
return nil unless ancestors.include?(self)
page[:Parent][:Kids].delete_at(index)
page.delete(:Parent)
document.delete(page)
ancestors.each {|node| node[:Count] -= 1 }
else
raise HexaPDF::Error, "Given page not found in page tree"
end
end
# :call-seq:
# pages.move_page(page, to_index)
# pages.move_page(index, to_index)
#
# Moves the given page or the page at the position specified by the zero-based index to the
# +to_index+ position.
#
# If the page that should be moved, doesn't exist or is invalid, an error is raised.
#
# Negative indices count backwards from the end, i.e. -1 is the last page. When using a
# negative index, the page will be moved after that element. So using an index of -1 will
# move the page after the last page.
def move_page(page, to_index)
page = self.page(page) if page.kind_of?(Integer)
if page.nil? || page.null? || !page[:Parent] ||
!(ancestors = page.ancestor_nodes).include?(self)
raise HexaPDF::Error, "The page to be moved doesn't exist in this page tree"
end
parent = page[:Parent]
prev_index = page.index
prev_kid_index = parent[:Kids].index(page)
if to_index < 0
to_index = self[:Count] + to_index + 1
elsif prev_index < to_index
to_index += 1
end
insert_page(to_index, page)
ancestors.each {|node| node[:Count] -= 1 }
if page[:Parent] == parent
if prev_index < to_index
parent[:Kids].delete_at(prev_kid_index)
else
parent[:Kids].delete_at(prev_kid_index + 1)
end
else
parent[:Kids].delete(page)
end
end
# :call-seq:
# pages.each_page {|page| block } -> pages
# pages.each_page -> Enumerator
#
# Iterates over all pages that are beneath this page tree node, from the first to the last
# page.
def each_page(&block)
return to_enum(__method__) unless block_given?
self[:Kids].each do |kid|
if kid.type == :Page
yield(kid)
else
kid.each_page(&block)
end
end
self
end
private
# Returns a new page object, correctly initialized using the document's configuration options.
def new_page
box = config['page.default_media_box']
if box.kind_of?(Symbol)
box = Page.media_box(box, orientation: config['page.default_media_orientation'])
end
document.add({Type: :Page, MediaBox: box})
end
# Ensures that the /Count and /Parent fields of the whole page tree are set up correctly and
# that there is at least one page node. This is therefore only done for the root node of the
# page tree!
def perform_validation(&block)
super
return unless document.catalog[:Pages] == self
validate_node = lambda do |node|
count = 0
node[:Kids].reject! do |kid|
if !kid.kind_of?(HexaPDF::Object) || kid.null? ||
(kid.type != :Page && kid.type != :Pages)
yield("Invalid object in page tree node", true)
next true
elsif kid.type == :Page
count += 1
else
count += validate_node.call(kid)
end
if kid[:Parent] != node
yield("Field Parent of page tree node (#{kid.oid},#{kid.gen}) is invalid", true)
kid[:Parent] = node
end
false
end
if node[:Count] != count
yield("Field Count of page tree node (#{node.oid},#{node.gen}) is invalid", true)
node[:Count] = count
end
count
end
validate_node.call(self)
if self[:Count] == 0
yield("A PDF document needs at least one page", true)
add_page.validate(&block)
end
end
end
end
end