.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "2023-09-29" "perl v5.36.0" "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 \- Create, modify, and examine 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\->open_page($page_number);
\&
\&    # Set the page size
\&    $page\->size(\*(AqLetter\*(Aq);
\&
\&    # Add a built\-in font to the PDF
\&    $font = $pdf\->font(\*(AqHelvetica\-Bold\*(Aq);
\&
\&    # Add an external TrueType font to the PDF
\&    $font = $pdf\->font(\*(Aq/path/to/font.ttf\*(Aq);
\&
\&    # Add some text to the page
\&    $text = $page\->text();
\&    $text\->font($font, 20);
\&    $text\->position(200, 700);
\&    $text\->text(\*(AqHello World!\*(Aq);
\&
\&    # Save the PDF
\&    $pdf\->save(\*(Aq/path/to/new.pdf\*(Aq);
.Ve
.SH "INPUT/OUTPUT METHODS"
.IX Header "INPUT/OUTPUT METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $pdf = PDF::API2\->new(%options);
.Ve
.PP
Create a new \s-1PDF.\s0
.PP
The following options are available:
.IP "\(bu" 4
file
.Sp
If you will be saving the \s-1PDF\s0 to disk and already know the filename, you can
include it here to open the file for writing immediately.  \f(CW\*(C`file\*(C'\fR may also be
a filehandle.
.IP "\(bu" 4
compress
.Sp
By default, most of the \s-1PDF\s0 will be compressed to save space.  To turn this off
(generally only useful for testing or debugging), set \f(CW\*(C`compress\*(C'\fR to 0.
.SS "open"
.IX Subsection "open"
.Vb 1
\&    my $pdf = PDF::API2\->open(\*(Aq/path/to/file.pdf\*(Aq, %options);
.Ve
.PP
Open an existing \s-1PDF\s0 file.
.PP
The following option is available:
.IP "\(bu" 4
compress
.Sp
By default, most of the \s-1PDF\s0 will be compressed to save space.  To turn this off
(generally only useful for testing or debugging), set \f(CW\*(C`compress\*(C'\fR to 0.
.SS "save"
.IX Subsection "save"
.Vb 1
\&    $pdf\->save(\*(Aq/path/to/file.pdf\*(Aq);
.Ve
.PP
Write the \s-1PDF\s0 to disk and close the file.  A filename is optional if one was
specified while opening or creating the \s-1PDF.\s0
.PP
As a side effect, the document structure is removed from memory when the file is
saved, so it will no longer be usable.
.SS "close"
.IX Subsection "close"
.Vb 1
\&    $pdf\->close();
.Ve
.PP
Close an open file (if relevant) and remove the object structure from memory.
.PP
\&\s-1PDF::API2\s0 contains circular references, so this call is necessary in
long-running processes to keep from running out of memory.
.PP
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.
.SS "from_string"
.IX Subsection "from_string"
.Vb 1
\&    my $pdf = PDF::API2\->from_string($pdf_string, %options);
.Ve
.PP
Read a \s-1PDF\s0 document contained in a string.
.PP
The following option is available:
.IP "\(bu" 4
compress
.Sp
By default, most of the \s-1PDF\s0 will be compressed to save space.  To turn this off
(generally only useful for testing or debugging), set \f(CW\*(C`compress\*(C'\fR to 0.
.SS "to_string"
.IX Subsection "to_string"
.Vb 1
\&    my $string = $pdf\->to_string();
.Ve
.PP
Return the \s-1PDF\s0 document as a string.
.PP
As a side effect, the document structure is removed from memory when the string
is created, so it will no longer be usable.
.SH "METADATA METHODS"
.IX Header "METADATA METHODS"
.SS "title"
.IX Subsection "title"
.Vb 2
\&    $title = $pdf\->title();
\&    $pdf = $pdf\->title($title);
.Ve
.PP
Get/set/clear the document's title.
.SS "author"
.IX Subsection "author"
.Vb 2
\&    $author = $pdf\->author();
\&    $pdf = $pdf\->author($author);
.Ve
.PP
Get/set/clear the name of the person who created the document.
.SS "subject"
.IX Subsection "subject"
.Vb 2
\&    $subject = $pdf\->subject();
\&    $pdf = $pdf\->subject($subject);
.Ve
.PP
Get/set/clear the subject of the document.
.SS "keywords"
.IX Subsection "keywords"
.Vb 2
\&    $keywords = $pdf\->keywords();
\&    $pdf = $pdf\->keywords($keywords);
.Ve
.PP
Get/set/clear a space-separated string of keywords associated with the document.
.SS "creator"
.IX Subsection "creator"
.Vb 2
\&    $creator = $pdf\->creator();
\&    $pdf = $pdf\->creator($creator);
.Ve
.PP
Get/set/clear the name of the product that created the document prior to its
conversion to \s-1PDF.\s0
.SS "producer"
.IX Subsection "producer"
.Vb 2
\&    $producer = $pdf\->producer();
\&    $pdf = $pdf\->producer($producer);
.Ve
.PP
Get/set/clear the name of the product that converted the original document to
\&\s-1PDF.\s0
.PP
\&\s-1PDF::API2\s0 fills in this field when creating a \s-1PDF.\s0
.SS "created"
.IX Subsection "created"
.Vb 2
\&    $date = $pdf\->created();
\&    $pdf = $pdf\->created($date);
.Ve
.PP
Get/set/clear the document's creation date.
.PP
The date format is \f(CW\*(C`D:YYYYMMDDHHmmSSOHH\*(Aqmm\*(C'\fR, where \f(CW\*(C`D:\*(C'\fR is a static prefix
identifying the string as a \s-1PDF\s0 date.  The date may be truncated at any point
after the year.  \f(CW\*(C`O\*(C'\fR is one of \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, or \f(CW\*(C`Z\*(C'\fR, with the following \f(CW\*(C`HH\*(Aqmm\*(C'\fR
representing an offset from \s-1UTC.\s0
.PP
When setting the date, \f(CW\*(C`D:\*(C'\fR will be prepended automatically if omitted.
.SS "modified"
.IX Subsection "modified"
.Vb 2
\&    $date = $pdf\->modified();
\&    $pdf = $pdf\->modified($date);
.Ve
.PP
Get/set/clear the document's modification date.  The date format is as described
in \f(CW\*(C`created\*(C'\fR above.
.SS "info_metadata"
.IX Subsection "info_metadata"
.Vb 2
\&    # Get all keys and values
\&    %info = $pdf\->info_metadata();
\&
\&    # Get the value of one key
\&    $value = $pdf\->info_metadata($key);
\&
\&    # Set the value of one key
\&    $pdf = $pdf\->info_metadata($key, $value);
.Ve
.PP
Get/set/clear a key in the document's information dictionary.  The standard keys
(title, author, etc.) have their own accessors, so this is primarily intended
for interacting with custom metadata.
.PP
Pass \f(CW\*(C`undef\*(C'\fR as the value in order to remove the key from the dictionary.
.SS "xml_metadata"
.IX Subsection "xml_metadata"
.Vb 2
\&    $xml = $pdf\->xml_metadata();
\&    $pdf = $pdf\->xml_metadata($xml);
.Ve
.PP
Get/set the document's \s-1XML\s0 metadata stream.
.SS "version"
.IX Subsection "version"
.Vb 1
\&    $version = $pdf\->version($new_version);
.Ve
.PP
Get/set the \s-1PDF\s0 version (e.g. 1.4).
.SS "is_encrypted"
.IX Subsection "is_encrypted"
.Vb 1
\&    $boolean = $pdf\->is_encrypted();
.Ve
.PP
Returns true if the opened \s-1PDF\s0 is encrypted.
.SH "INTERACTIVE FEATURE METHODS"
.IX Header "INTERACTIVE FEATURE METHODS"
.SS "outline"
.IX Subsection "outline"
.Vb 1
\&    $outline = $pdf\->outlines();
.Ve
.PP
Creates (if needed) and returns the document's outline tree, which is also known
as its bookmarks or the table of contents, depending on the \s-1PDF\s0 reader.
.PP
To examine or modify the outline tree, see PDF::API2::Outline.
.SS "open_action"
.IX Subsection "open_action"
.Vb 1
\&    $pdf = $pdf\->open_action($page, $location, @args);
.Ve
.PP
Set the destination in the \s-1PDF\s0 that should be displayed when the document is
opened.
.PP
\&\f(CW$page\fR may be either a page number or a page object.  The other parameters are
as described in PDF::API2::NamedDestination.
.SS "page_layout"
.IX Subsection "page_layout"
.Vb 2
\&    $layout = $pdf\->page_layout();
\&    $pdf = $pdf\->page_layout($layout);
.Ve
.PP
Get/set the page layout that should be used when the \s-1PDF\s0 is opened.
.PP
\&\f(CW$layout\fR is one of the following:
.IP "\(bu" 4
single_page (or undef)
.Sp
Display one page at a time.
.IP "\(bu" 4
one_column
.Sp
Display the pages in one column (a.k.a. continuous).
.IP "\(bu" 4
two_column_left
.Sp
Display the pages in two columns, with odd-numbered pages on the left.
.IP "\(bu" 4
two_column_right
.Sp
Display the pages in two columns, with odd-numbered pages on the right.
.IP "\(bu" 4
two_page_left
.Sp
Display two pages at a time, with odd-numbered pages on the left.
.IP "\(bu" 4
two_page_right
.Sp
Display two pages at a time, with odd-numbered pages on the right.
.SS "page_mode"
.IX Subsection "page_mode"
.Vb 2
\&    # Get
\&    $mode = $pdf\->page_mode();
\&
\&    # Set
\&    $pdf = $pdf\->page_mode($mode);
.Ve
.PP
Get/set the page mode, which describes how the \s-1PDF\s0 should be displayed when
opened.
.PP
\&\f(CW$mode\fR is one of the following:
.IP "\(bu" 4
none (or undef)
.Sp
Neither outlines nor thumbnails should be displayed.
.IP "\(bu" 4
outlines
.Sp
Show the document outline.
.IP "\(bu" 4
thumbnails
.Sp
Show the page thumbnails.
.IP "\(bu" 4
full_screen
.Sp
Open in full-screen mode, with no menu bar, window controls, or any other window
visible.
.IP "\(bu" 4
optional_content
.Sp
Show the optional content group panel.
.IP "\(bu" 4
attachments
.Sp
Show the attachments panel.
.SS "viewer_preferences"
.IX Subsection "viewer_preferences"
.Vb 2
\&    # Get
\&    %preferences = $pdf\->viewer_preferences();
\&
\&    # Set
\&    $pdf = $pdf\->viewer_preferences(%preferences);
.Ve
.PP
Get or set \s-1PDF\s0 viewer preferences, as described in
PDF::API2::ViewerPreferences.
.SH "PAGE METHODS"
.IX Header "PAGE METHODS"
.SS "page"
.IX Subsection "page"
.Vb 2
\&     # Add a page to the end of the document
\&     $page = $pdf\->page();
\&
\&     # Insert a page before the specified page number
\&     $page = $pdf\->page($page_number);
.Ve
.PP
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.
.PP
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.
.SS "open_page"
.IX Subsection "open_page"
.Vb 1
\&    $page = $pdf\->open_page($page_number);
.Ve
.PP
Returns the PDF::API2::Page object of page \f(CW$page_number\fR, if it exists.
.PP
If \f(CW$page_number\fR is 0 or \-1, it will return the last page in the document.
.SS "import_page"
.IX Subsection "import_page"
.Vb 1
\&    $page = $pdf\->import_page($source_pdf, $source_page_num, $target_page_num);
.Ve
.PP
Imports a page from \f(CW$source_pdf\fR and adds it to the specified position in
\&\f(CW$pdf\fR.
.PP
If \f(CW$source_page_num\fR or \f(CW$target_page_num\fR is 0, \-1, or unspecified, the last
page in the document is used.
.PP
\&\fBNote:\fR If you pass a page object instead of a page number for
\&\f(CW$target_page_num\fR, the contents of the page will be merged into the existing
page.
.PP
\&\fBExample:\fR
.PP
.Vb 2
\&    my $pdf = PDF::API2\->new();
\&    my $source = PDF::API2\->open(\*(Aqsource.pdf\*(Aq);
\&
\&    # Add page 2 from the source PDF as page 1 of the new PDF
\&    my $page = $pdf\->import_page($source, 2);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.SS "embed_page"
.IX Subsection "embed_page"
.Vb 1
\&    $xobject = $pdf\->embed_page($source_pdf, $source_page_number);
.Ve
.PP
Returns a Form XObject created by extracting the specified page from a
\&\f(CW$source_pdf\fR.
.PP
This is useful if you want to transpose the imported page somewhat differently
onto a page (e.g. two-up, four-up, etc.).
.PP
If \f(CW$source_page_number\fR is 0 or \-1, it will return the last page in the document.
.PP
\&\fBExample:\fR
.PP
.Vb 3
\&    my $pdf = PDF::API2\->new();
\&    my $source = PDF::API2\->open(\*(Aqsource.pdf\*(Aq);
\&    my $page = $pdf\->page();
\&
\&    # Import Page 2 from the source PDF
\&    my $object = $pdf\->embed_page($source, 2);
\&
\&    # Add it to the new PDF\*(Aqs first page at 1/2 scale
\&    my ($x, $y) = (0, 0);
\&    $page\->object($object, $x, $y, 0.5);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.SS "page_count"
.IX Subsection "page_count"
.Vb 1
\&    $integer = $pdf\->page_count();
.Ve
.PP
Return the number of pages in the document.
.SS "page_labels"
.IX Subsection "page_labels"
.Vb 1
\&    $pdf = $pdf\->page_labels($page_number, %options);
.Ve
.PP
Describes how pages should be numbered beginning at the specified page number.
.PP
.Vb 3
\&    # Generate a 30\-page PDF
\&    my $pdf = PDF::API2\->new();
\&    $pdf\->page() for 1..30;
\&
\&    # Number pages i to v, 1 to 20, and A\-1 to A\-5, respectively
\&    $pdf\->page_labels(1, style => \*(Aqroman\*(Aq);
\&    $pdf\->page_labels(6, style => \*(Aqdecimal\*(Aq);
\&    $pdf\->page_labels(26, style => \*(Aqdecimal\*(Aq, prefix => \*(AqA\-\*(Aq);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
The following options are available:
.IP "\(bu" 4
style
.Sp
One of \f(CW\*(C`decimal\*(C'\fR (standard decimal arabic numerals), \f(CW\*(C`Roman\*(C'\fR (uppercase roman
numerals), \f(CW\*(C`roman\*(C'\fR (lowercase roman numerals), \f(CW\*(C`Alpha\*(C'\fR (uppercase letters),
or \f(CW\*(C`alpha\*(C'\fR (lowercase letters).
.Sp
There is no default numbering style.  If omitted, the page label will be just
the prefix (if set) or an empty string.
.IP "\(bu" 4
prefix
.Sp
The label prefix for pages in this range.
.IP "\(bu" 4
start
.Sp
An integer (default: 1) representing the first value to be used in this page
range.
.SS "default_page_size"
.IX Subsection "default_page_size"
.Vb 2
\&    # Set
\&    $pdf\->default_page_size($size);
\&
\&    # Get
\&    @rectangle = $pdf\->default_page_size()
.Ve
.PP
Set the default physical size for pages in the \s-1PDF.\s0  If called without
arguments, return the coordinates of the rectangle describing the default
physical page size.
.PP
See \*(L"Page Sizes\*(R" in PDF::API2::Page for possible values.
.SS "default_page_boundaries"
.IX Subsection "default_page_boundaries"
.Vb 2
\&    # Set
\&    $pdf\->default_page_boundaries(%boundaries);
\&
\&    # Get
\&    %boundaries = $pdf\->default_page_boundaries();
.Ve
.PP
Set default prepress page boundaries for pages in the \s-1PDF.\s0  If called without
arguments, returns the coordinates of the rectangles describing each of the
supported page boundaries.
.PP
See the equivalent \f(CW\*(C`page_boundaries\*(C'\fR method in PDF::API2::Page for details.
.SH "FONT METHODS"
.IX Header "FONT METHODS"
.SS "font"
.IX Subsection "font"
.Vb 1
\&    my $font = $pdf\->font($name, %options)
.Ve
.PP
Add a font to the \s-1PDF.\s0  Returns the font object, to be used by
PDF::API2::Content.
.PP
The font \f(CW$name\fR is either the name of one of the standard 14
fonts (e.g. Helvetica) or
the path to a font file.
.PP
.Vb 5
\&    my $pdf = PDF::API2\->new();
\&    my $font1 = $pdf\->font(\*(AqHelvetica\-Bold\*(Aq);
\&    my $font2 = $pdf\->font(\*(Aq/path/to/ComicSans.ttf\*(Aq);
\&    my $page = $pdf\->page();
\&    my $content = $page\->text();
\&
\&    $content\->position(1 * 72, 9 * 72);
\&    $content\->font($font1, 24);
\&    $content\->text(\*(AqHello, World!\*(Aq);
\&
\&    $content\->position(0, \-36);
\&    $content\->font($font2, 12);
\&    $content\->text(\*(AqThis is some sample text.\*(Aq);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
The path can be omitted if the font file is in the current directory or one of
the directories returned by \f(CW\*(C`font_path\*(C'\fR.
.PP
TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph Bitmap
Distribution Format (bdf) fonts are supported.
.PP
The following \f(CW%options\fR are available:
.IP "\(bu" 4
format
.Sp
The font format is normally detected automatically based on the file's
extension.  If you're using a font with an atypical extension, you can set
\&\f(CW\*(C`format\*(C'\fR to one of \f(CW\*(C`truetype\*(C'\fR (TrueType or OpenType), \f(CW\*(C`type1\*(C'\fR (PostScript
Type 1), or \f(CW\*(C`bitmap\*(C'\fR (Adobe Bitmap).
.IP "\(bu" 4
kerning
.Sp
Kerning (automatic adjustment of space between pairs of characters) is enabled
by default if the font includes this information.  Set this option to false to
disable.
.IP "\(bu" 4
afm_file (PostScript Type 1 fonts only)
.Sp
Specifies the location of the font metrics file.
.IP "\(bu" 4
pfm_file (PostScript Type 1 fonts only)
.Sp
Specifies the location of the printer font metrics file.  This option overrides
the \-encode option.
.IP "\(bu" 4
embed (TrueType fonts only)
.Sp
Fonts are embedded in the \s-1PDF\s0 by default, which is required to ensure that they
can be viewed properly on a device that doesn't have the font installed.  Set
this option to false to prevent the font from being embedded.
.SS "synthetic_font"
.IX Subsection "synthetic_font"
.Vb 1
\&    $font = $pdf\->synthetic_font($base_font, %options)
.Ve
.PP
Create and return a new synthetic font object.  See
PDF::API2::Resource::Font::SynFont for details.
.SS "font_path"
.IX Subsection "font_path"
.Vb 1
\&    @directories = PDF::API2\->font_path()
.Ve
.PP
Return the list of directories that will be searched (in order) in addition to
the current directory when you add a font to a \s-1PDF\s0 without including the full
path to the font file.
.SS "add_to_font_path"
.IX Subsection "add_to_font_path"
.Vb 1
\&    @directories = PDF::API2\->add_to_font_path(\*(Aq/my/fonts\*(Aq, \*(Aq/path/to/fonts\*(Aq);
.Ve
.PP
Add one or more directories to the list of paths to be searched for font files.
.PP
Returns the font search path.
.SS "set_font_path"
.IX Subsection "set_font_path"
.Vb 1
\&    @directories = PDF::API2\->set_font_path(\*(Aq/my/fonts\*(Aq, \*(Aq/path/to/fonts\*(Aq);
.Ve
.PP
Replace the existing font search path.  This should only be necessary if you
need to remove a directory from the path for some reason, or if you need to
reorder the list.
.PP
Returns the font search path.
.SH "GRAPHICS METHODS"
.IX Header "GRAPHICS METHODS"
.SS "image"
.IX Subsection "image"
.Vb 1
\&    $object = $pdf\->image($file, %options);
.Ve
.PP
Import a supported image type and return an object that can be placed as part of
a page's content:
.PP
.Vb 2
\&    my $pdf = PDF::API2\->new();
\&    my $page = $pdf\->page();
\&
\&    my $image = $pdf\->image(\*(Aq/path/to/image.jpg\*(Aq);
\&    $page\->object($image, 100, 100);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
\&\f(CW$file\fR may be either a file name, a filehandle, or a GD::Image object.
.PP
See \*(L"place\*(R" in PDF::API2::Content for details about placing images on a page
once they're imported.
.PP
The image format is normally detected automatically based on the file's
extension.  If passed a filehandle, image formats \s-1GIF, JPEG,\s0 and \s-1PNG\s0 will be
detected based on the file's header.
.PP
If the file has an atypical extension or the filehandle is for a different kind
of image, you can set the \f(CW\*(C`format\*(C'\fR option to one of the supported types:
\&\f(CW\*(C`gif\*(C'\fR, \f(CW\*(C`jpeg\*(C'\fR, \f(CW\*(C`png\*(C'\fR, \f(CW\*(C`pnm\*(C'\fR, or \f(CW\*(C`tiff\*(C'\fR.
.PP
Note: \s-1PNG\s0 images that include an alpha (transparency) channel go through a
relatively slow process of splitting the image into separate \s-1RGB\s0 and alpha
components as is required by images in PDFs.  If you're having performance
issues, install \s-1PDF::API2::XS\s0 or Image::PNG::Libpng to speed this process up by
an order of magnitude; either module will be used automatically if available.
.SS "barcode"
.IX Subsection "barcode"
.Vb 1
\&    $object = $pdf\->barcode($format, $code, %options);
.Ve
.PP
Generate and return a barcode that can be placed as part of a page's content:
.PP
.Vb 2
\&    my $pdf = PDF::API2\->new();
\&    my $page = $pdf\->page();
\&
\&    my $barcode = $pdf\->barcode(\*(Aqean13\*(Aq, \*(Aq0123456789012\*(Aq);
\&    $page\->object($barcode, 100, 100);
\&
\&    my $qr_code = $pdf\->barcode(\*(Aqqr\*(Aq, \*(Aqhttp://www.example.com\*(Aq);
\&    $page\->object($qr_code, 100, 300, 144 / $qr_code\->width())
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
\&\f(CW$format\fR can be one of \f(CW\*(C`codabar\*(C'\fR, \f(CW\*(C`code128\*(C'\fR, \f(CW\*(C`code39\*(C'\fR (a.k.a. 3 of 9),
\&\f(CW\*(C`ean128\*(C'\fR, \f(CW\*(C`ean13\*(C'\fR, \f(CW\*(C`itf\*(C'\fR (a.k.a. interleaved 2 of 5), or \f(CW\*(C`qr\*(C'\fR.
.PP
\&\f(CW$code\fR is the value to be encoded.  Start and stop characters are only
required when they're not static (e.g. for Codabar).
.PP
The following options are available:
.IP "\(bu" 4
bar_width
.Sp
The width of the smallest bar or space in points (72 points = 1 inch).
.Sp
If you're following a specification that gives bar width in mils (thousandths of
an inch), use this conversion: \f(CW\*(C`$points = $mils / 1000 * 72\*(C'\fR.
.IP "\(bu" 4
bar_height
.Sp
The base height of the barcode in points.
.IP "\(bu" 4
bar_extend
.Sp
If present and applicable, bars for non-printing characters (e.g. start and stop
characters) will be extended downward by this many points, and printing
characters will be shown below their respective bars.
.Sp
This is enabled by default for \s-1EAN\-13\s0 barcodes.
.IP "\(bu" 4
caption
.Sp
If present, this value will be printed, centered, beneath the barcode, and
should be a human-readable representation of the barcode.  This option is
ignored for \s-1QR\s0 codes.
.IP "\(bu" 4
font
.Sp
A font object (created by \*(L"font\*(R") that will be used to print the caption, or
the printable characters when \f(CW\*(C`bar_extend\*(C'\fR is set.
.Sp
Helvetica will be used by default.
.IP "\(bu" 4
font_size
.Sp
The size of the font used for printing the caption or printable characters.
.Sp
The default will be calculated based on the barcode size, if \f(CW\*(C`bar_extend\*(C'\fR is
set, or 10 otherwise.
.IP "\(bu" 4
quiet_zone
.Sp
A margin, in points, that will be place before the left and bottom edges of the
barcode (including the caption, if present).  This is used to help barcode
scanners tell where the barcode begins and ends.
.Sp
The default is the width of one encoded character, or four squares for \s-1QR\s0 codes.
.IP "\(bu" 4
bar_overflow
.Sp
Shrinks the horizontal width of bars by this amount in points to account for ink
spread when printing.  This option is ignored for \s-1QR\s0 codes.
.Sp
The default is 0.01 points.
.IP "\(bu" 4
color
.Sp
Draw bars using this color, which may be any value accepted by
\&\*(L"fillcolor\*(R" in PDF::API2::Content.
.Sp
The default is black.
.PP
\&\s-1QR\s0 codes have
additional options for
customizing the error correction level and other niche settings.
.SS "colorspace"
.IX Subsection "colorspace"
.Vb 1
\&    $colorspace = $pdf\->colorspace($type, @arguments);
.Ve
.PP
Colorspaces can be added to a \s-1PDF\s0 to either specifically control the output
color on a particular device (spot colors, device colors) or to save space by
limiting the available colors to a defined color palette (web-safe palette, \s-1ACT\s0
file).
.PP
Once added to the \s-1PDF,\s0 they can be used in place of regular hex codes or named
colors:
.PP
.Vb 3
\&    my $pdf = PDF::API2\->new();
\&    my $page = $pdf\->page();
\&    my $content = $page\->graphics();
\&
\&    # Add colorspaces for a spot color and the web\-safe color palette
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqPANTONE Red 032 C\*(Aq, \*(Aq#EF3340\*(Aq);
\&    my $web = $pdf\->colorspace(\*(Aqweb\*(Aq);
\&
\&    # Fill using the spot color with 100% coverage
\&    $content\->fill_color($spot, 1.0);
\&
\&    # Stroke using the first color of the web\-safe palette
\&    $content\->stroke_color($web, 0);
\&
\&    # Add a rectangle to the page
\&    $content\->rectangle(100, 100, 200, 200);
\&    $content\->paint();
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
The following types of colorspaces are supported
.IP "\(bu" 4
spot
.Sp
.Vb 1
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, $tint, $alt_color);
.Ve
.Sp
Spot colors are used to instruct a device (usually a printer) to use or emulate
a particular ink color (\f(CW$tint\fR) for parts of the document.  An \f(CW$alt_color\fR
is provided for devices (e.g. \s-1PDF\s0 viewers) that don't know how to produce the
named color.  It can either be an approximation of the color in \s-1RGB, CMYK,\s0 or
\&\s-1HSV\s0 formats, or a wildly different color (e.g. 100% magenta, \f(CW%0F00\fR) to make
it clear if the spot color isn't being used as expected.
.IP "\(bu" 4
web
.Sp
.Vb 1
\&    my $web = $pdf\->colorspace(\*(Aqweb\*(Aq);
.Ve
.Sp
The web-safe color palette is a historical collection of colors that was used
when many display devices only supported 256 colors.
.IP "\(bu" 4
act
.Sp
.Vb 1
\&    my $act = $pdf\->colorspace(\*(Aqact\*(Aq, $filename);
.Ve
.Sp
An Adobe Color Table (\s-1ACT\s0) file provides a custom palette of colors that can be
referenced by \s-1PDF\s0 graphics and text drawing commands.
.IP "\(bu" 4
device
.Sp
.Vb 1
\&    my $devicen = $pdf\->colorspace(\*(Aqdevice\*(Aq, @colorspaces);
.Ve
.Sp
A device-specific colorspace allows for precise color output on a given device
(typically a printing press), bypassing the normal color interpretation
performed by raster image processors (RIPs).
.Sp
Device colorspaces are also needed if you want to blend spot colors:
.Sp
.Vb 3
\&    my $pdf = PDF::API2\->new();
\&    my $page = $pdf\->page();
\&    my $content = $page\->graphics();
\&
\&    # Create a two\-color device colorspace
\&    my $yellow = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqYellow\*(Aq, \*(Aq%00F0\*(Aq);
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqPANTONE Red 032 C\*(Aq, \*(Aq#EF3340\*(Aq);
\&    my $device = $pdf\->colorspace(\*(Aqdevice\*(Aq, $yellow, $spot);
\&
\&    # Fill using a blend of 25% yellow and 75% spot color
\&    $content\->fill_color($device, 0.25, 0.75);
\&
\&    # Stroke using 100% spot color
\&    $content\->stroke_color($device, 0, 1);
\&
\&    # Add a rectangle to the page
\&    $content\->rectangle(100, 100, 200, 200);
\&    $content\->paint();
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.SS "egstate"
.IX Subsection "egstate"
.Vb 1
\&    $resource = $pdf\->egstate();
.Ve
.PP
Creates and returns a new extended graphics state object, described in
PDF::API2::ExtGState.
.SH "BACKWARD COMPATIBILITY"
.IX Header "BACKWARD COMPATIBILITY"
Code written using \s-1PDF::API2\s0 should continue to work unchanged for the life of
most long-term-stable (\s-1LTS\s0) server distributions.  Specifically, it should
continue working for versions of Perl that were released within the
past five years (the typical support window for \s-1LTS\s0 releases) plus six months
(allowing plenty of time for package freezes prior to release).
.PP
In \s-1PDF::API2,\s0 method names, options, and functionality change over time.
Functionality that's documented (not just in source code comments) should
continue working for the same time period of five years and six months, though
deprecation warnings may be added.  There may be exceptions if your code happens
to rely on bugs that get fixed, including when a method in \s-1PDF::API2\s0 is changed
to more closely follow the \s-1PDF\s0 specification.
.PP
Occasional breaking changes may be unavoidable or deemed small enough in scope
to be worth the benefit of making the change instead of keeping the old
behavior.  These will be noted in the Changes file as items beginning with the
phrase \*(L"Breaking Change\*(R".
.PP
Undocumented features, unreleased code, features marked as experimental, and
underlying data structures may change at any time.  An exception is for features
that were previously released and documented, which should continue to work for
the above time period after the documentation is removed.
.PP
Before migrating to a new \s-1LTS\s0 server version, it's recommended that you upgrade
to the latest version of \s-1PDF::API2,\s0 \f(CW\*(C`use warnings\*(C'\fR, and check your server logs
for deprecation messages after exercising your code.  Once these are resolved,
it should be safe to use future \s-1PDF::API2\s0 releases during that \s-1LTS\s0 support
window.
.PP
If your code uses a \s-1PDF::API2\s0 method that isn't documented here, it has probably
been deprecated.  Search for it in the Migration section below to find its
replacement.
.SH "MIGRATION"
.IX Header "MIGRATION"
Use this section to bring your existing code up to date with current method
names and options.  If you're not getting a deprecation warning, this is
optional, but still recommended.
.PP
For example, in cases where a method was simply renamed, the old name will be
set up as an alias for the new one, which can be maintained indefinitely.  The
main benefit of switching to the new name is to make it easier to find the
appropriate documentation when you need it.
.IP "new(\-compress => 0)" 4
.IX Item "new(-compress => 0)"
.PD 0
.ie n .IP "new(\-file => $filename)" 4
.el .IP "new(\-file => \f(CW$filename\fR)" 4
.IX Item "new(-file => $filename)"
.PD
Remove the hyphen from the option names.
.ie n .IP "\fBnew()\fR with any options other than ""compress"" or ""file""" 4
.el .IP "\fBnew()\fR with any options other than \f(CWcompress\fR or \f(CWfile\fR" 4
.IX Item "new() with any options other than compress or file"
Replace with calls to \*(L"\s-1INTERACTIVE FEATURE METHODS\*(R"\s0.  See the deprecated
\&\*(L"preferences\*(R" method for particular option names.
.IP "finishobjects" 4
.IX Item "finishobjects"
.PD 0
.IP "saveas" 4
.IX Item "saveas"
.IP "update" 4
.IX Item "update"
.PD
Replace with \*(L"save\*(R".
.IP "end" 4
.IX Item "end"
.PD 0
.IP "release" 4
.IX Item "release"
.PD
Replace with \*(L"close\*(R".
.IP "open_scalar" 4
.IX Item "open_scalar"
.PD 0
.IP "openScalar" 4
.IX Item "openScalar"
.PD
Replace with \*(L"from_string\*(R".
.IP "stringify" 4
.IX Item "stringify"
Replace with \*(L"to_string\*(R".
.IP "info" 4
.IX Item "info"
Each of the hash keys now has its own accessor.  See \*(L"\s-1METADATA METHODS\*(R"\s0.
.Sp
For custom keys or if you prefer to give the key names as variables (e.g. as
part of a loop), use \*(L"info_metadata\*(R".
.IP "infoMetaAttributes" 4
.IX Item "infoMetaAttributes"
Use \*(L"info_metadata\*(R" without arguments to get a list of currently-set keys in
the Info dictionary (including any custom keys).  This is slightly different
behavior from calling \f(CW\*(C`infoMetaAttributes\*(C'\fR without arguments, which always
returns the standard key names and any defined custom key names, whether or not
they're present in the \s-1PDF.\s0
.Sp
Calling \f(CW\*(C`infoMetaAttributes\*(C'\fR with arguments defines the list of Info keys that
are supported by the deprecated \f(CW\*(C`info\*(C'\fR method.  You can now just call
\&\*(L"info_metadata\*(R" with a standard or custom key and value.
.IP "xmpMetadata" 4
.IX Item "xmpMetadata"
Replace with \*(L"xml_metadata\*(R".  Note that, when called with an argument,
\&\f(CW\*(C`xml_metadata\*(C'\fR returns the \s-1PDF\s0 object rather than the value, to line up with
most other \s-1PDF::API2\s0 accessors.
.IP "isEncrypted" 4
.IX Item "isEncrypted"
Replace with \*(L"is_encrypted\*(R".
.IP "outlines" 4
.IX Item "outlines"
Replace with \*(L"outline\*(R".
.IP "preferences" 4
.IX Item "preferences"
This functionality has been split into a few methods, aligning more closely with
the underlying \s-1PDF\s0 structure.  See the documentation for each of the methods for
revised option names.
.RS 4
.IP "\(bu" 4
\&\-fullscreen, \-thumbs, \-outlines
.Sp
Call \*(L"page_mode\*(R".
.IP "\(bu" 4
\&\-singlepage, \-onecolumn, \-twocolumnleft, \-twocolumnright
.Sp
Call \*(L"page_layout\*(R".
.IP "\(bu" 4
\&\-hidetoolbar, \-hidemenubar, \-hidewindowui, \-fitwindow, \-centerwindow,
\&\-displaytitle, \-righttoleft, \-afterfullscreenthumbs, \-afterfullscreenoutlines,
\&\-printscalingnone, \-simplex, \-duplexfliplongedge, \-duplexflipshortedge
.Sp
Call \*(L"viewer_preferences\*(R".
.IP "\(bu" 4
\&\-firstpage
.Sp
Call \*(L"open_action\*(R".
.RE
.RS 4
.RE
.IP "openpage" 4
.IX Item "openpage"
Replace with \*(L"open_page\*(R".
.IP "importpage" 4
.IX Item "importpage"
Replace with \*(L"import_page\*(R".
.IP "importPageIntoForm" 4
.IX Item "importPageIntoForm"
Replace with \*(L"embed_page\*(R".
.IP "pages" 4
.IX Item "pages"
Replace with \*(L"page_count\*(R".
.IP "pageLabel" 4
.IX Item "pageLabel"
Replace with \*(L"page_labels\*(R".  Remove hyphens from the argument names.  Add
\&\f(CW\*(C`style => \*(Aqdecimal\*(Aq\*(C'\fR if there wasn't a \f(CW\*(C`\-style\*(C'\fR argument.
.IP "mediabox" 4
.IX Item "mediabox"
.PD 0
.IP "cropbox" 4
.IX Item "cropbox"
.IP "bleedbox" 4
.IX Item "bleedbox"
.IP "trimbox" 4
.IX Item "trimbox"
.IP "artbox" 4
.IX Item "artbox"
.PD
Replace with \*(L"default_page_boundaries\*(R".  If using page size aliases
(e.g. \*(L"letter\*(R" or \*(L"A4\*(R"), check to ensure that the alias is still supported
(you'll get an error if it isn't).
.IP "synfont" 4
.IX Item "synfont"
Replace with \*(L"synthetic_font\*(R".
.IP "addFontDirs" 4
.IX Item "addFontDirs"
Replace with \*(L"add_to_font_path\*(R".
.IP "corefont" 4
.IX Item "corefont"
Replace with \*(L"font\*(R".  Note that \f(CW\*(C`font\*(C'\fR requires that the font name be an
exact, case-sensitive match.  The full list can be found in
\&\*(L"\s-1STANDARD FONTS\*(R"\s0 in PDF::API2::Resource::Font::CoreFont.
.IP "ttfont" 4
.IX Item "ttfont"
Replace with \*(L"font\*(R".  Replace \f(CW\*(C`\-noembed => 1\*(C'\fR with \f(CW\*(C`embed => 0\*(C'\fR.
.IP "bdfont" 4
.IX Item "bdfont"
Replace with \*(L"font\*(R".
.IP "psfont" 4
.IX Item "psfont"
Replace with \*(L"font\*(R".  Rename options \f(CW\*(C`\-afmfile\*(C'\fR and \f(CW\*(C`\-pfmfile\*(C'\fR to
\&\f(CW\*(C`afm_file\*(C'\fR and \f(CW\*(C`pfm_file\*(C'\fR.
.Sp
Note that Adobe has announced that their products no longer support Postscript
Type 1 fonts, effective early 2023.  They recommend using TrueType or OpenType
fonts instead.
.IP "cjkfont" 4
.IX Item "cjkfont"
.PD 0
.IP "unifont" 4
.IX Item "unifont"
.PD
These are old methods from back when Unicode was still new and poorly supported.
Replace them with calls to \*(L"font\*(R" using a TrueType or OpenType font that has
the characters you need.
.Sp
If you're successfully using one of these two methods and feel they shouldn't be
deprecated, please contact me with your use case.
.IP "image_gd" 4
.IX Item "image_gd"
.PD 0
.IP "image_gif" 4
.IX Item "image_gif"
.IP "image_jpeg" 4
.IX Item "image_jpeg"
.IP "image_png" 4
.IX Item "image_png"
.IP "image_pnm" 4
.IX Item "image_pnm"
.IP "image_tiff" 4
.IX Item "image_tiff"
.PD
Replace with \*(L"image\*(R".
.IP "xo_code128" 4
.IX Item "xo_code128"
.PD 0
.IP "xo_codabar" 4
.IX Item "xo_codabar"
.IP "xo_2of5int" 4
.IX Item "xo_2of5int"
.IP "xo_3of9" 4
.IX Item "xo_3of9"
.IP "xo_ean13" 4
.IX Item "xo_ean13"
.PD
Replace with \*(L"barcode\*(R".  Replace arguments as follows:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`\-color\*(C'\fR: \f(CW\*(C`color\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-fnsz\*(C'\fR: \f(CW\*(C`font_size\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-font\*(C'\fR: \f(CW\*(C`font\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-lmzn\*(C'\fR: \f(CW\*(C`bar_extend\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-ofwt\*(C'\fR: \f(CW\*(C`bar_overflow\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-quzn\*(C'\fR: \f(CW\*(C`quiet_zone\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`\-zone\*(C'\fR: \f(CW\*(C`bar_height\*(C'\fR
.Sp
These options are simple renames.
.IP "\(bu" 4
\&\f(CW\*(C`\-mils\*(C'\fR: \f(CW\*(C`bar_width\*(C'\fR
.Sp
This requires a conversion from mils to points.  The \f(CW\*(C`bar_width\*(C'\fR documentation
has sample code to do the conversion.
.IP "\(bu" 4
\&\f(CW\*(C`\-ean\*(C'\fR
.Sp
Specify \f(CW\*(C`ean128\*(C'\fR as the barcode format instead of \f(CW\*(C`code128\*(C'\fR.
.RE
.RS 4
.RE
.IP "colorspace_act" 4
.IX Item "colorspace_act"
.PD 0
.IP "colorspace_web" 4
.IX Item "colorspace_web"
.IP "colorspace_separation" 4
.IX Item "colorspace_separation"
.IP "colorspace_devicen" 4
.IX Item "colorspace_devicen"
.PD
Replace with \*(L"colorspace\*(R".
.IP "colorspace_hue" 4
.IX Item "colorspace_hue"
This is deprecated because I wasn't able to find a corresponding standard.
Please contact me if you're using it, to avoid having it be removed in a future
release.
.IP "default" 4
.IX Item "default"
The optional changes in default behavior have all been deprecated.
.Sp
Replace \f(CW\*(C`pageencaps\*(C'\fR with calls to \f(CW\*(C`save\*(C'\fR and \f(CW\*(C`restore\*(C'\fR when embedding or
superimposing a page onto another, if needed.
.Sp
\&\f(CW\*(C`nounrotate\*(C'\fR and \f(CW\*(C`copyannots\*(C'\fR will continue to work until better options are
available, but should not be used in new code.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1PDF::API2\s0 is developed and maintained by Steve Simms, with patches from numerous
contributors who are credited in the Changes file.
.PP
It was originally written by Alfred Reibenschuh, extending code written
by Martin Hosken.
.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.