.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::API2 3pm"
.TH PDF::API2 3pm "2020-10-25" "perl v5.30.3" "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::API2 \- Facilitates the creation and modification of PDF files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use PDF::API2;
\&
\&    # Create a blank PDF file
\&    $pdf = PDF::API2\->new();
\&
\&    # Open an existing PDF file
\&    $pdf = PDF::API2\->open(\*(Aqsome.pdf\*(Aq);
\&
\&    # Add a blank page
\&    $page = $pdf\->page();
\&
\&    # Retrieve an existing page
\&    $page = $pdf\->openpage($page_number);
\&
\&    # Set the page size
\&    $page\->mediabox(\*(AqLetter\*(Aq);
\&
\&    # Add a built\-in font to the PDF
\&    $font = $pdf\->corefont(\*(AqHelvetica\-Bold\*(Aq);
\&
\&    # Add an external TTF font to the PDF
\&    $font = $pdf\->ttfont(\*(Aq/path/to/font.ttf\*(Aq);
\&
\&    # Add some text to the page
\&    $text = $page\->text();
\&    $text\->font($font, 20);
\&    $text\->translate(200, 700);
\&    $text\->text(\*(AqHello World!\*(Aq);
\&
\&    # Save the PDF
\&    $pdf\->saveas(\*(Aq/path/to/new.pdf\*(Aq);
.Ve
.SH "GENERIC METHODS"
.IX Header "GENERIC METHODS"
.ie n .IP "$pdf = \s-1PDF::API2\-\s0>new(%options)" 4
.el .IP "\f(CW$pdf\fR = \s-1PDF::API2\-\s0>new(%options)" 4
.IX Item "$pdf = PDF::API2->new(%options)"
Creates a new \s-1PDF\s0 object.  If you will be saving it as a file and
already know the filename, you can give the '\-file' option to minimize
possible memory requirements later on.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::API2\->new();
\&    ...
\&    print $pdf\->stringify();
\&
\&    $pdf = PDF::API2\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::API2\->new(\-file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->save();
.Ve
.ie n .IP "$pdf = \s-1PDF::API2\-\s0>open($pdf_file)" 4
.el .IP "\f(CW$pdf\fR = \s-1PDF::API2\-\s0>open($pdf_file)" 4
.IX Item "$pdf = PDF::API2->open($pdf_file)"
Opens an existing \s-1PDF\s0 file.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::API2\->open(\*(Aqour/old.pdf\*(Aq);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::API2\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.ie n .IP "$pdf = \s-1PDF::API2\-\s0>open_scalar($pdf_string)" 4
.el .IP "\f(CW$pdf\fR = \s-1PDF::API2\-\s0>open_scalar($pdf_string)" 4
.IX Item "$pdf = PDF::API2->open_scalar($pdf_string)"
Opens a \s-1PDF\s0 contained in a string.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    # Read a PDF into a string, for the purpose of demonstration
\&    open $fh, \*(Aqour/old.pdf\*(Aq or die $@;
\&    undef $/;  # Read the whole file at once
\&    $pdf_string = <$fh>;
\&
\&    $pdf = PDF::API2\->open_scalar($pdf_string);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.ie n .IP "$pdf\->preferences(%options)" 4
.el .IP "\f(CW$pdf\fR\->preferences(%options)" 4
.IX Item "$pdf->preferences(%options)"
Controls viewing preferences for the \s-1PDF.\s0
.Sp
\&\fBPage Mode Options:\fR
.RS 4
.IP "\-fullscreen" 4
.IX Item "-fullscreen"
Full-screen mode, with no menu bar, window controls, or any other window visible.
.IP "\-thumbs" 4
.IX Item "-thumbs"
Thumbnail images visible.
.IP "\-outlines" 4
.IX Item "-outlines"
Document outline visible.
.RE
.RS 4
.Sp
\&\fBPage Layout Options:\fR
.IP "\-singlepage" 4
.IX Item "-singlepage"
Display one page at a time.
.IP "\-onecolumn" 4
.IX Item "-onecolumn"
Display the pages in one column.
.IP "\-twocolumnleft" 4
.IX Item "-twocolumnleft"
Display the pages in two columns, with oddnumbered pages on the left.
.IP "\-twocolumnright" 4
.IX Item "-twocolumnright"
Display the pages in two columns, with oddnumbered pages on the right.
.RE
.RS 4
.Sp
\&\fBViewer Options:\fR
.IP "\-hidetoolbar" 4
.IX Item "-hidetoolbar"
Specifying whether to hide tool bars.
.IP "\-hidemenubar" 4
.IX Item "-hidemenubar"
Specifying whether to hide menu bars.
.IP "\-hidewindowui" 4
.IX Item "-hidewindowui"
Specifying whether to hide user interface elements.
.IP "\-fitwindow" 4
.IX Item "-fitwindow"
Specifying whether to resize the document's window to the size of the displayed page.
.IP "\-centerwindow" 4
.IX Item "-centerwindow"
Specifying whether to position the document's window in the center of the screen.
.IP "\-displaytitle" 4
.IX Item "-displaytitle"
Specifying whether the window's title bar should display the
document title taken from the Title entry of the document information
dictionary.
.IP "\-afterfullscreenthumbs" 4
.IX Item "-afterfullscreenthumbs"
Thumbnail images visible after Full-screen mode.
.IP "\-afterfullscreenoutlines" 4
.IX Item "-afterfullscreenoutlines"
Document outline visible after Full-screen mode.
.IP "\-printscalingnone" 4
.IX Item "-printscalingnone"
Set the default print setting for page scaling to none.
.IP "\-simplex" 4
.IX Item "-simplex"
Print single-sided by default.
.IP "\-duplexflipshortedge" 4
.IX Item "-duplexflipshortedge"
Print duplex by default and flip on the short edge of the sheet.
.IP "\-duplexfliplongedge" 4
.IX Item "-duplexfliplongedge"
Print duplex by default and flip on the long edge of the sheet.
.RE
.RS 4
.Sp
\&\fBInitial Page Options\fR:
.ie n .IP "\-firstpage => [ $page, %options ]" 4
.el .IP "\-firstpage => [ \f(CW$page\fR, \f(CW%options\fR ]" 4
.IX Item "-firstpage => [ $page, %options ]"
Specifying the page (either a page number or a page object) to be
displayed, plus one of the following options:
.RS 4
.IP "\-fit => 1" 4
.IX Item "-fit => 1"
Display the page designated by page, with its contents magnified just
enough to fit the entire page within the window both horizontally and
vertically. If the required horizontal and vertical magnification
factors are different, use the smaller of the two, centering the page
within the window in the other dimension.
.ie n .IP "\-fith => $top" 4
.el .IP "\-fith => \f(CW$top\fR" 4
.IX Item "-fith => $top"
Display the page designated by page, with the vertical coordinate top
positioned at the top edge of the window and the contents of the page
magnified just enough to fit the entire width of the page within the
window.
.ie n .IP "\-fitv => $left" 4
.el .IP "\-fitv => \f(CW$left\fR" 4
.IX Item "-fitv => $left"
Display the page designated by page, with the horizontal coordinate
left positioned at the left edge of the window and the contents of the
page magnified just enough to fit the entire height of the page within
the window.
.ie n .IP "\-fitr => [ $left, $bottom, $right, $top ]" 4
.el .IP "\-fitr => [ \f(CW$left\fR, \f(CW$bottom\fR, \f(CW$right\fR, \f(CW$top\fR ]" 4
.IX Item "-fitr => [ $left, $bottom, $right, $top ]"
Display the page designated by page, with its contents magnified just
enough to fit the rectangle specified by the coordinates left, bottom,
right, and top entirely within the window both horizontally and
vertically. If the required horizontal and vertical magnification
factors are different, use the smaller of the two, centering the
rectangle within the window in the other dimension.
.IP "\-fitb => 1" 4
.IX Item "-fitb => 1"
Display the page designated by page, with its contents magnified just
enough to fit its bounding box entirely within the window both
horizontally and vertically. If the required horizontal and vertical
magnification factors are different, use the smaller of the two,
centering the bounding box within the window in the other dimension.
.ie n .IP "\-fitbh => $top" 4
.el .IP "\-fitbh => \f(CW$top\fR" 4
.IX Item "-fitbh => $top"
Display the page designated by page, with the vertical coordinate top
positioned at the top edge of the window and the contents of the page
magnified just enough to fit the entire width of its bounding box
within the window.
.ie n .IP "\-fitbv => $left" 4
.el .IP "\-fitbv => \f(CW$left\fR" 4
.IX Item "-fitbv => $left"
Display the page designated by page, with the horizontal coordinate
left positioned at the left edge of the window and the contents of the
page magnified just enough to fit the entire height of its bounding
box within the window.
.ie n .IP "\-xyz => [ $left, $top, $zoom ]" 4
.el .IP "\-xyz => [ \f(CW$left\fR, \f(CW$top\fR, \f(CW$zoom\fR ]" 4
.IX Item "-xyz => [ $left, $top, $zoom ]"
Display the page designated by page, with the coordinates (left, top)
positioned at the top-left corner of the window and the contents of
the page magnified by the factor zoom. A zero (0) value for any of the
parameters left, top, or zoom specifies that the current value of that
parameter is to be retained unchanged.
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 6
\&    $pdf\->preferences(
\&        \-fullscreen => 1,
\&        \-onecolumn => 1,
\&        \-afterfullscreenoutlines => 1,
\&        \-firstpage => [$page, \-fit => 1],
\&    );
.Ve
.RE
.ie n .IP "$val = $pdf\->default($parameter)" 4
.el .IP "\f(CW$val\fR = \f(CW$pdf\fR\->default($parameter)" 4
.IX Item "$val = $pdf->default($parameter)"
.PD 0
.ie n .IP "$pdf\->default($parameter, $value)" 4
.el .IP "\f(CW$pdf\fR\->default($parameter, \f(CW$value\fR)" 4
.IX Item "$pdf->default($parameter, $value)"
.PD
Gets/sets the default value for a behaviour of \s-1PDF::API2.\s0
.Sp
\&\fBSupported Parameters:\fR
.RS 4
.IP "nounrotate" 4
.IX Item "nounrotate"
prohibits \s-1API2\s0 from rotating imported/opened page to re-create a
default pdf-context.
.IP "pageencaps" 4
.IX Item "pageencaps"
enables than \s-1API2\s0 will add save/restore commands upon imported/opened
pages to preserve graphics-state for modification.
.IP "copyannots" 4
.IX Item "copyannots"
enables importing of annotations (\fB*EXPERIMENTAL*\fR).
.RE
.RS 4
.RE
.ie n .IP "$version = $pdf\->version([$new_version])" 4
.el .IP "\f(CW$version\fR = \f(CW$pdf\fR\->version([$new_version])" 4
.IX Item "$version = $pdf->version([$new_version])"
Get/set the \s-1PDF\s0 version (e.g. 1.4)
.ie n .IP "$bool = $pdf\->\fBisEncrypted()\fR" 4
.el .IP "\f(CW$bool\fR = \f(CW$pdf\fR\->\fBisEncrypted()\fR" 4
.IX Item "$bool = $pdf->isEncrypted()"
Checks if the previously opened \s-1PDF\s0 is encrypted.
.ie n .IP "%infohash = $pdf\->info(%infohash)" 4
.el .IP "\f(CW%infohash\fR = \f(CW$pdf\fR\->info(%infohash)" 4
.IX Item "%infohash = $pdf->info(%infohash)"
Gets/sets the info structure of the document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 11
\&    %h = $pdf\->info(
\&        \*(AqAuthor\*(Aq       => "Alfred Reibenschuh",
\&        \*(AqCreationDate\*(Aq => "D:20020911000000+01\*(Aq00\*(Aq",
\&        \*(AqModDate\*(Aq      => "D:YYYYMMDDhhmmssOHH\*(Aqmm\*(Aq",
\&        \*(AqCreator\*(Aq      => "fredos\-script.pl",
\&        \*(AqProducer\*(Aq     => "PDF::API2",
\&        \*(AqTitle\*(Aq        => "some Publication",
\&        \*(AqSubject\*(Aq      => "perl ?",
\&        \*(AqKeywords\*(Aq     => "all good things are pdf"
\&    );
\&    print "Author: $h{Author}\en";
.Ve
.ie n .IP "@metadata_attributes = $pdf\->infoMetaAttributes(@metadata_attributes)" 4
.el .IP "\f(CW@metadata_attributes\fR = \f(CW$pdf\fR\->infoMetaAttributes(@metadata_attributes)" 4
.IX Item "@metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)"
Gets/sets the supported info-structure tags.
.Sp
\&\fBExample:\fR
.Sp
.Vb 2
\&    @attributes = $pdf\->infoMetaAttributes;
\&    print "Supported Attributes: @attr\en";
\&
\&    @attributes = $pdf\->infoMetaAttributes(\*(AqCustomField1\*(Aq);
\&    print "Supported Attributes: @attributes\en";
.Ve
.ie n .IP "$xml = $pdf\->xmpMetadata($xml)" 4
.el .IP "\f(CW$xml\fR = \f(CW$pdf\fR\->xmpMetadata($xml)" 4
.IX Item "$xml = $pdf->xmpMetadata($xml)"
Gets/sets the \s-1XMP XML\s0 data stream.
.Sp
\&\fBExample:\fR
.Sp
.Vb 10
\&    $xml = $pdf\->xmpMetadata();
\&    print "PDFs Metadata reads: $xml\en";
\&    $xml=<<EOT;
\&    <?xpacket begin=\*(Aq\*(Aq id=\*(AqW5M0MpCehiHzreSzNTczkc9d\*(Aq?>
\&    <?adobe\-xap\-filters esc="CRLF"?>
\&    <x:xmpmeta
\&      xmlns:x=\*(Aqadobe:ns:meta/\*(Aq
\&      x:xmptk=\*(AqXMP toolkit 2.9.1\-14, framework 1.6\*(Aq>
\&        <rdf:RDF
\&          xmlns:rdf=\*(Aqhttp://www.w3.org/1999/02/22\-rdf\-syntax\-ns#\*(Aq
\&          xmlns:iX=\*(Aqhttp://ns.adobe.com/iX/1.0/\*(Aq>
\&            <rdf:Description
\&              rdf:about=\*(Aquuid:b8659d3a\-369e\-11d9\-b951\-000393c97fd8\*(Aq
\&              xmlns:pdf=\*(Aqhttp://ns.adobe.com/pdf/1.3/\*(Aq
\&              pdf:Producer=\*(AqAcrobat Distiller 6.0.1 for Macintosh\*(Aq></rdf:Description>
\&            <rdf:Description
\&              rdf:about=\*(Aquuid:b8659d3a\-369e\-11d9\-b951\-000393c97fd8\*(Aq
\&              xmlns:xap=\*(Aqhttp://ns.adobe.com/xap/1.0/\*(Aq
\&              xap:CreateDate=\*(Aq2004\-11\-14T08:41:16Z\*(Aq
\&              xap:ModifyDate=\*(Aq2004\-11\-14T16:38:50\-08:00\*(Aq
\&              xap:CreatorTool=\*(AqFrameMaker 7.0\*(Aq
\&              xap:MetadataDate=\*(Aq2004\-11\-14T16:38:50\-08:00\*(Aq></rdf:Description>
\&            <rdf:Description
\&              rdf:about=\*(Aquuid:b8659d3a\-369e\-11d9\-b951\-000393c97fd8\*(Aq
\&              xmlns:xapMM=\*(Aqhttp://ns.adobe.com/xap/1.0/mm/\*(Aq
\&              xapMM:DocumentID=\*(Aquuid:919b9378\-369c\-11d9\-a2b5\-000393c97fd8\*(Aq/></rdf:Description>
\&            <rdf:Description
\&              rdf:about=\*(Aquuid:b8659d3a\-369e\-11d9\-b951\-000393c97fd8\*(Aq
\&              xmlns:dc=\*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq
\&              dc:format=\*(Aqapplication/pdf\*(Aq>
\&                <dc:description>
\&                  <rdf:Alt>
\&                    <rdf:li xml:lang=\*(Aqx\-default\*(Aq>Adobe Portable Document Format (PDF)</rdf:li>
\&                  </rdf:Alt>
\&                </dc:description>
\&                <dc:creator>
\&                  <rdf:Seq>
\&                    <rdf:li>Adobe Systems Incorporated</rdf:li>
\&                  </rdf:Seq>
\&                </dc:creator>
\&                <dc:title>
\&                  <rdf:Alt>
\&                    <rdf:li xml:lang=\*(Aqx\-default\*(Aq>PDF Reference, version 1.6</rdf:li>
\&                  </rdf:Alt>
\&                </dc:title>
\&            </rdf:Description>
\&        </rdf:RDF>
\&    </x:xmpmeta>
\&    <?xpacket end=\*(Aqw\*(Aq?>
\&    EOT
\&
\&    $xml = $pdf\->xmpMetadata($xml);
\&    print "PDF metadata now reads: $xml\en";
.Ve
.ie n .IP "$pdf\->pageLabel($index, $options)" 4
.el .IP "\f(CW$pdf\fR\->pageLabel($index, \f(CW$options\fR)" 4
.IX Item "$pdf->pageLabel($index, $options)"
Sets page label options.
.Sp
\&\fBSupported Options:\fR
.RS 4
.IP "\-style" 4
.IX Item "-style"
Roman, roman, decimal, Alpha or alpha.
.IP "\-start" 4
.IX Item "-start"
Restart numbering at given number.
.IP "\-prefix" 4
.IX Item "-prefix"
Text prefix for numbering.
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    # Start with Roman Numerals
\&    $pdf\->pageLabel(0, {
\&        \-style => \*(Aqroman\*(Aq,
\&    });
\&
\&    # Switch to Arabic
\&    $pdf\->pageLabel(4, {
\&        \-style => \*(Aqdecimal\*(Aq,
\&    });
\&
\&    # Numbering for Appendix A
\&    $pdf\->pageLabel(32, {
\&        \-start => 1,
\&        \-prefix => \*(AqA\-\*(Aq
\&    });
\&
\&    # Numbering for Appendix B
\&    $pdf\->pageLabel( 36, {
\&        \-start => 1,
\&        \-prefix => \*(AqB\-\*(Aq
\&    });
\&
\&    # Numbering for the Index
\&    $pdf\->pageLabel(40, {
\&        \-style => \*(AqRoman\*(Aq
\&        \-start => 1,
\&        \-prefix => \*(AqIndex \*(Aq
\&    });
.Ve
.RE
.ie n .IP "$pdf\->finishobjects(@objects)" 4
.el .IP "\f(CW$pdf\fR\->finishobjects(@objects)" 4
.IX Item "$pdf->finishobjects(@objects)"
Force objects to be written to file if possible.
.Sp
\&\fBExample:\fR
.Sp
.Vb 5
\&    $pdf = PDF::API2\->new(\-file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->finishobjects($page, $gfx, $txt);
\&    ...
\&    $pdf\->save();
.Ve
.ie n .IP "$pdf\->\fBupdate()\fR" 4
.el .IP "\f(CW$pdf\fR\->\fBupdate()\fR" 4
.IX Item "$pdf->update()"
Saves a previously opened document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::API2\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.ie n .IP "$pdf\->saveas($file)" 4
.el .IP "\f(CW$pdf\fR\->saveas($file)" 4
.IX Item "$pdf->saveas($file)"
Save the document to \f(CW$file\fR and remove the object structure from memory.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::API2\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.ie n .IP "$string = $pdf\->\fBstringify()\fR" 4
.el .IP "\f(CW$string\fR = \f(CW$pdf\fR\->\fBstringify()\fR" 4
.IX Item "$string = $pdf->stringify()"
Return the document as a string and remove the object structure from memory.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::API2\->new();
\&    ...
\&    print $pdf\->stringify();
.Ve
.ie n .IP "$pdf\->\fBend()\fR" 4
.el .IP "\f(CW$pdf\fR\->\fBend()\fR" 4
.IX Item "$pdf->end()"
Remove the object structure from memory.  \s-1PDF::API2\s0 contains circular
references, so this call is necessary in long-running processes to
keep from running out of memory.
.Sp
This will be called automatically when you save or stringify a \s-1PDF.\s0
You should only need to call it explicitly if you are reading \s-1PDF\s0
files and not writing them.
.SH "PAGE METHODS"
.IX Header "PAGE METHODS"
.ie n .IP "$page = $pdf\->\fBpage()\fR" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->\fBpage()\fR" 4
.IX Item "$page = $pdf->page()"
.PD 0
.ie n .IP "$page = $pdf\->page($page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->page($page_number)" 4
.IX Item "$page = $pdf->page($page_number)"
.PD
Returns a new page object.  By default, the page is added to the end
of the document.  If you include an existing page number, the new page
will be inserted in that position, pushing existing pages back.
.Sp
If \f(CW$page_number\fR is \-1, the new page is inserted as the second-last page;
if \f(CW$page_number\fR is 0, the new page is inserted as the last page.
.Sp
\&\fBExample:\fR
.Sp
.Vb 1
\&    $pdf = PDF::API2\->new();
\&
\&    # Add a page.  This becomes page 1.
\&    $page = $pdf\->page();
\&
\&    # Add a new first page.  $page becomes page 2.
\&    $another_page = $pdf\->page(1);
.Ve
.ie n .IP "$page = $pdf\->openpage($page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->openpage($page_number)" 4
.IX Item "$page = $pdf->openpage($page_number)"
Returns the PDF::API2::Page object of page \f(CW$page_number\fR.
.Sp
If \f(CW$page_number\fR is 0 or \-1, it will return the last page in the
document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 5
\&    $pdf = PDF::API2\->open(\*(Aqour/99page.pdf\*(Aq);
\&    $page = $pdf\->openpage(1);   # returns the first page
\&    $page = $pdf\->openpage(99);  # returns the last page
\&    $page = $pdf\->openpage(\-1);  # returns the last page
\&    $page = $pdf\->openpage(999); # returns undef
.Ve
.ie n .IP "$xoform = $pdf\->importPageIntoForm($source_pdf, $source_page_number)" 4
.el .IP "\f(CW$xoform\fR = \f(CW$pdf\fR\->importPageIntoForm($source_pdf, \f(CW$source_page_number\fR)" 4
.IX Item "$xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)"
Returns a Form XObject created by extracting the specified page from \f(CW$source_pdf\fR.
.Sp
This is useful if you want to transpose the imported page somewhat
differently onto a page (e.g. two-up, four-up, etc.).
.Sp
If \f(CW$source_page_number\fR is 0 or \-1, it will return the last page in the
document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $pdf = PDF::API2\->new();
\&    $old = PDF::API2\->open(\*(Aqour/old.pdf\*(Aq);
\&    $page = $pdf\->page();
\&    $gfx = $page\->gfx();
\&
\&    # Import Page 2 from the old PDF
\&    $xo = $pdf\->importPageIntoForm($old, 2);
\&
\&    # Add it to the new PDF\*(Aqs first page at 1/2 scale
\&    $gfx\->formimage($xo, 0, 0, 0.5);
\&
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.Sp
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.ie n .IP "$page = $pdf\->import_page($source_pdf, $source_page_number, $target_page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->import_page($source_pdf, \f(CW$source_page_number\fR, \f(CW$target_page_number\fR)" 4
.IX Item "$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)"
Imports a page from \f(CW$source_pdf\fR and adds it to the specified position
in \f(CW$pdf\fR.
.Sp
If \f(CW$source_page_number\fR or \f(CW$target_page_number\fR is 0 or \-1, the last
page in the document is used.
.Sp
\&\fBNote:\fR If you pass a page object instead of a page number for
\&\f(CW$target_page_number\fR, the contents of the page will be merged into the
existing page.
.Sp
\&\fBExample:\fR
.Sp
.Vb 2
\&    $pdf = PDF::API2\->new();
\&    $old = PDF::API2\->open(\*(Aqour/old.pdf\*(Aq);
\&
\&    # Add page 2 from the old PDF as page 1 of the new PDF
\&    $page = $pdf\->import_page($old, 2);
\&
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.Sp
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.ie n .IP "$count = $pdf\->\fBpages()\fR" 4
.el .IP "\f(CW$count\fR = \f(CW$pdf\fR\->\fBpages()\fR" 4
.IX Item "$count = $pdf->pages()"
Returns the number of pages in the document.
.ie n .IP "($llx, $lly, $urx, $ury) = $pdf\->\fBmediabox()\fR" 4
.el .IP "($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR) = \f(CW$pdf\fR\->\fBmediabox()\fR" 4
.IX Item "($llx, $lly, $urx, $ury) = $pdf->mediabox()"
.PD 0
.ie n .IP "$pdf\->mediabox($name)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($name)" 4
.IX Item "$pdf->mediabox($name)"
.ie n .IP "$pdf\->mediabox($w, $h)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($w, \f(CW$h\fR)" 4
.IX Item "$pdf->mediabox($w, $h)"
.ie n .IP "$pdf\->mediabox($llx, $lly, $urx, $ury)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR)" 4
.IX Item "$pdf->mediabox($llx, $lly, $urx, $ury)"
.PD
Get or set the global mediabox.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $pdf = PDF::API2\->new();
\&    $pdf\->mediabox(\*(AqA4\*(Aq);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::API2\->new();
\&    $pdf\->mediabox(595, 842);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::API2\->new;
\&    $pdf\->mediabox(0, 0, 595, 842);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.ie n .IP "($llx, $lly, $urx, $ury) = $pdf\->\fBcropbox()\fR" 4
.el .IP "($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR) = \f(CW$pdf\fR\->\fBcropbox()\fR" 4
.IX Item "($llx, $lly, $urx, $ury) = $pdf->cropbox()"
.PD 0
.ie n .IP "$pdf\->cropbox($name)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($name)" 4
.IX Item "$pdf->cropbox($name)"
.ie n .IP "$pdf\->cropbox($w, $h)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($w, \f(CW$h\fR)" 4
.IX Item "$pdf->cropbox($w, $h)"
.ie n .IP "$pdf\->cropbox($llx, $lly, $urx, $ury)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR)" 4
.IX Item "$pdf->cropbox($llx, $lly, $urx, $ury)"
.PD
Get or set the global cropbox.
.Sp
The cropbox defaults to the mediabox.
.ie n .IP "($llx, $lly, $urx, $ury) = $pdf\->\fBbleedbox()\fR" 4
.el .IP "($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR) = \f(CW$pdf\fR\->\fBbleedbox()\fR" 4
.IX Item "($llx, $lly, $urx, $ury) = $pdf->bleedbox()"
.PD 0
.ie n .IP "$pdf\->bleedbox($name)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($name)" 4
.IX Item "$pdf->bleedbox($name)"
.ie n .IP "$pdf\->bleedbox($w, $h)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($w, \f(CW$h\fR)" 4
.IX Item "$pdf->bleedbox($w, $h)"
.ie n .IP "$pdf\->bleedbox($llx, $lly, $urx, $ury)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR)" 4
.IX Item "$pdf->bleedbox($llx, $lly, $urx, $ury)"
.PD
Get or set the global bleedbox.
.Sp
The bleedbox defaults to the cropbox.
.ie n .IP "($llx, $lly, $urx, $ury) = $pdf\->\fBtrimbox()\fR" 4
.el .IP "($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR) = \f(CW$pdf\fR\->\fBtrimbox()\fR" 4
.IX Item "($llx, $lly, $urx, $ury) = $pdf->trimbox()"
.PD 0
.ie n .IP "$pdf\->trimbox($name)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($name)" 4
.IX Item "$pdf->trimbox($name)"
.ie n .IP "$pdf\->trimbox($w, $h)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($w, \f(CW$h\fR)" 4
.IX Item "$pdf->trimbox($w, $h)"
.ie n .IP "$pdf\->trimbox($llx, $lly, $urx, $ury)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR)" 4
.IX Item "$pdf->trimbox($llx, $lly, $urx, $ury)"
.PD
Get or set the global trimbox.
.Sp
The trimbox defaults to the cropbox.
.ie n .IP "($llx, $lly, $urx, $ury) = $pdf\->\fBartbox()\fR" 4
.el .IP "($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR) = \f(CW$pdf\fR\->\fBartbox()\fR" 4
.IX Item "($llx, $lly, $urx, $ury) = $pdf->artbox()"
.PD 0
.ie n .IP "$pdf\->artbox($name)" 4
.el .IP "\f(CW$pdf\fR\->artbox($name)" 4
.IX Item "$pdf->artbox($name)"
.ie n .IP "$pdf\->artbox($w, $h)" 4
.el .IP "\f(CW$pdf\fR\->artbox($w, \f(CW$h\fR)" 4
.IX Item "$pdf->artbox($w, $h)"
.ie n .IP "$pdf\->artbox($llx, $lly, $urx, $ury)" 4
.el .IP "\f(CW$pdf\fR\->artbox($llx, \f(CW$lly\fR, \f(CW$urx\fR, \f(CW$ury\fR)" 4
.IX Item "$pdf->artbox($llx, $lly, $urx, $ury)"
.PD
Get or sets the global artbox.
.Sp
The artbox defaults to the cropbox.
.SH "FONT METHODS"
.IX Header "FONT METHODS"
.ie n .IP "@directories = PDF::API2::addFontDirs($dir1, $dir2, ...)" 4
.el .IP "\f(CW@directories\fR = PDF::API2::addFontDirs($dir1, \f(CW$dir2\fR, ...)" 4
.IX Item "@directories = PDF::API2::addFontDirs($dir1, $dir2, ...)"
Adds one or more directories to the search path for finding font
files.
.Sp
Returns the list of searched directories.
.ie n .IP "$font = $pdf\->corefont($fontname, [%options])" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->corefont($fontname, [%options])" 4
.IX Item "$font = $pdf->corefont($fontname, [%options])"
Returns a new Adobe core font object.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 4
\&    $font = $pdf\->corefont(\*(AqTimes\-Roman\*(Aq);
\&    $font = $pdf\->corefont(\*(AqTimes\-Bold\*(Aq);
\&    $font = $pdf\->corefont(\*(AqHelvetica\*(Aq);
\&    $font = $pdf\->corefont(\*(AqZapfDingbats\*(Aq);
.Ve
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.IP "\-dokern" 4
.IX Item "-dokern"
Enables kerning if data is available.
.RE
.RS 4
.Sp
See Also: PDF::API2::Resource::Font::CoreFont.
.RE
.ie n .IP "$font = $pdf\->psfont($ps_file, [%options])" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->psfont($ps_file, [%options])" 4
.IX Item "$font = $pdf->psfont($ps_file, [%options])"
Returns a new Adobe Type1 font object.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&    $font = $pdf\->psfont(\*(AqTimes\-Book.pfa\*(Aq, \-afmfile => \*(AqTimes\-Book.afm\*(Aq);
\&    $font = $pdf\->psfont(\*(Aq/fonts/Synest\-FB.pfb\*(Aq, \-pfmfile => \*(Aq/fonts/Synest\-FB.pfm\*(Aq);
.Ve
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.IP "\-afmfile" 4
.IX Item "-afmfile"
Specifies the location of the font metrics file.
.IP "\-pfmfile" 4
.IX Item "-pfmfile"
Specifies the location of the printer font metrics file.  This option
overrides the \-encode option.
.IP "\-dokern" 4
.IX Item "-dokern"
Enables kerning if data is available.
.RE
.RS 4
.RE
.ie n .IP "$font = $pdf\->ttfont($ttf_file, [%options])" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->ttfont($ttf_file, [%options])" 4
.IX Item "$font = $pdf->ttfont($ttf_file, [%options])"
Returns a new TrueType or OpenType font object.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&    $font = $pdf\->ttfont(\*(AqTimes.ttf\*(Aq);
\&    $font = $pdf\->ttfont(\*(AqGeorgia.otf\*(Aq);
.Ve
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.IP "\-isocmap" 4
.IX Item "-isocmap"
Use the \s-1ISO\s0 Unicode Map instead of the default \s-1MS\s0 Unicode Map.
.IP "\-dokern" 4
.IX Item "-dokern"
Enables kerning if data is available.
.IP "\-noembed" 4
.IX Item "-noembed"
Disables embedding of the font file.
.RE
.RS 4
.RE
.ie n .IP "$font = $pdf\->cjkfont($cjkname, [%options])" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->cjkfont($cjkname, [%options])" 4
.IX Item "$font = $pdf->cjkfont($cjkname, [%options])"
Returns a new \s-1CJK\s0 font object.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&    $font = $pdf\->cjkfont(\*(Aqkorean\*(Aq);
\&    $font = $pdf\->cjkfont(\*(Aqtraditional\*(Aq);
.Ve
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.RE
.RS 4
.Sp
See Also: PDF::API2::Resource::CIDFont::CJKFont
.RE
.ie n .IP "$font = $pdf\->synfont($basefont, [%options])" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->synfont($basefont, [%options])" 4
.IX Item "$font = $pdf->synfont($basefont, [%options])"
Returns a new synthetic font object.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 4
\&    $cf  = $pdf\->corefont(\*(AqTimes\-Roman\*(Aq, \-encode => \*(Aqlatin1\*(Aq);
\&    $sf  = $pdf\->synfont($cf, \-slant => 0.85);  # compressed 85%
\&    $sfb = $pdf\->synfont($cf, \-bold => 1);      # embolden by 10em
\&    $sfi = $pdf\->synfont($cf, \-oblique => \-12); # italic at \-12 degrees
.Ve
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-slant" 4
.IX Item "-slant"
Slant/expansion factor (0.1\-0.9 = slant, 1.1+ = expansion).
.IP "\-oblique" 4
.IX Item "-oblique"
Italic angle (+/\-)
.IP "\-bold" 4
.IX Item "-bold"
Emboldening factor (0.1+, bold = 1, heavy = 2, ...)
.IP "\-space" 4
.IX Item "-space"
Additional character spacing in ems (0\-1000)
.RE
.RS 4
.Sp
See Also: PDF::API2::Resource::Font::SynFont
.RE
.ie n .IP "$font = $pdf\->bdfont($bdf_file)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->bdfont($bdf_file)" 4
.IX Item "$font = $pdf->bdfont($bdf_file)"
Returns a new \s-1BDF\s0 font object, based on the specified Adobe \s-1BDF\s0 file.
.Sp
See Also: PDF::API2::Resource::Font::BdFont
.ie n .IP "$font = $pdf\->unifont(@fontspecs, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->unifont(@fontspecs, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->unifont(@fontspecs, %options)"
Returns a new uni-font object, based on the specified fonts and options.
.Sp
\&\fB\s-1BEWARE:\s0\fR This is not a true pdf-object, but a virtual/abstract font definition!
.Sp
See Also: PDF::API2::Resource::UniFont.
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.RE
.RS 4
.RE
.SH "IMAGE METHODS"
.IX Header "IMAGE METHODS"
.ie n .IP "$jpeg = $pdf\->image_jpeg($file)" 4
.el .IP "\f(CW$jpeg\fR = \f(CW$pdf\fR\->image_jpeg($file)" 4
.IX Item "$jpeg = $pdf->image_jpeg($file)"
Imports and returns a new \s-1JPEG\s0 image object.  \f(CW$file\fR may be either a filename or a filehandle.
.ie n .IP "$tiff = $pdf\->image_tiff($file)" 4
.el .IP "\f(CW$tiff\fR = \f(CW$pdf\fR\->image_tiff($file)" 4
.IX Item "$tiff = $pdf->image_tiff($file)"
Imports and returns a new \s-1TIFF\s0 image object.  \f(CW$file\fR may be either a filename or a filehandle.
.ie n .IP "$pnm = $pdf\->image_pnm($file)" 4
.el .IP "\f(CW$pnm\fR = \f(CW$pdf\fR\->image_pnm($file)" 4
.IX Item "$pnm = $pdf->image_pnm($file)"
Imports and returns a new \s-1PNM\s0 image object.  \f(CW$file\fR may be either a filename or a filehandle.
.ie n .IP "$png = $pdf\->image_png($file)" 4
.el .IP "\f(CW$png\fR = \f(CW$pdf\fR\->image_png($file)" 4
.IX Item "$png = $pdf->image_png($file)"
Imports and returns a new \s-1PNG\s0 image object.  \f(CW$file\fR may be either a filename or a filehandle.
.Sp
Note: \s-1PNG\s0 files that include an alpha (transparency) channel go through a
relatively slow process of separating the transparency channel into a \s-1PDF\s0 SMask
object.  Install \s-1PDF::API2::XS\s0 or Image::PNG::Libpng to speed this up by an
order of magnitude.
.ie n .IP "$gif = $pdf\->image_gif($file)" 4
.el .IP "\f(CW$gif\fR = \f(CW$pdf\fR\->image_gif($file)" 4
.IX Item "$gif = $pdf->image_gif($file)"
Imports and returns a new \s-1GIF\s0 image object.  \f(CW$file\fR may be either a filename or a filehandle.
.ie n .IP "$gdf = $pdf\->image_gd($gd_object, %options)" 4
.el .IP "\f(CW$gdf\fR = \f(CW$pdf\fR\->image_gd($gd_object, \f(CW%options\fR)" 4
.IX Item "$gdf = $pdf->image_gd($gd_object, %options)"
Imports and returns a new image object from GD::Image.
.Sp
\&\fBOptions:\fR The only option currently supported is \f(CW\*(C`\-lossless => 1\*(C'\fR.
.SH "COLORSPACE METHODS"
.IX Header "COLORSPACE METHODS"
.ie n .IP "$cs = $pdf\->colorspace_act($file)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_act($file)" 4
.IX Item "$cs = $pdf->colorspace_act($file)"
Returns a new colorspace object based on an Adobe Color Table file.
.Sp
See PDF::API2::Resource::ColorSpace::Indexed::ACTFile for a
reference to the file format's specification.
.ie n .IP "$cs = $pdf\->\fBcolorspace_web()\fR" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->\fBcolorspace_web()\fR" 4
.IX Item "$cs = $pdf->colorspace_web()"
Returns a new colorspace-object based on the web color palette.
.ie n .IP "$cs = $pdf\->\fBcolorspace_hue()\fR" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->\fBcolorspace_hue()\fR" 4
.IX Item "$cs = $pdf->colorspace_hue()"
Returns a new colorspace-object based on the hue color palette.
.Sp
See PDF::API2::Resource::ColorSpace::Indexed::Hue for an explanation.
.ie n .IP "$cs = $pdf\->colorspace_separation($tint, $color)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_separation($tint, \f(CW$color\fR)" 4
.IX Item "$cs = $pdf->colorspace_separation($tint, $color)"
Returns a new separation colorspace object based on the parameters.
.Sp
\&\fI\f(CI$tint\fI\fR can be any valid ink identifier, including but not limited
to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
\&'Orange'.
.Sp
\&\fI\f(CI$color\fI\fR must be a valid color specification limited to: '#rrggbb',
\&'!hhssvv', '%ccmmyykk' or a \*(L"named color\*(R" (rgb).
.Sp
The colorspace model will automatically be chosen based on the
specified color.
.ie n .IP "$cs = $pdf\->colorspace_devicen(\e@tintCSx, [$samples])" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_devicen(\e@tintCSx, [$samples])" 4
.IX Item "$cs = $pdf->colorspace_devicen(@tintCSx, [$samples])"
Returns a new DeviceN colorspace object based on the parameters.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $cy = $pdf\->colorspace_separation(\*(AqCyan\*(Aq,    \*(Aq%f000\*(Aq);
\&    $ma = $pdf\->colorspace_separation(\*(AqMagenta\*(Aq, \*(Aq%0f00\*(Aq);
\&    $ye = $pdf\->colorspace_separation(\*(AqYellow\*(Aq,  \*(Aq%00f0\*(Aq);
\&    $bk = $pdf\->colorspace_separation(\*(AqBlack\*(Aq,   \*(Aq%000f\*(Aq);
\&
\&    $pms023 = $pdf\->colorspace_separation(\*(AqPANTONE 032CV\*(Aq, \*(Aq%0ff0\*(Aq);
\&
\&    $dncs = $pdf\->colorspace_devicen( [ $cy,$ma,$ye,$bk,$pms023 ] );
.Ve
.Sp
The colorspace model will automatically be chosen based on the first
colorspace specified.
.SH "BARCODE METHODS"
.IX Header "BARCODE METHODS"
.ie n .IP "$bc = $pdf\->xo_codabar(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_codabar(%options)" 4
.IX Item "$bc = $pdf->xo_codabar(%options)"
.PD 0
.ie n .IP "$bc = $pdf\->xo_code128(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_code128(%options)" 4
.IX Item "$bc = $pdf->xo_code128(%options)"
.ie n .IP "$bc = $pdf\->xo_2of5int(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_2of5int(%options)" 4
.IX Item "$bc = $pdf->xo_2of5int(%options)"
.ie n .IP "$bc = $pdf\->xo_3of9(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_3of9(%options)" 4
.IX Item "$bc = $pdf->xo_3of9(%options)"
.ie n .IP "$bc = $pdf\->xo_ean13(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_ean13(%options)" 4
.IX Item "$bc = $pdf->xo_ean13(%options)"
.PD
Creates the specified barcode object as a form XObject.
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.ie n .IP "$xo = $pdf\->\fBxo_form()\fR" 4
.el .IP "\f(CW$xo\fR = \f(CW$pdf\fR\->\fBxo_form()\fR" 4
.IX Item "$xo = $pdf->xo_form()"
Returns a new form XObject.
.ie n .IP "$egs = $pdf\->\fBegstate()\fR" 4
.el .IP "\f(CW$egs\fR = \f(CW$pdf\fR\->\fBegstate()\fR" 4
.IX Item "$egs = $pdf->egstate()"
Returns a new extended graphics state object.
.ie n .IP "$obj = $pdf\->\fBpattern()\fR" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->\fBpattern()\fR" 4
.IX Item "$obj = $pdf->pattern()"
Returns a new pattern object.
.ie n .IP "$obj = $pdf\->\fBshading()\fR" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->\fBshading()\fR" 4
.IX Item "$obj = $pdf->shading()"
Returns a new shading object.
.ie n .IP "$otls = $pdf\->\fBoutlines()\fR" 4
.el .IP "\f(CW$otls\fR = \f(CW$pdf\fR\->\fBoutlines()\fR" 4
.IX Item "$otls = $pdf->outlines()"
Returns a new or existing outlines object.
.SH "SUPPORTED PERL VERSIONS"
.IX Header "SUPPORTED PERL VERSIONS"
\&\s-1PDF::API2\s0 will aim to support all major Perl versions that were released in the
past six years, plus one, in order to continue working for the life of most
long-term-stable (\s-1LTS\s0) server distributions.
.PP
For example, a version of \s-1PDF::API2\s0 released on 2018\-01\-01 would support the
last major version of Perl released before 2012\-01\-01, which happens to be 5.14.
.PP
If you need to use this module on a server with an extremely out-of-date version
of Perl, consider using either plenv or Perlbrew to run a newer version of Perl
without needing admin privileges.
.SH "KNOWN ISSUES"
.IX Header "KNOWN ISSUES"
This module does not work with perl's \-l command-line switch.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1PDF::API2\s0 was originally written by Alfred Reibenschuh, extending code written
by Martin Hosken.
.PP
It is currently being maintained and developed by Steve Simms.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software: you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
Software Foundation, either version 2.1 of the License, or (at your option) any
later version.
.PP
This library is distributed in the hope that it will be useful, but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0 Lesser General Public License for more details.