.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Basic::PDF::Pages 3pm"
.TH PDF::Builder::Basic::PDF::Pages 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder::Basic::PDF::Pages \- a PDF pages hierarchical element. 
Inherits from PDF::Builder::Basic::PDF::Dict
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Pages object is the parent to other pages objects or to page objects
themselves.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "PDF::Builder::Basic::PDF::Pages\->new($pdf, $parent)"
.el .SS "PDF::Builder::Basic::PDF::Pages\->new($pdf, \f(CW$parent\fP)"
.IX Subsection "PDF::Builder::Basic::PDF::Pages->new($pdf, $parent)"
This creates a new Pages object in a \s-1PDF.\s0 Notice that the \f(CW$parent\fR here is 
not the file context for the object, but the parent pages object for these 
pages. If we are using this class to create a root node, \f(CW$parent\fR should 
point to the file context, which is identified by \fInot\fR having a Type of 
\&\fIPages\fR. \f(CW$pdf\fR is the file object (or a reference to an array of \fIone\fR 
file object [3.016 and later, or multiple file objects earlier]) in which to 
create the new Pages object.
.ie n .SS "$p\->find_page($page_number)"
.el .SS "\f(CW$p\fP\->find_page($page_number)"
.IX Subsection "$p->find_page($page_number)"
Returns the given page, using the page count values in the pages tree. Pages
start at 0.
.ie n .SS "$p\->add_page($page, $page_number)"
.el .SS "\f(CW$p\fP\->add_page($page, \f(CW$page_number\fP)"
.IX Subsection "$p->add_page($page, $page_number)"
Inserts the page before the given \f(CW$page_number\fR. \f(CW$page_number\fR can be 
negative to count backwards from the \s-1END\s0 of the document. \-1 is after the last 
page. Likewise \f(CW$page_number\fR can be greater than the number of pages 
currently in the document, to append.
.PP
This method only guarantees to provide a reasonable pages tree if pages are
appended or prepended to the document. Pages inserted in the middle of the
document may simply be inserted in the appropriate leaf in the pages tree 
without adding any new branches or leaves, leaving it unbalanced (slower
performance, but still usable).
.ie n .SS "@objects = $p\->\fBget_pages()\fP"
.el .SS "\f(CW@objects\fP = \f(CW$p\fP\->\fBget_pages()\fP"
.IX Subsection "@objects = $p->get_pages()"
Returns a list of page objects in the document, in page order.
.ie n .SS "$p\->find_prop($key)"
.el .SS "\f(CW$p\fP\->find_prop($key)"
.IX Subsection "$p->find_prop($key)"
Searches up through the inheritance tree to find a property (key).
.ie n .SS "$p\->add_font($pdf, $font)"
.el .SS "\f(CW$p\fP\->add_font($pdf, \f(CW$font\fP)"
.IX Subsection "$p->add_font($pdf, $font)"
Creates or edits the resource dictionary at this level in the hierarchy. If
the font is already supported, even through the hierarchy, then it is not added.
.PP
\&\fB\s-1CAUTION:\s0\fR if this method was used in older releases, the code may have 
swapped the order of \f(CW$pdf\fR and \f(CW$font\fR, requiring ad hoc swapping of 
parameters in user code, contrary to the \s-1POD\s0 definition above. Now the code
matches the documentation.
.ie n .SS "$p\->bbox($xmin,$ymin, $xmax,$ymax, $param)"
.el .SS "\f(CW$p\fP\->bbox($xmin,$ymin, \f(CW$xmax\fP,$ymax, \f(CW$param\fP)"
.IX Subsection "$p->bbox($xmin,$ymin, $xmax,$ymax, $param)"
.ie n .SS "$p\->bbox($xmin,$ymin, $xmax,$ymax)"
.el .SS "\f(CW$p\fP\->bbox($xmin,$ymin, \f(CW$xmax\fP,$ymax)"
.IX Subsection "$p->bbox($xmin,$ymin, $xmax,$ymax)"
Specifies the bounding box for this and all child pages. If the values are
identical to those inherited, no change is made. \f(CW$param\fR specifies the 
attribute name so that other 'bounding box'es can be set with this method.
.ie n .SS "$p\->proc_set(@entries)"
.el .SS "\f(CW$p\fP\->proc_set(@entries)"
.IX Subsection "$p->proc_set(@entries)"
Ensures that the current resource contains all the entries in the proc_sets
listed. If necessary, it creates a local resource dictionary to achieve this.
.ie n .SS "$p\->\fBget_top()\fP"
.el .SS "\f(CW$p\fP\->\fBget_top()\fP"
.IX Subsection "$p->get_top()"
Returns the top of the pages tree.