.\" 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::Page 3pm"
.TH PDF::Builder::Page 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::Page \- Methods to interact with individual pages
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$page = PDF::Builder::Page\->new($pdf, $parent, $index)" 4
.el .IP "\f(CW$page\fR = PDF::Builder::Page\->new($pdf, \f(CW$parent\fR, \f(CW$index\fR)" 4
.IX Item "$page = PDF::Builder::Page->new($pdf, $parent, $index)"
Returns a page object (called from \f(CW$pdf\fR\->\fBpage()\fR).
.ie n .IP "$page\->userunit($value)" 4
.el .IP "\f(CW$page\fR\->userunit($value)" 4
.IX Item "$page->userunit($value)"
Sets the User Unit for this one page.  
See \*(L"User Units\*(R" in PDF::Builder::Docs for more information.
.ie n .IP "$page\->mediabox($alias)" 4
.el .IP "\f(CW$page\fR\->mediabox($alias)" 4
.IX Item "$page->mediabox($alias)"
.PD 0
.ie n .IP "$page\->mediabox($alias, \-orient => 'orientation')" 4
.el .IP "\f(CW$page\fR\->mediabox($alias, \-orient => 'orientation')" 4
.IX Item "$page->mediabox($alias, -orient => 'orientation')"
.ie n .IP "$page\->mediabox($w,$h)" 4
.el .IP "\f(CW$page\fR\->mediabox($w,$h)" 4
.IX Item "$page->mediabox($w,$h)"
.ie n .IP "$page\->mediabox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$page\fR\->mediabox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$page->mediabox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBmediabox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBmediabox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->mediabox()"
.PD
Sets or gets the Media Box for this one page.  
See \*(L"Media Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBget_mediabox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBget_mediabox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->get_mediabox()"
Gets the Media Box corner coordinates based on best estimates or the default.
These are in the order given in a mediabox call (4 coordinates).
.Sp
This method is \fBDeprecated\fR, and will likely be removed in the future. Use
the global (\f(CW$pdf\fR) or page (\f(CW$page\fR) \fBmediabox()\fR call with no parameters
instead.
.ie n .IP "$page\->cropbox($alias)" 4
.el .IP "\f(CW$page\fR\->cropbox($alias)" 4
.IX Item "$page->cropbox($alias)"
.PD 0
.ie n .IP "$page\->cropbox($alias, \-orient => 'orientation')" 4
.el .IP "\f(CW$page\fR\->cropbox($alias, \-orient => 'orientation')" 4
.IX Item "$page->cropbox($alias, -orient => 'orientation')"
.ie n .IP "$page\->cropbox($w,$h)" 4
.el .IP "\f(CW$page\fR\->cropbox($w,$h)" 4
.IX Item "$page->cropbox($w,$h)"
.ie n .IP "$page\->cropbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$page\fR\->cropbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$page->cropbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBcropbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBcropbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->cropbox()"
.PD
Sets or gets the Crop Box for this one page.  
See \*(L"Crop Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBget_cropbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBget_cropbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->get_cropbox()"
Gets the Crop Box based on best estimates or the default.
.Sp
This method is \fBDeprecated\fR, and will likely be removed in the future. Use
the global (\f(CW$pdf\fR) or page (\f(CW$page\fR) \fBcropbox()\fR call with no parameters
instead.
.ie n .IP "$page\->bleedbox($alias)" 4
.el .IP "\f(CW$page\fR\->bleedbox($alias)" 4
.IX Item "$page->bleedbox($alias)"
.PD 0
.ie n .IP "$page\->bleedbox($alias, \-orient => 'orientation')" 4
.el .IP "\f(CW$page\fR\->bleedbox($alias, \-orient => 'orientation')" 4
.IX Item "$page->bleedbox($alias, -orient => 'orientation')"
.ie n .IP "$page\->bleedbox($w,$h)" 4
.el .IP "\f(CW$page\fR\->bleedbox($w,$h)" 4
.IX Item "$page->bleedbox($w,$h)"
.ie n .IP "$page\->bleedbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$page\fR\->bleedbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$page->bleedbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBbleedbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBbleedbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->bleedbox()"
.PD
Sets or gets or gets the Bleed Box for this one page.  
See \*(L"Bleed Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBget_bleedbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBget_bleedbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->get_bleedbox()"
Gets the Bleed Box based on best estimates or the default.
.Sp
This method is \fBDeprecated\fR, and will likely be removed in the future. Use
the global (\f(CW$pdf\fR) or page (\f(CW$page\fR) \fBbleedbox()\fR call with no parameters
instead.
.ie n .IP "$page\->trimbox($alias)" 4
.el .IP "\f(CW$page\fR\->trimbox($alias)" 4
.IX Item "$page->trimbox($alias)"
.PD 0
.ie n .IP "$page\->trimbox($alias, \-orient => 'orientation')" 4
.el .IP "\f(CW$page\fR\->trimbox($alias, \-orient => 'orientation')" 4
.IX Item "$page->trimbox($alias, -orient => 'orientation')"
.ie n .IP "$page\->trimbox($w,$h)" 4
.el .IP "\f(CW$page\fR\->trimbox($w,$h)" 4
.IX Item "$page->trimbox($w,$h)"
.ie n .IP "$page\->trimbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$page\fR\->trimbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$page->trimbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBtrimbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBtrimbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->trimbox()"
.PD
Sets or gets the Trim Box for this one page.  
See \*(L"Trim Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBget_trimbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBget_trimbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->get_trimbox()"
Gets the Trim Box based on best estimates or the default.
.Sp
This method is \fBDeprecated\fR, and will likely be removed in the future. Use
the global (\f(CW$pdf\fR) or page (\f(CW$page\fR) \fBtrimbox()\fR call with no parameters
instead.
.ie n .IP "$page\->artbox($alias)" 4
.el .IP "\f(CW$page\fR\->artbox($alias)" 4
.IX Item "$page->artbox($alias)"
.PD 0
.ie n .IP "$page\->artbox($alias, \-orient => 'orientation')" 4
.el .IP "\f(CW$page\fR\->artbox($alias, \-orient => 'orientation')" 4
.IX Item "$page->artbox($alias, -orient => 'orientation')"
.ie n .IP "$page\->artbox($w,$h)" 4
.el .IP "\f(CW$page\fR\->artbox($w,$h)" 4
.IX Item "$page->artbox($w,$h)"
.ie n .IP "$page\->artbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$page\fR\->artbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$page->artbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBartbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBartbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->artbox()"
.PD
Sets or gets the Art Box for this one page.  
See \*(L"Art Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "($llx,$lly, $urx,$ury) = $page\->\fBget_artbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$page\fR\->\fBget_artbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $page->get_artbox()"
Gets the Art Box based on best estimates or the default.
.Sp
This method is \fBDeprecated\fR, and will likely be removed in the future. Use
the global (\f(CW$pdf\fR) or page (\f(CW$page\fR) \fBartbox()\fR call with no parameters
instead.
.ie n .IP "$page\->rotate($deg)" 4
.el .IP "\f(CW$page\fR\->rotate($deg)" 4
.IX Item "$page->rotate($deg)"
Rotates the page by the given degrees, which must be a multiple of 90.
An angle that is not a multiple of 90 will be rounded to the nearest 90 
degrees, with a message.
Note that the rotation angle is \fIclockwise\fR for a positive amount!
E.g., a rotation of +90 (or \-270) will have the bottom edge of the paper at
the left of the screen.
.Sp
(This allows you to auto-rotate to landscape without changing the mediabox!)
.Sp
Do not confuse this \f(CW\*(C`rotate()\*(C'\fR call with the \fIgraphics context\fR rotation 
(Content.pm) \f(CW\*(C`rotate()\*(C'\fR, which permits any angle, is of opposite direction, 
and does not shift the origin!
.ie n .IP "$gfx = $page\->gfx($prepend)" 4
.el .IP "\f(CW$gfx\fR = \f(CW$page\fR\->gfx($prepend)" 4
.IX Item "$gfx = $page->gfx($prepend)"
.PD 0
.ie n .IP "$gfx = $page\->\fBgfx()\fR" 4
.el .IP "\f(CW$gfx\fR = \f(CW$page\fR\->\fBgfx()\fR" 4
.IX Item "$gfx = $page->gfx()"
.PD
Returns a graphics content object. 
If \f(CW$prepend\fR is \fItrue\fR, the content will be prepended to the page description.
Otherwise, it will be appended.
.Sp
You may have more than one \fIgfx\fR object. They and \fItext\fR objects will be 
output as objects and streams in the order defined, with all actions pertaining
to this \fIgfx\fR object appearing in one stream. However, note that graphics 
and text objects are not fully independent of each other: the exit state 
(linewidth, strokecolor, etc.) of one object is the entry state of the next 
object in line to be output, and so on.
.Sp
If you intermix multiple \fIgfx\fR and \fItext\fR objects on
a page, the results may be confusing. Say you have \f(CW$gfx1\fR, \f(CW$text1\fR, \f(CW$gfx2\fR, and
\&\f(CW$text2\fR on your page (\fIcreated in that order\fR). PDF::Builder will output all the
\&\f(CW$gfx1\fR\->\fIaction\fR calls in one stream, then all the \f(CW$text1\fR\->\fIaction\fR calls in
the next stream, and likewise for \f(CW$gfx2\fR usage and finally \f(CW$text2\fR.
.Sp
Then it's \s-1PDF\s0's turn to confuse you. \s-1PDF\s0 will process the entire \f(CW$gfx1\fR object
stream, accumulating the graphics state to the end of the stream, and using 
that as the entry state into \f(CW$text1\fR. In a similar manner, \f(CW$gfx2\fR and \f(CW$text2\fR are
read, processed, and rendered. Thus, a change in, say, the dash pattern in the
middle of \f(CW$gfx1\fR, \fIafter\fR you have output some \f(CW$gfx2\fR, \f(CW$text1\fR, and \f(CW$text2\fR 
material, may suddenly show up at the beginning of \f(CW$text1\fR (and continue through 
\&\f(CW$gfx2\fR and \f(CW$text2\fR)!
.Sp
It is possible to use multiple graphics objects, to avoid having to change
settings constantly, but you may want to consider resetting all your settings 
at the first call to each object, so that you are starting from a known base.
This may most easily be done by using $\fItype\fR\->\fBrestore()\fR and \->\fBsave()\fR just
after creating $\fItype\fR:
.RS 4
.Sp
.Vb 10
\& $text1 = $page\->text(); 
\&   $text1\->save();
\& $grfx1 = $page\->gfx();
\&   $grfx1\->restore();
\&   $grfx1\->save();
\& $text2 = $page\->text();
\&   $text2\->restore();
\&   $text2\->save();
\& $grfx2 = $page\->gfx();
\&   $grfx1\->restore();
.Ve
.RE
.RS 4
.RE
.ie n .IP "$txt = $page\->text($prepend)" 4
.el .IP "\f(CW$txt\fR = \f(CW$page\fR\->text($prepend)" 4
.IX Item "$txt = $page->text($prepend)"
.PD 0
.ie n .IP "$txt = $page\->\fBtext()\fR" 4
.el .IP "\f(CW$txt\fR = \f(CW$page\fR\->\fBtext()\fR" 4
.IX Item "$txt = $page->text()"
.PD
Returns a text content object. 
If \f(CW$prepend\fR is \fItrue\fR, the content will be prepended to the page description.
Otherwise, it will be appended.
.Sp
Please see the discussion above in \f(CW\*(C`gfx()\*(C'\fR regarding multiple graphics and
text objects on one page, how they are grouped into \s-1PDF\s0 objects and streams, 
and the rendering consequences of running through one entire object at a time,
before moving on to the next.
.Sp
The \fItext\fR object has many settings and attributes of its own, but shares many
with graphics (\fIgfx\fR), such as strokecolor, fillcolor, linewidth, linedash,
and the like. Thus there is some overlap in attributes, and graphics and text
calls can affect each other.
.ie n .IP "$ant = $page\->\fBannotation()\fR" 4
.el .IP "\f(CW$ant\fR = \f(CW$page\fR\->\fBannotation()\fR" 4
.IX Item "$ant = $page->annotation()"
Returns a new annotation object.
.ie n .IP "$page\->resource($type, $key, $obj)" 4
.el .IP "\f(CW$page\fR\->resource($type, \f(CW$key\fR, \f(CW$obj\fR)" 4
.IX Item "$page->resource($type, $key, $obj)"
Adds a resource to the page-inheritance tree.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $co\->resource(\*(AqFont\*(Aq, $fontkey, $fontobj);
\&    $co\->resource(\*(AqXObject\*(Aq, $imagekey, $imageobj);
\&    $co\->resource(\*(AqShading\*(Aq, $shadekey, $shadeobj);
\&    $co\->resource(\*(AqColorSpace\*(Aq, $spacekey, $speceobj);
.Ve
.Sp
\&\fBNote:\fR You only have to add the required resources if
they are \s-1NOT\s0 handled by the *font*, *image*, *shade* or *space*
methods.