Provided by: libpdf-api2-perl_2.044-1_all bug

NAME

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

SYNOPSIS

           my $pdf = PDF::API2->new();

           # Add a page to a new or existing PDF
           my $page = $pdf->page();

           # Set the page size
           $page->size('letter');

           # Set prepress page boundaries
           $page->boundaries(media => '12x18', trim => 0.5 * 72);

           # Add an image
           my $image = $pdf->image('/path/to/file.jpg');
           $page->object($image, $x, $y, $w, $h);

           # Add textual content
           my $text = $page->text();

           # Add graphical content (paths and shapes)
           my $canvas = $page->graphics();

METHODS

   size
           # Set the page size using a common name
           $page->size('letter');

           # Set the page size using coordinates in points (X1, Y1, X2, Y2)
           $page->size([0, 0, 612, 792]);

           # Get the page coordinates in points
           my @rectangle = $page->size();

       Set the physical page size (a.k.a. media box) when called with an argument.  See "Page
       Sizes" below for possible values.  Returns the $page object.

       Returns the coordinates of the rectangle enclosing the physical page size when called
       without arguments.

       The size method is a convenient shortcut for setting the PDF's media box when print-
       related page boundaries aren't required.  It's equivalent to the following:

           # Set
           $page = $page->boundaries(media => $size);

           # Get
           @rectangle = $page->boundaries->{'media'}->@*;

   boundaries
           # Set
           $page->boundaries(
               media => '13x19',
               bleed => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
               trim  => 0.25 * 72,
           );

           # Get
           %boundaries = $page->boundaries();
           ($x1, $y1, $x2, $y2) = $page->boundaries('trim');

       Set or replace all prepress page boundaries when called with a hash containing one or more
       page boundary definitions.  Returns the $page object.

       Returns the current page boundaries if called without arguments.  Returns the coordinates
       for the specified page boundary if called with one argument.

       Page Boundaries

       PDF defines five page boundaries.  When creating PDFs for print shops, you'll most
       commonly use just the media box and trim box.  Traditional print shops may also use the
       bleed box when adding printer's marks and other information.

       •   media

           The media box defines the boundaries of the physical medium on which the page is to be
           printed.  It may include any extended area surrounding the finished page for bleed,
           printing marks, or other such purposes.  The default value is a US letter page (8.5" x
           11").

       •   crop

           The crop box defines the region to which the contents of the page shall be clipped
           (cropped) when displayed or printed.  The default value is the page's media box.

           This is a historical page boundary.  You'll likely want to set the bleed and/or trim
           boxes instead.

       •   bleed

           The bleed box defines the region to which the contents of the page shall be clipped
           when output in a production environment.  This may include any extra bleed area needed
           to accommodate the physical limitations of cutting, folding, and trimming equipment.
           The actual printed page (media box) may include printing marks that fall outside the
           bleed box.  The default value is the page's crop box.

       •   trim

           The trim box defines the intended dimensions of the finished page after trimming.  It
           may be smaller than the media box to allow for production-related content, such as
           printing instructions, cut marks, or color bars.  The default value is the page's crop
           box.

       •   art

           The art box defines the extent of the page's meaningful content (including potential
           white space) as intended by the page's creator.  The default value is the page's crop
           box.

       Page Sizes

       PDF page sizes are stored as rectangle coordinates.  For convenience, PDF::API2 also
       supports a number of aliases and shortcuts that are more human-friendly.

       The following formats are available:

       •   a standard paper size

               $page->boundaries(media => 'A4');

           Aliases for the most common paper sizes are built in (case-insensitive).

           US: Letter, Legal, Ledger, Tabloid

           Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6

       •   a "WxH" string in inches

               $page->boundaries(media => '8.5x11');

           Many US paper sizes are commonly identified by their size in inches rather than by a
           particular name.  These can be passed as strings with the width and height separated
           by an "x".

           Examples: "4x6", "12x18", "8.5x11"

       •   a number (in points) representing a reduction from the next-larger box

               # Note: There are 72 points per inch
               $page->boundaries(media => '12x18', trim => 0.5 * 72);

               # Equivalent
               $page->boundaries(media => [0,        0,        12   * 72, 18   * 72],
                                 trim  => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);

           This example shows a 12" x 18" physical sheet that will be reduced to a final size of
           11" x 17" by trimming 0.5" from each edge.  The smaller boundary is assumed to be
           centered on the larger one.

           The "next-larger box" follows this order, stopping at the first defined value:

               art -> trim -> bleed -> media

               crop -> media

           This option isn't available for the media box since it is by definition the largest
           boundary.

       •   [$width, $height] in points

               $page->boundaries(media => [8.5 * 72, 11 * 7.2]);

           For other page or boundary sizes, the width and height (in points) can be given
           directly as an array.

       •   [$x1, $y1, $x2, $y2] in points

               $page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);

           Finally, the raw coordinates of the bottom-left and top-right corners of a rectangle
           can be specified.

   rotation
           $page = $page->rotation($degrees);

       Rotates the page clockwise when displayed or printed.  $degrees must be a multiple of 90
       and may be negative for counter-clockwise rotation.

       The coordinate system follows the page rotation.  In other words, after rotating the page
       180 degrees, [0, 0] will be in the top right corner of the page rather than the bottom
       left, X will increase to the right, and Y will increase downward.

       To create a landscape page without moving the origin, use "size".

   graphics
           my $canvas = $page->graphics(%options);

       Returns a PDF::API2::Content object for drawing paths and shapes.

       The following options are available:

       •   prepend (boolean)

           If true, place the drawing at the beginning of the page's content stream instead of
           the end.

       •   compress (boolean)

           Manually specify whether the drawing instructions should be compressed.  If
           unspecified, the PDF's compression setting will be used, which is on by default.

   text
           my $text = $page->text(%options);

       Returns a PDF::API2::Content object for including textual content.

       The options are the same as the "graphics" method.

   object
           $page = $page->object($object, $x, $y, $scale_x, $scale_y);

       Places an image or other external object (a.k.a. XObject) on the page in the specified
       location.

       For images, $scale_x and $scale_y represent the width and height of the image on the page
       in points.  If $scale_x is omitted, it will default to 72 pixels per inch.  If $scale_y is
       omitted, the image will be scaled proportionally based on the image dimensions.

       For other external objects, the scale is a multiplier, where 1 (the default) represents
       100% (i.e. no change).

       If the object to be placed depends on a coordinate transformation (e.g. rotation or skew),
       first create a content object using "graphics", then call "object" in PDF::API2::Content
       after making the appropriate transformations.

   annotation
           my $annotation = $page->annotation();

       Returns a new PDF::API2::Annotation object.

MIGRATION

       See "MIGRATION" in PDF::API2 for an overview.

       gfx Replace with "graphics".

       rotate
           Replace with "rotation".

       mediabox
       get_mediabox
           Replace with "size" if not in a print shop environment or "boundaries" if more complex
           page boundaries are needed.

           If using page size aliases (e.g. "letter" or "A4"), check the Page Sizes section to
           ensure that the alias you're using is still supported (you'll get an error if it
           isn't).

       cropbox
       bleedbox
       trimbox
       artbox
       get_cropbox
       get_bleedbox
       get_trimbox
       get_artbox
           Replace with "boundaries".