{
    "mode": "perldoc",
    "parameter": "PDF::API2::Page",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/PDF%3A%3AAPI2%3A%3APage/json",
    "generated": "2026-06-12T18:55:31Z",
    "synopsis": "my $pdf = PDF::API2->new();\n# Add a page to a new or existing PDF\nmy $page = $pdf->page();\n# Set the page size\n$page->size('letter');\n# Set prepress page boundaries\n$page->boundaries(media => '12x18', trim => 0.5 * 72);\n# Add an image\nmy $image = $pdf->image('/path/to/file.jpg');\n$page->object($image, $x, $y, $w, $h);\n# Add textual content\nmy $text = $page->text();\n# Add graphical content (paths and shapes)\nmy $canvas = $page->graphics();",
    "sections": {
        "NAME": {
            "content": "PDF::API2::Page - Methods to interact with individual pages\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $pdf = PDF::API2->new();\n\n# Add a page to a new or existing PDF\nmy $page = $pdf->page();\n\n# Set the page size\n$page->size('letter');\n\n# Set prepress page boundaries\n$page->boundaries(media => '12x18', trim => 0.5 * 72);\n\n# Add an image\nmy $image = $pdf->image('/path/to/file.jpg');\n$page->object($image, $x, $y, $w, $h);\n\n# Add textual content\nmy $text = $page->text();\n\n# Add graphical content (paths and shapes)\nmy $canvas = $page->graphics();\n",
            "subsections": []
        },
        "METHODS": {
            "content": "size\n# Set the page size using a common name\n$page->size('letter');\n\n# Set the page size using coordinates in points (X1, Y1, X2, Y2)\n$page->size([0, 0, 612, 792]);\n\n# Get the page coordinates in points\nmy @rectangle = $page->size();\n\nSet the physical page size (a.k.a. media box) when called with an argument. See \"Page Sizes\"\nbelow for possible values. Returns the $page object.\n\nReturns the coordinates of the rectangle enclosing the physical page size when called without\narguments.\n\nThe size method is a convenient shortcut for setting the PDF's media box when print-related page\nboundaries aren't required. It's equivalent to the following:\n\n# Set\n$page = $page->boundaries(media => $size);\n\n# Get\n@rectangle = $page->boundaries->{'media'}->@*;\n\nboundaries\n# Set\n$page->boundaries(\nmedia => '13x19',\nbleed => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],\ntrim  => 0.25 * 72,\n);\n\n# Get\n%boundaries = $page->boundaries();\n($x1, $y1, $x2, $y2) = $page->boundaries('trim');\n\nSet prepress page boundaries when called with a hash containing one or more page boundary\ndefinitions. Returns the $page object.\n\nReturns the current page boundaries if called without arguments. Returns the coordinates for the\nspecified page boundary if called with one argument.\n\nPage Boundaries\nPDF defines five page boundaries. When creating PDFs for print shops, you'll most commonly use\njust the media box and trim box. Traditional print shops may also use the bleed box when adding\nprinter's marks and other information.\n\n*   media\n\nThe media box defines the boundaries of the physical medium on which the page is to be\nprinted. It may include any extended area surrounding the finished page for bleed, printing\nmarks, or other such purposes. The default value is a US letter page (8.5\" x 11\").\n\n*   crop\n\nThe crop box defines the region to which the contents of the page shall be clipped (cropped)\nwhen displayed or printed. The default value is the page's media box.\n\nThis is a historical page boundary. You'll likely want to set the bleed and/or trim boxes\ninstead.\n\n*   bleed\n\nThe bleed box defines the region to which the contents of the page shall be clipped when\noutput in a production environment. This may include any extra bleed area needed to\naccommodate the physical limitations of cutting, folding, and trimming equipment. The actual\nprinted page (media box) may include printing marks that fall outside the bleed box. The\ndefault value is the page's crop box.\n\n*   trim\n\nThe trim box defines the intended dimensions of the finished page after trimming. It may be\nsmaller than the media box to allow for production-related content, such as printing\ninstructions, cut marks, or color bars. The default value is the page's crop box.\n\n*   art\n\nThe art box defines the extent of the page's meaningful content (including potential white\nspace) as intended by the page's creator. The default value is the page's crop box.\n\nPage Sizes\nPDF page sizes are stored as rectangle coordinates. For convenience, PDF::API2 also supports a\nnumber of aliases and shortcuts that are more human-friendly.\n\nThe following formats are available:\n\n*   a standard paper size\n\n$page->boundaries(media => 'A4');\n\nAliases for the most common paper sizes are built in (case-insensitive).\n\nUS: Letter, Legal, Ledger, Tabloid\n\nMetric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6\n\n*   a \"WxH\" string in inches\n\n$page->boundaries(media => '8.5x11');\n\nMany US paper sizes are commonly identified by their size in inches rather than by a\nparticular name. These can be passed as strings with the width and height separated by an\n\"x\".\n\nExamples: \"4x6\", \"12x18\", \"8.5x11\"\n\n*   a number (in points) representing a reduction from the next-larger box\n\n# Note: There are 72 points per inch\n$page->boundaries(media => '12x18', trim => 0.5 * 72);\n\n# Equivalent\n$page->boundaries(media => [0,        0,        12   * 72, 18   * 72],\ntrim  => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);\n\nThis example shows a 12\" x 18\" physical sheet that will be reduced to a final size of 11\" x\n17\" by trimming 0.5\" from each edge. The smaller boundary is assumed to be centered on the\nlarger one.\n\nThe \"next-larger box\" follows this order, stopping at the first defined value:\n\nart -> trim -> bleed -> media\n\ncrop -> media\n\nThis option isn't available for the media box since it is by definition the largest\nboundary.\n\n*   [$width, $height] in points\n\n$page->boundaries(media => [8.5 * 72, 11 * 7.2]);\n\nFor other page or boundary sizes, the width and height (in points) can be given directly as\nan array.\n\n*   [$x1, $y1, $x2, $y2] in points\n\n$page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);\n\nFinally, the raw coordinates of the bottom-left and top-right corners of a rectangle can be\nspecified.\n\nrotation\n$page = $page->rotation($degrees);\n\nRotates the page clockwise when displayed or printed. $degrees must be a multiple of 90 and may\nbe negative for counter-clockwise rotation.\n\nThe coordinate system follows the page rotation. In other words, after rotating the page 180\ndegrees, [0, 0] will be in the top right corner of the page rather than the bottom left, X will\nincrease to the right, and Y will increase downward.\n\nTo create a landscape page without moving the origin, use \"size\".\n\ngraphics\nmy $canvas = $page->graphics(%options);\n\nReturns a PDF::API2::Content object for drawing paths and shapes.\n\nThe following options are available:\n\n*   prepend (boolean)\n\nIf true, place the drawing at the beginning of the page's content stream instead of the end.\n\n*   compress (boolean)\n\nManually specify whether the drawing instructions should be compressed. If unspecified, the\nPDF's compression setting will be used, which is on by default.\n\ntext\nmy $text = $page->text(%options);\n\nReturns a PDF::API2::Content object for including textual content.\n\nThe options are the same as the \"graphics\" method.\n\nobject\n$page = $page->object($object, $x, $y, $scalex, $scaley);\n\nPlaces an image or other external object (a.k.a. XObject) on the page in the specified location.\n\nFor images, $scalex and $scaley represent the width and height of the image on the page in\npoints. If $scalex is omitted, it will default to 72 pixels per inch. If $scaley is omitted,\nthe image will be scaled proportionally based on the image dimensions.\n\nFor other external objects, the scale is a multiplier, where 1 (the default) represents 100%\n(i.e. no change).\n\nIf the object to be placed depends on a coordinate transformation (e.g. rotation or skew), first\ncreate a content object using \"graphics\", then call \"object\" in PDF::API2::Content after making\nthe appropriate transformations.\n\nannotation\nmy $annotation = $page->annotation();\n\nReturns a new PDF::API2::Annotation object.\n",
            "subsections": []
        },
        "MIGRATION": {
            "content": "See \"MIGRATION\" in PDF::API2 for an overview.\n\ngfx Replace with \"graphics\".\n\nrotate\nReplace with \"rotation\".\n\nmediabox\ngetmediabox\nReplace with \"size\" if not in a print shop environment or \"boundaries\" if more complex page\nboundaries are needed.\n\nIf using page size aliases (e.g. \"letter\" or \"A4\"), check the Page Sizes section to ensure\nthat the alias you're using is still supported (you'll get an error if it isn't).\n\ncropbox\nbleedbox\ntrimbox\nartbox\ngetcropbox\ngetbleedbox\ngettrimbox\ngetartbox\nReplace with \"boundaries\".\n",
            "subsections": []
        }
    },
    "summary": "PDF::API2::Page - Methods to interact with individual pages",
    "flags": [],
    "examples": [],
    "see_also": []
}