This class provides methods for managing the pages and page labels of a PDF file.
For page manipulation it uses the methods of
HexaPDF::Type::PageTreeNode underneath but provides a more convenient interface.
In addition to page manipulation, the class provides methods for managing the page labels which are alternative descriptions for the pages. In contrast to the page indices which are fixed the page labels can be freely defined.
The way this works is that one can assign page label objects (
HexaPDF::Type::PageLabel) to page ranges via the /PageLabels number tree in the catalog. The page label objects specify how the pages in their range shall be labeled. See
HexaPDF::Type::PageLabel for examples of page labels.
To facilitate the easy use of page labels the following methods are provided:
Public Class Methods
Public Instance Methods
Appends the given page at the end and returns the pages object itself to allow chaining.
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.
Adds the given page or a new empty page at the end and returns it.
If called with a page object as argument, that page object is used. Otherwise
create is called with the arguments
orientation to create a new page.
Adds a new labelling range starting at
start_index and returns it.
HexaPDF::Type::PageLabel for information on the arguments
If a labelling range already exists for the given
start_index, its value will be overwritten.
If there are no existing labelling ranges and the given
start_index isn’t 0, a default labelling range using start index 0 and numbering style :decimal is added.
Returns the number of pages in the PDF document. May be zero if the document has no pages yet.
Creates a page object and returns it without adding it to the page tree.
If this argument is
nil/not specified, the value is taken from the configuration option ‘page.default_media_box’.
If the resulting value is an array with four numbers (specifying the media box), the new page will have these exact dimensions.
If the value is a symbol, it is taken as a reference to a pre-defined media box in HexaPDF::Type::Page::PAPER_SIZE. The
orientationcan then be used to specify the page orientation.
If this argument is not specified, it is taken from ‘page.default_media_orientation’. It is only used if
media_boxis a symbol and not an array.
Deletes the given page object from the document’s page tree and the document.
Deletes the page object at the given index from the document’s page tree and the document.
Deletes the page labelling range starting at
start_index and returns the associated page label object.
Note: The page label for the range starting at zero can only be deleted last!
Iterates over all defined labelling ranges inorder, yielding the page index of the first page in the labelling range, the number of pages in the range, and the associated page label object.
The last yielded count might be equal or lower than zero in case the document has fewer pages than anticipated by the labelling ranges.
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.
Moves the given page or the page at the position specified by the zero-based index to the
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.
Returns the constructed page label for the given page index.
If no page labels are defined,
nil is returned.
HexaPDF::Type::PageLabel for examples.