Class: HexaPDF::Type::PageTreeNode

Inherits:
Dictionary show all
Defined in:
lib/hexapdf/type/page_tree_node.rb

Overview

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

Constant Summary

Constants included from DictionaryFields

DictionaryFields::Boolean, DictionaryFields::PDFByteString, DictionaryFields::PDFDate

Constants inherited from Object

Object::NOT_DUPLICATABLE_CLASSES

Instance Attribute Summary

Attributes inherited from Object

#data, #document, #must_be_indirect

Instance Method Summary collapse

Methods inherited from Dictionary

#[], #[]=, define_field, define_type, #delete, #each, each_field, #empty?, field, #key?, #to_h, type, #type

Methods inherited from Object

#<=>, #==, #deep_copy, deep_copy, #document?, #eql?, #gen, #gen=, #hash, #indirect?, #initialize, #inspect, #null?, #oid, #oid=, #type, #validate, #value, #value=

Constructor Details

This class inherits a constructor from HexaPDF::Object

Instance Method Details

#add_page(page = nil) ⇒ Object

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

See: #insert_page



156
157
158
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 156

def add_page(page = nil)
  insert_page(-1, page)
end

#delete_page(page) ⇒ Object

:call-seq:

pages.delete_page(page)        -> page or nil
pages.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.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 172

def delete_page(page)
  page = self.page(page) if page.kind_of?(Integer)
  return nil unless page && page[:Parent]

  parent = page[:Parent]
  index = parent[:Kids].index {|kid| document.deref(kid).data == page.data }

  if index
    ancestors = [parent]
    ancestors << parent while (parent = parent[:Parent])
    return nil unless ancestors.include?(self)

    page[:Parent][:Kids].delete_at(index)
    page.delete(:Parent)
    ancestors.each {|node| node[:Count] -= 1 }
    page
  else
    nil
  end
end

#each_page(&block) ⇒ Object

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



199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 199

def each_page(&block)
  return to_enum(__method__) unless block_given?

  self[:Kids].each do |kid|
    kid = document.deref(kid)
    if kid.type == :Page
      yield(kid)
    else
      kid.each_page(&block)
    end
  end

  self
end

#insert_page(index, page = nil) ⇒ Object

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.



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 122

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|
      kid = document.deref(kid)
      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

#must_be_indirect? ⇒ Boolean

Returns true since page tree objects must always be indirect.

Returns:



76
77
78
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 76

def must_be_indirect?
  true
end

#page(index) ⇒ Object

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.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 91

def page(index)
  index = self[:Count] + index if index < 0
  return nil if index < 0 || index >= self[:Count]

  self[:Kids].each do |kid|
    kid = document.deref(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

#page_count ⇒ Object

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!



84
85
86
 
# File 'lib/hexapdf/type/page_tree_node.rb', line 84

def page_count
  self[:Count]
end