oracular (3) PDF::Builder.3pm.gz
NAME
PDF::Builder - Facilitates the creation and modification of PDF files
SYNOPSIS
use PDF::Builder;
# Create a blank PDF file
$pdf = PDF::Builder->new();
# Open an existing PDF file
$pdf = PDF::Builder->open('some.pdf');
# Add a blank page
$page = $pdf->page();
# Retrieve an existing page
$page = $pdf->open_page($page_number);
# Set the page size
$page->size('Letter'); # or mediabox('Letter')
# Add a built-in font to the PDF
$font = $pdf->font('Helvetica-Bold'); # or corefont('Helvetica-Bold')
# Add an external TrueType (TTF) font to the PDF
$font = $pdf->font('/path/to/font.ttf'); # or ttfont() in this case
# Add some text to the page
$text = $page->text();
$text->font($font, 20);
$text->position(200, 700); # or translate()
$text->text('Hello World!');
# Save the PDF
$pdf->saveas('/path/to/new.pdf');
SOME SPECIAL NOTES
See the file README.md (in downloadable package and on CPAN) for a summary of prerequisites and tools
needed to install PDF::Builder, both mandatory and optional.
SOFTWARE DEVELOPMENT KIT
There are four levels of involvement with PDF::Builder. Depending on what you want to do, different kinds
of installs are recommended. See "Software Development Kit" in PDF::Builder::Docs for suggestions.
OPTIONAL LIBRARIES
PDF::Builder can make use of some optional libraries, which are not required for a successful
installation, but improve speed and capabilities. See "Optional Libraries" in PDF::Builder::Docs for more
information.
STRINGS (CHARACTER TEXT)
There are some things you should know about character encoding (for text), before you dive in to coding.
Please go to "Strings (Character Text)" in PDF::Builder::Docs and have a read.
RENDERING ORDER
Invoking "text" and "graphics" methods can lead to unexpected results (a different ordering of output
than intended). See "Rendering Order" in PDF::Builder::Docs for more information.
PDF VERSIONS SUPPORTED
PDF::Builder is mostly PDF 1.4-compliant, but there are complications you should be aware of. Please read
"PDF Versions Supported" in PDF::Builder::Docs for details.
SUPPORTED PERL VERSIONS (BACKWARDS COMPATIBILITY GOALS)
PDF::Builder intends 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 (LTS) server distributions. See
the <https://www.cpan.org/src/> table First release in each branch of Perl x.xxxx0 "Major" release dates.
For example, a version of PDF::Builder released on 2018-06-05 would support the last major version of
Perl released on or after 2012-06-05 (5.18), and then one before that, which would be 5.16.
Alternatively, the last major version of Perl released before 2012-06-05 is 5.16.
The intent is to avoid expending unnecessary effort in supporting very old (obsolete) versions of Perl.
Anticipated Support Cutoff Dates
Note that these are not hard and fast dates. In particular, we develop on Strawberry Perl, which
sometimes falls a little behind the official Perl release!
• 5.26 current minimum supported version, until next PDF::Builder release after 23 June, 2024. This is
currently the minimum tested version.
• 5.28 future minimum supported version, until next PDF::Builder release after 22 May, 2025
• 5.30 future minimum supported version, until next PDF::Builder release after 20 June, 2026
• 5.32 future minimum supported version, until next PDF::Builder release after 20 May, 2027. This is
currently our primary development version.
• 5.34 future minimum supported version, until next PDF::Builder release after 28 May, 2028
• 5.36 future minimum supported version, until next PDF::Builder release after 02 Jul, 2029
• 5.38 future minimum supported version, until next PDF::Builder release some time after 02 Jul, 2029.
This is currently the maximum tested version.
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.
On the other hand, any feature in PDF::Builder should continue to work unchanged for the life of most
long-term-stable (LTS) server distributions. Their lifetime is usually about six (6) years. Note that
this does not constitute a statement of warranty, but that we intend to try to keep any particular
release of PDF::Builder working for a period of years. Of course, it helps if you periodically update
your Perl installation to something released in the recent past.
KNOWN ISSUES
This module does not work with perl's -l command-line switch.
There is a file INFO/KNOWN_INCOMP which lists known incompatibilities with PDF::API2, in case you're
thinking of porting over something from that world, or have experience there and want to try
PDF::Builder. There is also a file INFO/DEPRECATED, which lists things which are planned to be removed at
some point.
HISTORY
The history of PDF::Builder is a complex and exciting saga... OK, it may be mildly interesting. Have a
look at "History" in PDF::Builder::Docs section.
AUTHOR
PDF::API2 was originally written by Alfred Reibenschuh. See the HISTORY section for more information.
It was maintained by Steve Simms, who is still contributing new code to it (which often ends up in
PDF::Builder).
PDF::Builder is currently being maintained by Phil M. Perry.
SUPPORT
The full source is on https://github.com/PhilterPaper/Perl-PDF-Builder.
The release distribution is on CPAN: https://metacpan.org/pod/PDF::Builder.
Bug reports are on
https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc (with "bug"
label), feature requests have an "enhancement" label, and general discussions (architecture, roadmap,
etc.) have a "general discussion" label.
Do not under any circumstances open a PR (Pull Request) to report a bug. It is a waste of both your and
our time and effort. Open a regular ticket (issue), and attach a Perl (.pl) program illustrating the
problem, if possible. If you believe that you have a program patch, and offer to share it as a PR, we
may give the go-ahead. Unsolicited PRs may be closed without further action.
LICENSE
This software is Copyright (c) 2017-2023 by Phil M. Perry.
This is free software, licensed under:
The GNU Lesser General Public License (LGPL) Version 2.1, February 1999
(The master copy of this license lives on the GNU website.)
(A copy is provided in the INFO/LICENSE file for your convenience.)
This section of Builder.pm is intended only as a very brief summary of the license; please consider
INFO/LICENSE to be the controlling version, if there is any conflict or ambiguity between the two.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU 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 of this license.
NOTE: there are several files in this distribution which were incorporated from outside sources and carry
different licenses. If a file states that it is under a license different than LGPL 2.1, that license and
its terms will apply to that file, and not LGPL 2.1.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
Public License for more details.
GENERAL PURPOSE METHODS
new
$pdf = PDF::Builder->new(%opts)
Creates a new PDF object.
Options
file
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 (the file is opened immediately for writing, rather
than waiting until the "save"). The "file" may also be a filehandle.
compress
The 'compress' option can be given to specify stream compression: default is 'flate', 'none' (or 0)
is no compression. No other compression methods are currently supported.
outver
The 'outver' option defaults to 1.4 as the output PDF version and the highest allowed feature version
(attempts to use anything higher will give a warning). If an existing PDF with a higher version is
read in, "outver" will be increased to that version, with a warning.
msgver
The 'msgver' option value of 1 (default) gives a warning message if the 'outver' PDF level has to be
bumped up due to either a higher PDF level file being read in, or a higher level feature was
requested. A value of 0 suppresses the warning message.
diaglevel
The 'diaglevel' option can be given to specify the level of diagnostics given by IntegrityCheck().
The default is level 2 (errors and warnings). See "IntegrityCheck" in PDF::Builder::Docs for more
information.
Example:
$pdf = PDF::Builder->new();
...
print $pdf->to_string();
$pdf = PDF::Builder->new(compress => 'none');
# equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)
$pdf = PDF::Builder->new();
...
$pdf->saveas('our/new.pdf');
$pdf = PDF::Builder->new(file => 'our/new.pdf');
...
$pdf->save();
default_page_size
$pdf->default_page_size($size); # Set
@rectangle = $pdf->default_page_size() # Get
Set the default physical size for pages in the PDF. If called without arguments, return the
coordinates of the rectangle describing the default physical page size.
This is essentially an alternate method of defining the "mediabox()" call, and added for
compatibility with PDF::API2.
See "Page Sizes" in PDF::Builder::Page for possible values.
default_page_boundaries
$pdf->default_page_boundaries(%boundaries); # Set
%boundaries = $pdf->default_page_boundaries(); # Get
Set default prepress page boundaries for pages in the PDF. If called without arguments, returns the
coordinates of the rectangles describing each of the supported page boundaries.
See the equivalent "page_boundaries" method in PDF::Builder::Page for details.
INPUT/OUTPUT METHODS
open
$pdf = PDF::Builder->open($pdf_file, %opts)
Opens an existing PDF file. See "new()" for options.
Example:
$pdf = PDF::Builder->open('our/old.pdf');
...
$pdf->saveas('our/new.pdf');
$pdf = PDF::Builder->open('our/to/be/updated.pdf');
...
$pdf->update();
from_string, open_scalar, openScalar
$pdf = PDF::Builder->from_string($pdf_string, %opts)
Opens a PDF contained in a string. See "new()" for other options.
diags => 1
Display warnings when non-conforming PDF structure is found, and fix up where possible. See
PDF::Builder::Basic::PDF::File for more information.
Example:
# Read a PDF into a string, for the purpose of demonstration
open $fh, 'our/old.pdf' or croak $@;
undef $/; # Read the whole file at once
$pdf_string = <$fh>;
$pdf = PDF::Builder->from_string($pdf_string);
...
$pdf->saveas('our/new.pdf');
Alternate name: "open_scalar"
"from_string" was formerly known as "open_scalar" (and even before that, as "openScalar"), and this
older name is still valid as an alternative to "from_string". It is possible that "open_scalar" will
be deprecated and then removed some time in the future, so it may be advisable to use "from_string"
in new work.
to_string, stringify
$string = $pdf->to_string()
Return the document as a string and remove the object structure from memory.
Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after
invoking this method! You will receive error messages about "can't call method new_obj on an
undefined value".
Example:
$pdf = PDF::Builder->new();
...
print $pdf->to_string();
Alternate name: "stringify"
"to_string" was formerly known as "stringify", and this older name is still valid as an alternative
to "to_string". It is possible that "stringify" will be deprecated and then removed some time in the
future, so it may be advisable to use "to_string" in new work.
finishobjects
$pdf->finishobjects(@objects)
Force objects to be written to file if possible.
Example:
$pdf = PDF::Builder->new(file => 'our/new.pdf');
...
$pdf->finishobjects($page, $gfx, $txt);
...
$pdf->save();
Note: this method is now considered obsolete, and may be deprecated. It allows for objects to be
written to disk in advance of finally saving and closing the file. Otherwise, it's no different than
just calling "save()" when all changes have been made. There's no memory advantage since "ship_out"
doesn't remove objects from memory.
update
$pdf->update()
Saves a previously opened document.
Example:
$pdf = PDF::Builder->open('our/to/be/updated.pdf');
...
$pdf->update();
Note: it is considered better to simply "save()" the file, rather than calling "update()". They end
up doing the same thing, anyway. This method may be deprecated in the future.
saveas
$pdf->saveas($file)
Save the document to $file and remove the object structure from memory.
Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after
invoking this method! You will receive error messages about "can't call method new_obj on an
undefined value".
Example:
$pdf = PDF::Builder->new();
...
$pdf->saveas('our/new.pdf');
save
$pdf->save()
$pdf->save(filename)
Save the document to an already-defined file (or filename) and remove the object structure from
memory. Optionally, a new filename may be given.
Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after
invoking this method! You will receive error messages about "can't call method new_obj on an
undefined value".
Example:
$pdf = PDF::Builder->new(file => 'file_to_output');
...
$pdf->save();
Note: now that "save()" can take a filename as an argument, it effectively is interchangeable with
"saveas()". This is strictly for compatibility with recent changes to PDF::API2. Unlike PDF::API2, we
are not deprecating the "saveas()" method, because in user interfaces, "save" normally means that the
current filename is known and is to be used, while "saveas" normally means that (whether or not there
is a current filename) a new filename is to be used.
close, release, end
$pdf->close();
Close an open file (if relevant) and remove the object structure from memory.
PDF::API2 contains circular references, so this call is necessary in long-running processes to keep
from running out of memory.
This will be called automatically when you save or stringify a PDF. You should only need to call it
explicitly if you are reading PDF files and not writing them.
Alternate names: "release" and "end"
end
$pdf->end()
Remove the object structure from memory. PDF::Builder contains circular references, so this call is
necessary in long-running processes to keep from running out of memory.
This will be called automatically when you save or to_string a PDF. You should only need to call it
explicitly if you are reading PDF files and not writing them.
This (and release) are older and now deprecated names formerly used in PDF::API2 and PDF::Builder.
You should try to avoid having to explicitly call them.
METADATA METHODS
title
$title = $pdf->title();
$pdf = $pdf->title($title);
Get/set/clear the document's title.
author
$author = $pdf->author();
$pdf = $pdf->author($author);
Get/set/clear the name of the person who created the document.
subject
$subject = $pdf->subject();
$pdf = $pdf->subject($subject);
Get/set/clear the subject of the document.
keywords
$keywords = $pdf->keywords();
$pdf = $pdf->keywords($keywords);
Get/set/clear a space-separated string of keywords associated with the document.
creator
$creator = $pdf->creator();
$pdf = $pdf->creator($creator);
Get/set/clear the name of the product that created the document prior to its conversion to PDF.
producer
$producer = $pdf->producer();
$pdf = $pdf->producer($producer);
Get/set/clear the name of the product that converted the original document to PDF.
PDF::Builder fills in this field when creating a PDF.
created
$date = $pdf->created();
$pdf = $pdf->created($date);
Get/set/clear the document's creation date.
The date format is "D:YYYYMMDDHHmmSSOHH'mm", where "D:" is a static prefix identifying the string as
a PDF date. The date may be truncated at any point after the year. "O" is one of "+", "-", or "Z",
with the following "HH'mm" representing an offset from UTC.
See comments in the internal function "_is_date()" for more information on the inconsistency of PDF
standards on exactly what the date format should be!
When setting the date, "D:" will be prepended automatically if omitted.
modified
$date = $pdf->modified();
$pdf = $pdf->modified($date);
Get/set/clear the document's modification date. The date format is as described in "created" above.
See comments in the internal function "_is_date()" for more information on the inconsistency of PDF
standards on exactly what the date format should be!
info_metadata
%info = $pdf->info_metadata(); # Get all keys and values
$value = $pdf->info_metadata($key); # Get the value of one key
$pdf = $pdf->info_metadata($key, $value); # Set the value of one key
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.
Pass "undef" as the value in order to remove the key from the dictionary.
See comments in the internal function "_is_date()" for more information on the inconsistency of PDF
standards on exactly what the date format should be! This applies to CreationDate and ModDate keys.
info
%infohash = $pdf->info()
%infohash = $pdf->info(%infohash)
Gets/sets the info structure of the document.
See "info Example" in PDF::Builder::Docs section for an example of the use of this method.
Note: this method is still available, for compatibility purposes. It is better to use individual
accessors or "info_metadata" instead.
infoMetaAttributes
@metadata_attributes = $pdf->infoMetaAttributes()
@metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
Gets/sets the supported info-structure tags.
Example:
@attributes = $pdf->infoMetaAttributes;
print "Supported Attributes: @attr\n";
@attributes = $pdf->infoMetaAttributes('CustomField1');
print "Supported Attributes: @attributes\n";
Note: this method is still available for compatibility purposes, but the use of "info_metadata"
instead is encouraged.
xml_metadata
$xml = $pdf->xml_metadata();
$pdf = $pdf->xml_metadata($xml);
Gets/sets the document's XML metadata stream.
xmpMetadata
$xml = $pdf->xmpMetadata() # Get
$xml = $pdf->xmpMetadata($xml) # Set (also returns $xml value)
Gets/sets the XMP XML data stream.
See "XMP XML example" in PDF::Builder::Docs section for an example of the use of this method.
This method is considered obsolete. Use "xml_metadata" instead.
default
$val = $pdf->default($parameter)
$pdf->default($parameter, $value)
Gets/sets the default value for a behavior of PDF::Builder.
Supported Parameters:
nounrotate
prohibits Builder from rotating imported/opened page to re-create a default pdf-context.
pageencaps
enables Builder's adding save/restore commands upon importing/opening pages to preserve graphics-
state for modification.
copyannots
enables importing of annotations (*EXPERIMENTAL*).
CAUTION: Perl::Critic (tools/1_pc.pl) has started flagging the name "default" as a reserved keyword
in higher Perl versions. Use with caution, and be aware that this name may have to be changed in the
future.
version
$version = $pdf->version() # Get
$version = $pdf->version($version) # Set (also returns newly set version)
Gets/sets the PDF version (e.g., 1.5). For compatibility with earlier releases, if no decimal point
is given, assume "1." precedes the number given.
A warning message is given if you attempt to decrease the PDF version, as you might have already read
in a higher level file, or used a higher level feature.
See PDF::Builder::Basic::PDF::File for additional information on the "version" method.
is_encrypted, isEncrypted
$bool = $pdf->is_encrypted()
Checks if the previously opened PDF is encrypted.
Alternate name: "isEncrypted"
This is the older name; it is kept for compatibility with PDF::API2.
INTERACTIVE FEATURE METHODS
outline, outlines
$otls = $pdf->outline()
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 PDF reader being used.
To examine or modify the outline tree, see PDF::Builder::Outlines.
Alternate name: "outlines"
This is the older name; it is kept for compatibility.
page_layout
$layout = $pdf->page_layout();
$pdf = $pdf->page_layout($layout);
Gets/sets the page layout that should be used when the PDF is opened.
$layout is one of the following:
single_page (or undef)
Display one page at a time.
one_column
Display the pages in one column (a.k.a. continuous).
two_column_left
Display the pages in two columns, with odd-numbered pages on the left.
two_column_right
Display the pages in two columns, with odd-numbered pages on the right.
two_page_left
Display two pages at a time, with odd-numbered pages on the left.
two_page_right
Display two pages at a time, with odd-numbered pages on the right.
This has been split out from "preferences()" for compatibility with PDF::API2. It also can both set
(assign) and get (query) the settings used.
page_mode
$mode = $pdf->page_mode(); # Get
$pdf = $pdf->page_mode($mode); # Set
Gets/sets the page mode, which describes how the PDF should be displayed when opened.
$mode is one of the following:
none (or undef)
Neither outlines nor thumbnails should be displayed.
outlines
Show the document outline.
thumbnails
Show the page thumbnails.
full_screen
Open in full-screen mode, with no menu bar, window controls, or any other window visible.
optional_content
Show the optional content group panel.
attachments
Show the attachments panel.
This has been split out from "preferences()" for compatibility with PDF::API2. It also can both set
(assign) and get (query) the settings used.
viewer_preferences
%preferences = $pdf->viewer_preferences(); # Get
$pdf = $pdf->viewer_preferences(%preferences); # Set
Gets/sets PDF viewer preferences, as described in PDF::Builder::ViewerPreferences.
This has been split out from "preferences()" for compatibility with PDF::API2. It also can both set
(assign) and get (query) the settings used.
preferences
$pdf->preferences(%opts)
Controls viewing preferences for the PDF, including the Page Mode, Page Layout, Viewer, and Initial
Page Options. See "Preferences - set user display preferences" in PDF::Builder::Docs for details on
all these option groups, and "Page Fit Options" in PDF::Builder::Docs for page positioning.
Note: the various preferences have been split out into their own methods. It is preferred that you
use these specific methods.
PAGE METHODS
page
$page = $pdf->page()
$page = $pdf->page($page_number)
Returns a new page object. By default, the page is added to the end of the document. If you give an
existing page number, the new page will be inserted in that position, pushing existing pages back by
1 (e.g., page(5) would insert an empty page 5, with the old page 5 now page 6, etc.
If $page_number is -1, the new page is inserted as the second-to-last page; if $page_number is 0, the
new page is inserted as the last page.
Example:
$pdf = PDF::Builder->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);
open_page, openpage
$page = $pdf->open_page($page_number)
Returns the PDF::Builder::Page object of page $page_number. This is similar to "$page =
$pdf->page()", except that $page is not a new, empty page; but contains the contents of that existing
page.
If $page_number is 0, -1, or unspecified, it will return the last page in the document. If the
requested page is out of range, the $page returned will be undefined.
Example:
$pdf = PDF::Builder->open('our/99page.pdf');
$page = $pdf->open_page(1); # returns the first page
$page = $pdf->open_page(99); # returns the last page
$page = $pdf->open_page(-1); # returns the last page
$page = $pdf->open_page(999); # returns undef
$page = $pdf->open_page(0); # returns the last page
$page = $pdf->open_page(); # returns the last page
Alternate name: "openpage"
This is the older name; it is kept for compatibility until after June 2023 (deprecated, as previously
announced).
import_page, importpage
$page = $pdf->import_page($source_pdf)
$page = $pdf->import_page($source_pdf, $source_page_number)
$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)
$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_object)
Imports a page from $source_pdf and adds it to the specified position in $pdf.
If the $source_page_number is omitted, 0, or -1; the last page of the source is imported. If the
$target_page_number is omitted, 0, or -1; the imported page will be placed as the new last page of
the target ($pdf). Otherwise, as with the "page()" method, the page will be inserted before an
existing page of that number.
Note: If you pass a page object instead of a page number for $target_page_number, the contents of the
page will be merged into the existing page.
Example:
my $pdf = PDF::Builder->new();
my $source = PDF::Builder->open('source.pdf');
# Add page 2 from the old PDF as page 1 of the new PDF
my $page = $pdf->import_page($source, 2);
$pdf->saveas('sample.pdf');
Note: You can only import a page from an existing PDF file.
Alternate name: importpage
This name is still valid in PDF::API2, so it is included here for compatiblity.
embed_page, importPageIntoForm
$xoform = $pdf->embed_page($source_pdf, $source_page_number)
Returns a Form XObject created by extracting the specified page from $source_pdf.
This is useful if you want to transpose the imported page somewhat differently onto a page (e.g. two-
up, four-up, etc.).
If $source_page_number is 0 or -1, it will return the last page in the document. The default value
for the $source_page_number is 0 (return last page).
Example:
# take page 2 of source.pdf and add to empty doc sample.pdf at half size
# note that sample.pdf could be an existing document!
#
my $pdf = PDF::Builder->new(); # so far, empty document
my $source = PDF::Builder->open('source.pdf'); # content to copy over
my $page = $pdf->page(); # place to be actually updated
# Import Page 2 from the source PDF
my $xo = $pdf->embed_page($source, 2);
# Add it to the new PDF's first page at 1/2 scale
my ($x, $y) = (0, 0);
$page->object($xo, $x, $y, 0.5);
$pdf->save('sample.pdf');
Note: You can only import a page from an existing PDF file.
Alternate name: "importPageIntoForm"
This is the older name; it is kept for compatibility.
page_count, pages
$count = $pdf->page_count()
Returns the number of pages in the document.
Alternate name: "pages"
This is the old name; it is kept for compatibility.
page_labels, pageLabel
$pdf->page_labels($page_number, %opts)
Sets page label numbering format, for the PDF Reader's page-selection slider thumb (not the
outline/bookmarks). At this time, there is no method to automatically synchronize a page's label with
the outline/bookmarks, or to somewhere on the printed page. Depending on the PDF Reader you are
using, this formatted page label may show up in the reader control area as the current page number.
CAUTIONS:
1. The given page index started at 0 for the old method ("pageLabel()"), which is the internal PDF array
index, while for the new method ("page_labels()") it starts with 1, the visible page number! Don't
get confused.
2. Options for the old method ("pageLabel") were a hashref, while for the new method ("page_labels") it
is a hash. This permits pageLabel() to accept multiple page number schemes in one call, rather than
one per call as per page_labels().
3. Many PDF readers do not support page labels; they simply (at most) label the sliding thumb with the
physical page number. Adobe Acrobat Reader (free version) appears to have a bug in some versions,
where if the only page label is 'decimal' (the default), it labels the thumb as though no page labels
were defined ("Page m of n"). You may be able to get around this problem by using an explicit start
option value, e.g., "'start' => 1".
# Generate a 30-page PDF
my $pdf = PDF::Builder->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' => 'roman');
$pdf->page_labels(6, 'style' => 'decimal');
$pdf->page_labels(26, 'style' => 'decimal', 'prefix' => 'A-');
or...
$pdf->pageLabel(0, { style => 'roman' },
5, { style => 'decimal' },
25, { style => 'decimal', prefix => 'A-' });
$pdf->save('sample.pdf');
Supported Options:
style
Roman (I,II,III,...), roman (i,ii,iii,...), decimal (1,2,3,...), Alpha (A,B,C,...), alpha
(a,b,c,...), or nocounter. This is the styling of the counter part of the label (unless "nocounter",
in which case there is no counter output).
start
(Re)start numbering the counter at given page number (this is a decimal integer, not the styled
counter). By default it starts at 1, and resets to 1 at each call to "page_labels()"! You need to
explicitly give "start" if you want to continue counting at the current page number when you call
"page_labels()", whether or not you are changing the format.
Also note that the counter starts at physical page 1, while the page $index number in the
"page_labels()" call (as well as the PDF PageLabels dictionary) starts at logical page (index) 0.
prefix
Text prefix for numbering, such as an Appendix letter B-. If "style" is nocounter, just this text is
used, otherwise a styled counter will be appended. If "style" is omitted, remember that it will
default to a decimal number, which will be appended to the prefix.
According to the Adobe/ISO PDF specification, a prefix of 'Content' has a special meaning, in that
any /S counter is ignored and only that text is used. However, this appears to be ignored (use a
style of nocounter to suppress the counter).
Dotted inserted page numbers
To easily insert a range of pages, e.g., 3 pages between existing pages 37 and 38, use a "prefix" of
'37.' and decimal numbering starting ("start") at 1 or a specified point. This would produce pages
37.1, 37.2, and 37.3. To put leading 0's on the numbers, if you find that you later need to insert
additional pages between those, e.g., page 37.05 between 37 and 37.1, use a "prefix" of '37.0' and
"start" at 5.
Just remember that only the (rightmost) counter, which begins at the "start" value, is incremented
(and formatted) by the PDF Reader. Everything else (the "prefix") is a constant string. At worst, you
might have to define a page label for each individual page.
Example:
# Start with lowercase Roman Numerals at the 1st page, starting with i (1)
$pdf->page_labels(1,
'style' => 'roman',
);
or,
$pdf->pageLabel(0,
{ 'style' => 'roman' },
);
# Switch to Arabic (decimal) at the 5th page, starting with 1
$pdf->page_labels(5,
'style' => 'decimal',
);
or,
$pdf->pageLabel(4,
{ 'style' => 'decimal' },
);
# invalid style at the 25th page, should just continue
# with decimal at the current counter
$pdf->page_labels(25,
'style' => 'raman_noodles', # fail over to decimal
# note that older versions of PDF::API2 may see the 'r' and
# treat it as 'roman'
'start' => 25, # necessary, otherwise would restart at 1
);
# No page label at the 31st and 32nd pages. Note that this could be
# confusing to the person viewing the PDF, but may be appropriate if
# the page itself has no numbering.
$pdf->page_labels(31,
'style' => 'nocounter',
);
# Numbering for Appendix A at the 33rd page, A-1, A-2,...
$pdf->page_labels(33,
'start' => 1, # unnecessary
'prefix' => 'A-'
);
# Numbering for Appendix B at the 37th page, B-1, B-2,...
$pdf->page_labels(37,
'prefix' => 'B-'
);
# Numbering for the Index at the 41st page, Index I, Index II,...
$pdf->page_labels(41,
'style' => 'Roman',
'start' => 1, # unnecessary
'prefix' => 'Index ' # note trailing space
);
# Unnumbered 'Index' at the 45th page, Index, Index,...
$pdf->page_labels(45,
'style' => 'nocounter',
'prefix' => 'Index '
);
Alternate name: "pageLabel"
This old method name is retained for compatibility with old user code. Note that with "pageLabel",
you need to make the "options" list an anonymous hash by placing { } around the entire list, even if
it has only one item in it. Also remember that the page number (index) for "pageLabel" starts at 0
(same as the PDF page index), rather than 1 (as in "page_labels"). Finally, pageLabel() still
permits you to define multiple page numbering schemes in one call.
userunit
$pdf->userunit($value)
Sets the global UserUnit, defining the scale factor to multiply any size or coordinate by. For
example, "userunit(72)" results in a User Unit of 72 points, or 1 inch.
See "User Units" in PDF::Builder::Docs for more information.
mediabox
$pdf->mediabox($name)
$pdf->mediabox($name, 'orient' => 'orientation')
$pdf->mediabox($w,$h)
$pdf->mediabox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $pdf->mediabox()
Sets (or gets) the global MediaBox, defining the width and height (or by corner coordinates, or by
standard name) of the output page itself, such as the physical paper size.
See "Media Box" in PDF::Builder::Docs for more information. The method always returns the current
bounds (after any set operation).
cropbox
$pdf->cropbox($name)
$pdf->cropbox($name, 'orient' => 'orientation')
$pdf->cropbox($w,$h)
$pdf->cropbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $pdf->cropbox()
Sets (or gets) the global CropBox. This will define the media size to which the output will later be
clipped.
See "Crop Box" in PDF::Builder::Docs for more information. The method always returns the current
bounds (after any set operation).
bleedbox
$pdf->bleedbox($name)
$pdf->bleedbox($name, 'orient' => 'orientation')
$pdf->bleedbox($w,$h)
$pdf->bleedbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $pdf->bleedbox()
Sets (or gets) the global BleedBox. This is typically used for hard copy printing where you want ink
to go to the edge of the cut paper.
See "Bleed Box" in PDF::Builder::Docs for more information. The method always returns the current
bounds (after any set operation).
trimbox
$pdf->trimbox($name)
$pdf->trimbox($name, 'orient' => 'orientation')
$pdf->trimbox($w,$h)
$pdf->trimbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $pdf->trimbox()
Sets (or gets) the global TrimBox. This is supposed to be the actual dimensions of the finished page
(after trimming of the paper).
See "Trim Box" in PDF::Builder::Docs for more information. The method always returns the current
bounds (after any set operation).
artbox
$pdf->artbox($name)
$pdf->artbox($name, 'orient' => 'orientation')
$pdf->artbox($w,$h)
$pdf->artbox($llx,$lly, $urx,$ury)
($llx,$lly, $urx,$ury) = $pdf->artbox()
Sets (or gets) the global ArtBox. This is supposed to define "the extent of the page's meaningful
content". What is considered "meaningful" is up to the author of the page, but would usually exclude
"decorative" graphics and such; and possibly titles, headers, footers, and page numbers.
See "Art Box" in PDF::Builder::Docs for more information. The method always returns the current
bounds (after any set operation).
FONT METHODS
Embedding of Fonts
CAUTION: Some font routines (currently only "ttfont()") automatically embed font definitions for the
purpose of improving portability of PDF files. Note that font copyright and licensing terms vary by font
provider, and some may prohibit embedding of their fonts, either entirely, or allowing only the subset of
glyphs actually used in the document. You should be aware of the terms, and use the "noembed" or
"nosubset" flags as appropriate. The PDF::Builder font routines currently have no means to automatically
detect any embedding limitations for a given font, and cannot default their behavior accordingly!
corefont
$font = $pdf->corefont($fontname, %opts)
Returns a new Adobe core font object. For details, see "Core Fonts" in PDF::Builder::Docs. Note that
this is an Adobe-standard corefont name, and not a file name.
See also PDF::Builder::Resource::Font::CoreFont.
psfont
$font = $pdf->psfont($ps_file, %opts)
Returns a new Adobe Type1 ("PostScript", "T1") font object. For details, see "PS Fonts" in
PDF::Builder::Docs.
See also PDF::Builder::Resource::Font::Postscript.
ttfont
$font = $pdf->ttfont($ttf_file, %opts)
Returns a new TrueType (or OpenType) font object. For details, see "TrueType Fonts" in
PDF::Builder::Docs.
bdfont
$font = $pdf->bdfont($bdf_file, @opts)
Returns a new BDF (bitmapped distribution format) font object, based on the specified Adobe BDF file.
These are very low resolution fonts that appear to have come off a dot-matrix printer.
See also PDF::Builder::Resource::Font::BdFont
cjkfont
$font = $pdf->cjkfont($cjkname, %opts)
Returns a new CJK font object. These are TrueType-like fonts for East Asian languages (Chinese,
Japanese, Korean). For details, see "CJK Fonts" in PDF::Builder::Docs.
NOTE: "cjkfont" is quite old and is not well supported. We recommend that you try using "ttfont" (or
another font routine, if not TTF/OTF) with the appropriate CJK font file. Most appear to be .ttf or
.otf format. PDFs created using "cjkfont" may not be fully portable, and support for "cjkfont" may be
dropped in a future release. We would appreciate hearing from you if you are successfully using
"cjkfont", and are unable to use "ttfont" instead.
Among other things, "cjkfont" selections are limited, as they require CMAP files; they may or may not
subset correctly; and they can not be used as the base for synthetic fonts.
See also PDF::Builder::Resource::CIDFont::CJKFont
font
$font = $pdf->font($name, %opts)
A convenience function to add a font to the PDF without having to specify the format. Returns the
font object, to be used by PDF::Builder::Content.
The font $name is either the name of one of the standard 14 fonts ("STANDARD FONTS" in
PDF::Builder::Resource::Font::CoreFont), such as Helvetica or the path to a font file. There are 15
additional core fonts on a Windows system. Note that the exact name of a core font needs to be
given. The file extension (if path given) determines what type of font file it is.
my $pdf = PDF::Builder->new();
my $font1 = $pdf->font('Helvetica-Bold');
my $font2 = $pdf->font('/path/to/ComicSans.ttf');
my $page = $pdf->page();
my $content = $page->text();
$content->position(1 * 72, 9 * 72);
$content->font($font1, 24);
$content->text('Hello, World!');
$content->position(0, -36);
$content->font($font2, 12);
$content->text('This is some sample text.');
$pdf->saveas('sample.pdf');
The path can be omitted if the font file is in the current directory or one of the directories
returned by "font_path".
TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph Bitmap Distribution Format
(bdf) fonts are supported.
The following options (%opts) are available:
format
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 "format" to one of "truetype" (TrueType or OpenType),
"type1" (PostScript Type 1), or "bitmap" (Adobe Bitmap).
dokern
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.
afm_file (PostScript Type 1 fonts only)
Specifies the location of the font metrics file.
pfm_file (PostScript Type 1 fonts only)
Specifies the location of the printer font metrics file. This option overrides the encode option.
embed (TrueType fonts only)
Fonts are embedded in the PDF 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.
font_path
@directories = PDF::Builder->font_path()
Return the list of directories that will be searched (in order) in addition to the current directory
when you add a font to a PDF without including the full path to the font file.
add_to_font_path, addFontDirs
@directories = PDF::Builder::add_to_font_path('/my/fonts', '/path/to/fonts', ...)
Adds one or more directories to the list of paths to be searched for font files.
Returns the font search path.
Alternate name: "addFontDirs"
Prior to recent changes to PDF::API2, this method was addFontDirs(). This method is still available,
but may be deprecated some time in the future.
set_font_path
@directories = PDF::Builder->set_font_path('/my/fonts', '/path/to/fonts');
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.
Returns the font search path.
synfont, synthetic_font
$font = $pdf->synfont($basefont, %opts)
Returns a new synthetic font object. These are modifications to a core (or PS/T1 or TTF/OTF) font,
where the font may be replaced by a Type1 or Type3 PostScript font. This does not appear to work
with CJK fonts (created with "cjkfont" method). For details, see "Synthetic Fonts" in
PDF::Builder::Docs.
See also PDF::Builder::Resource::Font::SynFont
Alternate name: "synthetic_font"
Prior to recent PDF::API2 changes, the routine to create modified fonts was "synfont". PDF::API2 has
renamed it to "synthetic_font", which I don't like, but to maintain compatibility, "synthetic_font"
is available as an alias.
There are also some minor option differences (incompatibilities) discussed in "SynFont", including
the value of 'bold' between the two entry points.
unifont
$font = $pdf->unifont(@fontspecs, %opts)
Returns a new uni-font object, based on the specified fonts and options.
BEWARE: This is not a true PDF-object, but a virtual/abstract font definition!
See also PDF::Builder::Resource::UniFont.
Valid options (%opts) are:
encode
Changes the encoding of the font from its default.
Font Manager methods
The Font Manager is automatically initialized.
font_settings
@list = $pdf->font_settings() # Get
$pdf->font_settings(%info) # Set
Change one or more default settings. See PDF::Builder::FontManager/font_settings for details.
add_font_path
$rc = $pdf->add_font_path("a directory path", %opts)
Add a search path for Font Manager font entries. See PDF::Builder::FontManager/add_font_path for
details.
add_font
$rc = $pdf->add_font(%info)
Add a font (face) definition to the Font Manager list. See PDF::Builder::FontManager/add_font for
details.
get_font
@current = $pdf->get_font() # Get
$font = $pdf->get_font(%info) # Set
Retrieve a ready-to-use font, or find out what the current one is. See
PDF::Builder::FontManager/get_font for details.
dump_font_tables
$pdf->dump_font_tables()
Dump all known font information to STDOUT. See PDF::Builder::FontManager/dump_font_tables for
details.
IMAGE METHODS
image
$object = $pdf->image($file, %opts);
A convenience function to attempt to determine the image type, and import a file of that type and
return an object that can be placed as part of a page's content:
my $pdf = PDF::Builder->new();
my $page = $pdf->page();
my $image = $pdf->image('/path/to/image.jpg');
$page->object($image, 100, 100);
$pdf->save('sample.pdf');
$file may be either a file name, a filehandle, or a PDF::Builder::Resource::XObject::Image::GD
object.
Caution: Do not confuse this "image" ($pdf->) with the image method found in the graphics (gfx) class
($gfx->), used to actually place a read-in or decoded image on the page!
See "image" in PDF::Builder::Content for details about placing images on a page once they're
imported.
The image format is normally detected automatically based on the file's extension (.gif, .png,
.tif/.tiff, .jpg/.jpeg, .pnm/.pbm/.pgm/.ppm). If passed a filehandle, image formats GIF, JPEG, PNM,
and PNG will be detected based on the file's header. Unfortunately, at this time, other image formats
(TIFF and GD) cannot be automatically detected. (TIFF could be, except that "image_tiff()" cannot use
a filehandle anyway as input when using the libtiff library, which is highly recommended.)
If the file has an atypical extension or the filehandle is for a different kind of image, you can set
the "format" option to one of the supported types: "gif", "jpeg", "png", "pnm", or "tiff".
Note: PNG images that include an alpha (transparency) channel go through a relatively slow process of
splitting the image into separate RGB and alpha components as is required by images in PDFs. If
you're having performance issues, install Image::PNG::Libpng to speed this process up by an order of
magnitude; either module will be used automatically if available. See the "image_png" method for
details.
Note: TIFF image processing is very slow if using the pure Perl decoder. We highly recommend using
the Graphics::TIFF library to improve performance. See the "image_tiff" method for details.
image_jpeg
$jpeg = $pdf->image_jpeg($file, %opts)
Imports and returns a new JPEG image object. $file may be either a filename or a filehandle.
See PDF::Builder::Resource::XObject::Image::JPEG for additional information and "examples/Content.pl"
for some examples of placing an image on a page.
image_tiff
$tiff = $pdf->image_tiff($file, %opts)
Imports and returns a new TIFF image object. $file may be either a filename or a filehandle. For
details, see "TIFF Images" in PDF::Builder::Docs.
See PDF::Builder::Resource::XObject::Image::TIFF and PDF::Builder::Resource::XObject::Image::TIFF_GT
for additional information and "examples/Content.pl" for some examples of placing an image on a page
(JPEG, but the principle is the same). There is an optional TIFF library (TIFF_GT) described, that
gives more capability than the default one. However, note that $file can only be a filename when
using this library.
LA_GT
$rc = $pdf->LA_GT()
Returns 1 if the library name (package) Graphics::TIFF is installed, and 0 otherwise. For this
optional library, this call can be used to know if it is safe to use certain functions. For example:
if ($pdf->LA_GT() {
# is installed and usable
} else {
# not available. you will be running the old, pure PERL code
}
image_pnm
$pnm = $pdf->image_pnm($file, %opts)
Imports and returns a new PNM image object. $file may be either a filename or a filehandle.
See PDF::Builder::Resource::XObject::Image::PNM for additional information and "examples/Content.pl"
for some examples of placing an image on a page (JPEG, but the principle is the same).
image_png
$png = $pdf->image_png($file, %opts)
Imports and returns a new PNG image object. $file may be either a filename or a filehandle. For
details, see "PNG Images" in PDF::Builder::Docs.
See PDF::Builder::Resource::XObject::Image::PNG and PDF::Builder::Resource::XObject::Image::PNG_IPL
for additional information and "examples/Content.pl" for some examples of placing an image on a page
(JPEG, but the principle is the same).
There is an optional PNG library (PNG_IPL) described, that gives more capability than the default
one. However, note that $file can only be a filename when using this library.
LA_IPL
$rc = $pdf->LA_IPL()
Returns 1 if the library name (package) Image::PNG::Libpng is installed, and 0 otherwise. For this
optional library, this call can be used to know if it is safe to use certain functions. For example:
if ($pdf->LA_IPL() {
# is installed and usable
} else {
# not available. don't use 16bps or interlaced PNG image files
}
image_gif
$gif = $pdf->image_gif($file, %opts)
Imports and returns a new GIF image object. $file may be either a filename or a filehandle.
See PDF::Builder::Resource::XObject::Image::GIF for additional information and "examples/Content.pl"
for some examples of placing an image on a page (JPEG, but the principle is the same).
image_gd
$gdf = $pdf->image_gd($gd_object, %opts)
Imports and returns a new image object from Image::GD.
See PDF::Builder::Resource::XObject::Image::GD for additional information and "examples/Content.pl"
for some examples of placing an image on a page (JPEG, but the principle is the same).
COLORSPACE METHODS
colorspace
$colorspace = $pdf->colorspace($type, @arguments)
Colorspaces can be added to a PDF 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, ACT file).
Once added to the PDF, they can be used in place of regular hex codes or named colors:
my $pdf = PDF::Builder->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('spot', 'PANTONE Red 032 C', '#EF3340');
my $web = $pdf->colorspace('web');
# 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('sample.pdf');
The following types of colorspaces are supported
spot
Spot colors are used to instruct a device (usually a printer) to use or emulate a particular ink
color ($tint) for parts of the document. An $alt_color is provided for devices (e.g. PDF viewers)
that don't know how to produce the named color. It can either be an approximation of the color in
RGB, CMYK, or HSV formats, or a wildly different color (e.g. 100% magenta, %0F00) to make it clear if
the spot color isn't being used as expected.
my $spot = $pdf->colorspace('spot', $tint, $alt_color);
web The web-safe color palette is a historical collection of colors that was used when many display
devices only supported 256 colors.
my $web = $pdf->colorspace('web');
act An Adobe Color Table (ACT) file provides a custom palette of colors that can be referenced by PDF
graphics and text drawing commands.
my $act = $pdf->colorspace('act', $filename);
device
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).
my $devicen = $pdf->colorspace('device', @colorspaces);
Device colorspaces are also needed if you want to blend spot colors:
my $pdf = PDF::Builder->new();
my $page = $pdf->page();
my $content = $page->graphics();
# Create a two-color device colorspace
my $yellow = $pdf->colorspace('spot', 'Yellow', '%00F0');
my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
my $device = $pdf->colorspace('device', $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('sample.pdf');
colorspace_act
$cs = $pdf->colorspace_act($file)
Returns a new colorspace object based on an Adobe Color Table file.
See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a reference to the file format's
specification.
colorspace_web
$cs = $pdf->colorspace_web()
Returns a new colorspace-object based on the "web-safe" color palette.
colorspace_hue
$cs = $pdf->colorspace_hue()
Returns a new colorspace-object based on the hue color palette.
See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an explanation.
colorspace_separation
$cs = $pdf->colorspace_separation($tint, $color)
Returns a new separation colorspace object based on the parameters.
$tint can be any valid ink identifier, including but not limited to: 'Cyan', 'Magenta', 'Yellow',
'Black', 'Red', 'Green', 'Blue' or 'Orange'.
$color must be a valid color specification limited to: '#rrggbb', '!hhssvv', '%ccmmyykk' or a "named
color" (rgb).
The colorspace model will automatically be chosen based on the specified color.
colorspace_devicen
$cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
$cs = $pdf->colorspace_devicen(\@tintCSx)
Returns a new DeviceN colorspace object based on the parameters.
Example:
$cy = $pdf->colorspace_separation('Cyan', '%f000');
$ma = $pdf->colorspace_separation('Magenta', '%0f00');
$ye = $pdf->colorspace_separation('Yellow', '%00f0');
$bk = $pdf->colorspace_separation('Black', '%000f');
$pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
$dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
The colorspace model will automatically be chosen based on the first colorspace specified.
BARCODE METHODS
These are glue routines to the actual barcode rendering routines found elsewhere.
xo_* Bar Code routines
$bc = $pdf->xo_codabar(%opts)
$bc = $pdf->xo_code128(%opts)
$bc = $pdf->xo_2of5int(%opts)
$bc = $pdf->xo_3of9(%opts)
$bc = $pdf->xo_ean13(%opts)
Creates the specified barcode object as a form XObject.
OTHER METHODS
xo_form
$xo = $pdf->xo_form()
Returns a new form XObject.
egstate
$egs = $pdf->egstate()
Returns a new extended graphics state object, as described in PDF::Builder::Resource::ExtGState.
pattern
$obj = $pdf->pattern(%opts)
Returns a new pattern object.
shading
$obj = $pdf->shading(%opts)
Returns a new shading object.
named_destination
$ndest = $pdf->named_destination()
Returns a new or existing named destination object.