NAME

PDF::Builder::Page - Methods to interact with individual pages

METHODS

$page = PDF::Builder::Page->new($pdf, $parent, $index)

Returns a page object (called from $pdf->page()).

$page = PDF::Builder::Page->coerce($pdf, $pdfpage)

Returns a page object converted from $pdfpage (called from $pdf->openpage()).

$page->update()

Marks a page to be updated (by $pdf->update()).

$page->mediabox($w,$h)

$page->mediabox($llx,$lly, $urx,$ury)

$page->mediabox($alias)

Sets the mediabox. This method supports the following aliases and more: '4A0', '2A0', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', '4B0', '2B0', 'B0', 'B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'LETTER', 'BROADSHEET', 'LEDGER', 'TABLOID', 'LEGAL', 'EXECUTIVE', and '36X36'. See PDF::Builder::Resource::get_paper_sizes() for the full list.

($llx,$lly, $urx,$ury) = $page->get_mediabox()

Gets the mediabox based on best estimates or the default.

$page->cropbox($w,$h)

$page->cropbox($llx,$lly, $urx,$ury)

$page->cropbox($alias)

Sets the cropbox. This method supports the same aliases as mediabox.

($llx,$lly, $urx,$ury) = $page->get_cropbox()

Gets the cropbox based on best estimates or the default.

$page->bleedbox($w,$h)

$page->bleedbox($llx,$lly, $urx,$ury)

$page->bleedbox($alias)

Sets the bleedbox. This method supports the same aliases as mediabox.

($llx,$lly, $urx,$ury) = $page->get_bleedbox()

Gets the bleedbox based on best estimates or the default.

$page->trimbox($w,$h)

$page->trimbox($llx,$lly, $urx,$ury)

$page->trimbox($alias)

Sets the trimbox. This method supports the same aliases as mediabox.

($llx,$lly, $urx,$ury) = $page->get_trimbox()

Gets the trimbox based on best estimates or the default.

$page->artbox($w,$h)

$page->artbox($llx,$lly, $urx,$ury)

$page->artbox($alias)

Sets the artbox. This method supports the same aliases as mediabox.

($llx,$lly, $urx,$ury) = $page->get_artbox()

Gets the artbox based on best estimates or the default.

$page->rotate($deg)

Rotates the page by the given degrees, which must be a multiple of 90.

(This allows you to auto-rotate to landscape without changing the mediabox!)

$gfx = $page->gfx($prepend)

$gfx = $page->gfx()

Returns a graphics content object. If $prepend is true, the content will be prepended to the page description. Otherwise, it will be appended.

You may have more than one gfx object. They and text objects will be output as objects and streams in the order defined, with all actions pertaining to this gfx 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.

If you intermix multiple gfx and text objects on a page, the results may be confusing. Say you have $gfx1, $text1, $gfx2, and $text2 on your page (created in that order). PDF::Builder will output all the $gfx1->action calls in one stream, then all the $text1->action calls in the next stream, and likewise for $gfx2 usage and finally $text2.

Then it's PDF's turn to confuse you. PDF will process the entire $gfx1 object stream, accumulating the graphics state to the end of the stream, and using that as the entry state into $text1. In a similar manner, $gfx2 and $text2 are read, processed, and rendered. Thus, a change in, say, the dash pattern in the middle of $gfx1, after you have output some $gfx2, $text1, and $text2 material, may suddenly show up at the beginning of $text1 (and continue through $gfx2 and $text2)!

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 $type->restore() and ->save() just after creating $type:

$text1 = $page->text(); 
  $text1->save();
$grfx1 = $page->gfx();
  $grfx1->restore();
  $grfx1->save();
$text2 = $page->text();
  $text2->restore();
  $text2->save();
$grfx2 = $page->gfx();
  $grfx1->restore();

$txt = $page->text($prepend)

$txt = $page->text()

Returns a text content object. If $prepend is true, the content will be prepended to the page description. Otherwise, it will be appended.

Please see the discussion above in gfx() regarding multiple graphics and text objects on one page, how they are grouped into PDF objects and streams, and the rendering consequences of running through one entire object at a time, before moving on to the next.

The text object has many settings and attributes of its own, but shares many with graphics (gfx), 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.

$ant = $page->annotation()

Returns a new annotation object.

$page->resource($type, $key, $obj)

Adds a resource to the page-inheritance tree.

Example:

$co->resource('Font', $fontkey, $fontobj);
$co->resource('XObject', $imagekey, $imageobj);
$co->resource('Shading', $shadekey, $shadeobj);
$co->resource('ColorSpace', $spacekey, $speceobj);

Note: You only have to add the required resources, if they are NOT handled by the *font*, *image*, *shade* or *space* methods.