1PDF::API2(3) User Contributed Perl Documentation PDF::API2(3)
2
6 PDF::API2 - Facilitates the creation and modification of PDF files
7
9 use PDF::API2;
10 # Create a blank PDF file
12 $pdf = PDF::API2->new();
13 # Open an existing PDF file
15 $pdf = PDF::API2->open('some.pdf');
16 # Add a blank page
18 $page = $pdf->page();
19 # Retrieve an existing page
21 $page = $pdf->openpage($page_number);
22 # Set the page size
24 $page->mediabox('Letter');
25 # Add a built-in font to the PDF
27 $font = $pdf->corefont('Helvetica-Bold');
28 # Add an external TTF font to the PDF
30 $font = $pdf->ttfont('/path/to/font.ttf');
31 # Add some text to the page
33 $text = $pdf->text();
34 $text->font($font, 20);
35 $text->translate(200, 700);
36 $text->text('Hello World!');
37 # Save the PDF
39 $pdf->saveas('/path/to/new.pdf');
40
42 $pdf = PDF::API2->new(%options)
43 Creates a new PDF object. If you will be saving it as a file and
44 already know the filename, you can give the '-file' option to
45 minimize possible memory requirements later on.
46 Example:
48 $pdf = PDF::API2->new();
50 ...
51 print $pdf->stringify();
52 $pdf = PDF::API2->new();
54 ...
55 $pdf->saveas('our/new.pdf');
56 $pdf = PDF::API2->new(-file => 'our/new.pdf');
58 ...
59 $pdf->save();
60 $pdf = PDF::API2->open($pdf_file)
62 Opens an existing PDF file.
63 Example:
65 $pdf = PDF::API2->open('our/old.pdf');
67 ...
68 $pdf->saveas('our/new.pdf');
69 $pdf = PDF::API2->open('our/to/be/updated.pdf');
71 ...
72 $pdf->update();
73 $pdf = PDF::API2->openScalar($pdf_string)
75 Opens a PDF contained in a string.
76 Example:
78 # Read a PDF into a string, for the purpose of demonstration
80 open $fh, 'our/old.pdf' or die $@;
81 undef $/; # Read the whole file at once
82 $pdf_string = <$fh>;
83 $pdf = PDF::API2->openScalar($pdf_string);
85 ...
86 $pdf->saveas('our/new.pdf');
87 $pdf->preferences(%options)
89 Controls viewing preferences for the PDF.
90 Page Mode Options:
92 -fullscreen
94 Full-screen mode, with no menu bar, window controls, or any
95 other window visible.
96 -thumbs
98 Thumbnail images visible.
99 -outlines
101 Document outline visible.
102 Page Layout Options:
104 -singlepage
106 Display one page at a time.
107 -onecolumn
109 Display the pages in one column.
110 -twocolumnleft
112 Display the pages in two columns, with oddnumbered pages on the
113 left.
114 -twocolumnright
116 Display the pages in two columns, with oddnumbered pages on the
117 right.
118 Viewer Options:
120 -hidetoolbar
122 Specifying whether to hide tool bars.
123 -hidemenubar
125 Specifying whether to hide menu bars.
126 -hidewindowui
128 Specifying whether to hide user interface elements.
129 -fitwindow
131 Specifying whether to resize the document's window to the size
132 of the displayed page.
133 -centerwindow
135 Specifying whether to position the document's window in the
136 center of the screen.
137 -displaytitle
139 Specifying whether the window's title bar should display the
140 document title taken from the Title entry of the document
141 information dictionary.
142 -afterfullscreenthumbs
144 Thumbnail images visible after Full-screen mode.
145 -afterfullscreenoutlines
147 Document outline visible after Full-screen mode.
148 -printscalingnone
150 Set the default print setting for page scaling to none.
151 Initial Page Options:
153 -firstpage => [ $page, %options ]
155 Specifying the page to be displayed, plus one of the following
156 options:
157 -fit => 1
159 Display the page designated by page, with its contents
160 magnified just enough to fit the entire page within the
161 window both horizontally and vertically. If the required
162 horizontal and vertical magnification factors are
163 different, use the smaller of the two, centering the page
164 within the window in the other dimension.
165 -fith => $top
167 Display the page designated by page, with the vertical
168 coordinate top positioned at the top edge of the window and
169 the contents of the page magnified just enough to fit the
170 entire width of the page within the window.
171 -fitv => $left
173 Display the page designated by page, with the horizontal
174 coordinate left positioned at the left edge of the window
175 and the contents of the page magnified just enough to fit
176 the entire height of the page within the window.
177 -fitr => [ $left, $bottom, $right, $top ]
179 Display the page designated by page, with its contents
180 magnified just enough to fit the rectangle specified by the
181 coordinates left, bottom, right, and top entirely within
182 the window both horizontally and vertically. If the
183 required horizontal and vertical magnification factors are
184 different, use the smaller of the two, centering the
185 rectangle within the window in the other dimension.
186 -fitb => 1
188 Display the page designated by page, with its contents
189 magnified just enough to fit its bounding box entirely
190 within the window both horizontally and vertically. If the
191 required horizontal and vertical magnification factors are
192 different, use the smaller of the two, centering the
193 bounding box within the window in the other dimension.
194 -fitbh => $top
196 Display the page designated by page, with the vertical
197 coordinate top positioned at the top edge of the window and
198 the contents of the page magnified just enough to fit the
199 entire width of its bounding box within the window.
200 -fitbv => $left
202 Display the page designated by page, with the horizontal
203 coordinate left positioned at the left edge of the window
204 and the contents of the page magnified just enough to fit
205 the entire height of its bounding box within the window.
206 -xyz => [ $left, $top, $zoom ]
208 Display the page designated by page, with the coordinates
209 (left, top) positioned at the top-left corner of the window
210 and the contents of the page magnified by the factor zoom.
211 A zero (0) value for any of the parameters left, top, or
212 zoom specifies that the current value of that parameter is
213 to be retained unchanged.
214 Example:
216 $pdf->preferences(
218 -fullscreen => 1,
219 -onecolumn => 1,
220 -afterfullscreenoutlines => 1,
221 -firstpage => [$page, -fit => 1],
222 );
223 $val = $pdf->default($parameter)
225 $pdf->default($parameter, $value)
226 Gets/sets the default value for a behaviour of PDF::API2.
227 Supported Parameters:
229 nounrotate
231 prohibits API2 from rotating imported/opened page to re-create
232 a default pdf-context.
233 pageencaps
235 enables than API2 will add save/restore commands upon
236 imported/opened pages to preserve graphics-state for
237 modification.
238 copyannots
240 enables importing of annotations (*EXPERIMENTAL*).
241 $bool = $pdf->isEncrypted()
243 Checks if the previously opened PDF is encrypted.
244 %infohash = $pdf->info(%infohash)
246 Gets/sets the info structure of the document.
247 Example:
249 %h = $pdf->info(
251 'Author' => "Alfred Reibenschuh",
252 'CreationDate' => "D:20020911000000+01'00'",
253 'ModDate' => "D:YYYYMMDDhhmmssOHH'mm'",
254 'Creator' => "fredos-script.pl",
255 'Producer' => "PDF::API2",
256 'Title' => "some Publication",
257 'Subject' => "perl ?",
258 'Keywords' => "all good things are pdf"
259 );
260 print "Author: $h{Author}\n";
261 @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
263 Gets/sets the supported info-structure tags.
264 Example:
266 @attributes = $pdf->infoMetaAttributes;
268 print "Supported Attributes: @attr\n";
269 @attributes = $pdf->infoMetaAttributes('CustomField1');
271 print "Supported Attributes: @attributes\n";
272 $xml = $pdf->xmpMetadata($xml)
274 Gets/sets the XMP XML data stream.
275 Example:
277 $xml = $pdf->xmpMetadata();
279 print "PDFs Metadata reads: $xml\n";
280 $xml=<<EOT;
281 <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
282 <?adobe-xap-filters esc="CRLF"?>
283 <x:xmpmeta
284 xmlns:x='adobe:ns:meta/'
285 x:xmptk='XMP toolkit 2.9.1-14, framework 1.6'>
286 <rdf:RDF
287 xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
288 xmlns:iX='http://ns.adobe.com/iX/1.0/'>
289 <rdf:Description
290 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
291 xmlns:pdf='http://ns.adobe.com/pdf/1.3/'
292 pdf:Producer='Acrobat Distiller 6.0.1 for Macintosh'></rdf:Description>
293 <rdf:Description
294 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
295 xmlns:xap='http://ns.adobe.com/xap/1.0/'
296 xap:CreateDate='2004-11-14T08:41:16Z'
297 xap:ModifyDate='2004-11-14T16:38:50-08:00'
298 xap:CreatorTool='FrameMaker 7.0'
299 xap:MetadataDate='2004-11-14T16:38:50-08:00'></rdf:Description>
300 <rdf:Description
301 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
302 xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/'
303 xapMM:DocumentID='uuid:919b9378-369c-11d9-a2b5-000393c97fd8'/></rdf:Description>
304 <rdf:Description
305 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
306 xmlns:dc='http://purl.org/dc/elements/1.1/'
307 dc:format='application/pdf'>
308 <dc:description>
309 <rdf:Alt>
310 <rdf:li xml:lang='x-default'>Adobe Portable Document Format (PDF)</rdf:li>
311 </rdf:Alt>
312 </dc:description>
313 <dc:creator>
314 <rdf:Seq>
315 <rdf:li>Adobe Systems Incorporated</rdf:li>
316 </rdf:Seq>
317 </dc:creator>
318 <dc:title>
319 <rdf:Alt>
320 <rdf:li xml:lang='x-default'>PDF Reference, version 1.6</rdf:li>
321 </rdf:Alt>
322 </dc:title>
323 </rdf:Description>
324 </rdf:RDF>
325 </x:xmpmeta>
326 <?xpacket end='w'?>
327 EOT
328 $xml = $pdf->xmpMetadata($xml);
330 print "PDF metadata now reads: $xml\n";
331 $pdf->pageLabel($index, $options)
333 Sets page label options.
334 Supported Options:
336 -style
338 Roman, roman, decimal, Alpha or alpha.
339 -start
341 Restart numbering at given number.
342 -prefix
344 Text prefix for numbering.
345 Example:
347 # Start with Roman Numerals
349 $pdf->pageLabel(0, {
350 -style => 'roman',
351 });
352 # Switch to Arabic
354 $pdf->pageLabel(4, {
355 -style => 'decimal',
356 });
357 # Numbering for Appendix A
359 $pdf->pageLabel(32, {
360 -start => 1,
361 -prefix => 'A-'
362 });
363 # Numbering for Appendix B
365 $pdf->pageLabel( 36, {
366 -start => 1,
367 -prefix => 'B-'
368 });
369 # Numbering for the Index
371 $pdf->pageLabel(40, {
372 -style => 'Roman'
373 -start => 1,
374 -prefix => 'Index '
375 });
376 $pdf->finishobjects(@objects)
378 Force objects to be written to file if possible.
379 Example:
381 $pdf = PDF::API2->new(-file => 'our/new.pdf');
383 ...
384 $pdf->finishobjects($page, $gfx, $txt);
385 ...
386 $pdf->save();
387 $pdf->update()
389 Saves a previously opened document.
390 Example:
392 $pdf = PDF::API2->open('our/to/be/updated.pdf');
394 ...
395 $pdf->update();
396 $pdf->saveas($file)
398 Saves the document to file.
399 Example:
401 $pdf = PDF::API2->new();
403 ...
404 $pdf->saveas('our/new.pdf');
405 $string = $pdf->stringify()
407 Returns the document as a string.
408 Example:
410 $pdf = PDF::API2->new();
412 ...
413 print $pdf->stringify();
414 $pdf->end()
416 Destroys the document.
417
419 $page = $pdf->page()
420 $page = $pdf->page($page_number)
421 Returns a new page object. By default, the page is added to the
422 end of the document. If you include an existing page number, the
423 new page will be inserted in that position, pushing existing pages
424 back.
425 $page_number can also have one of the following values:
427 -1 inserts the new page as the second-last page
429 0 inserts the page as the last page
430 Example:
432 $pdf = PDF::API2->new();
434 # Add a page. This becomes page 1.
436 $page = $pdf->page();
437 # Add a new first page. $page becomes page 2.
439 $another_page = $pdf->page(1);
440 $page = $pdf->openpage($page_number)
442 Returns the PDF::API2::Page object of page $page_number.
443 If $page_number is 0 or -1, it will return the last page in the
445 document.
446 Example:
448 $pdf = PDF::API2->open('our/99page.pdf');
450 $page = $pdf->openpage(1); # returns the first page
451 $page = $pdf->openpage(99); # returns the last page
452 $page = $pdf->openpage(-1); # returns the last page
453 $page = $pdf->openpage(999); # returns undef
454 $xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)
456 Returns a Form XObject created by extracting the specified page
457 from $source_pdf.
458 This is useful if you want to transpose the imported page somewhat
460 differently onto a page (e.g. two-up, four-up, etc.).
461 If $source_page_number is 0 or -1, it will return the last page in
463 the document.
464 Example:
466 $pdf = PDF::API2->new();
468 $old = PDF::API2->open('our/old.pdf');
469 $page = $pdf->page();
470 $gfx = $page->gfx();
471 # Import Page 2 from the old PDF
473 $xo = $pdf->importPageIntoForm($old, 2);
474 # Add it to the new PDF's first page at 1/2 scale
476 $gfx->formimage($xo, 0, 0, 0.5);
477 $pdf->saveas('our/new.pdf');
479 Note: You can only import a page from an existing PDF file.
481 $page = $pdf->importpage($source_pdf, $source_page_number,
483 $target_page_number)
484 Imports a page from $source_pdf and adds it to the specified
485 position in $pdf.
486 If $source_page_number or $target_page_number is 0 or -1, the last
488 page in the document is used.
489 Note: If you pass a page object instead of a page number for
491 $target_page_number, the contents of the page will be merged into
492 the existing page.
493 Example:
495 $pdf = PDF::API2->new();
497 $old = PDF::API2->open('our/old.pdf');
498 # Add page 2 from the old PDF as page 1 of the new PDF
500 $page = $pdf->importpage($old, 2);
501 $pdf->saveas('our/new.pdf');
503 Note: You can only import a page from an existing PDF file.
505 $count = $pdf->pages()
507 Returns the number of pages in the document.
508 $pdf->mediabox($name)
510 $pdf->mediabox($w, $h)
511 $pdf->mediabox($llx, $lly, $urx, $ury)
512 Sets the global mediabox.
513 Example:
515 $pdf = PDF::API2->new();
517 $pdf->mediabox('A4');
518 ...
519 $pdf->saveas('our/new.pdf');
520 $pdf = PDF::API2->new();
522 $pdf->mediabox(595, 842);
523 ...
524 $pdf->saveas('our/new.pdf');
525 $pdf = PDF::API2->new;
527 $pdf->mediabox(0, 0, 595, 842);
528 ...
529 $pdf->saveas('our/new.pdf');
530 $pdf->cropbox($name)
532 $pdf->cropbox($w, $h)
533 $pdf->cropbox($llx, $lly, $urx, $ury)
534 Sets the global cropbox.
535 $pdf->bleedbox($name)
537 $pdf->bleedbox($w, $h)
538 $pdf->bleedbox($llx, $lly, $urx, $ury)
539 Sets the global bleedbox.
540 $pdf->trimbox($name)
542 $pdf->trimbox($w, $h)
543 $pdf->trimbox($llx, $lly, $urx, $ury)
544 Sets the global trimbox.
545 $pdf->artbox($name)
547 $pdf->artbox($w, $h)
548 $pdf->artbox($llx, $lly, $urx, $ury)
549 Sets the global artbox.
550
552 @directories = PDF::API2::addFontDirs($dir1, $dir2, ...)
553 Adds one or more directories to the search path for finding font
554 files.
555 Returns the list of searched directories.
557 $font = $pdf->corefont($fontname, [%options])
559 Returns a new Adobe core font object.
560 Examples:
562 $font = $pdf->corefont('Times-Roman');
564 $font = $pdf->corefont('Times-Bold');
565 $font = $pdf->corefont('Helvetica');
566 $font = $pdf->corefont('ZapfDingbats');
567 Valid %options are:
569 -encode
571 Changes the encoding of the font from its default.
572 -dokern
574 Enables kerning if data is available.
575 See Also: PDF::API2::Resource::Font::CoreFont.
577 $font = $pdf->psfont($ps_file, [%options])
579 Returns a new Adobe Type1 font object.
580 Examples:
582 $font = $pdf->psfont('Times-Book.pfa', -afmfile => 'Times-Book.afm');
584 $font = $pdf->psfont('/fonts/Synest-FB.pfb', -pfmfile => '/fonts/Synest-FB.pfm');
585 Valid %options are:
587 -encode
589 Changes the encoding of the font from its default.
590 -afmfile
592 Specifies the location of the font metrics file.
593 -pfmfile
595 Specifies the location of the printer font metrics file. This
596 option overrides the -encode option.
597 -dokern
599 Enables kerning if data is available.
600 $font = $pdf->ttfont($ttf_file, [%options])
602 Returns a new TrueType or OpenType font object.
603 Examples:
605 $font = $pdf->ttfont('Times.ttf');
607 $font = $pdf->ttfont('Georgia.otf');
608 Valid %options are:
610 -encode
612 Changes the encoding of the font from its default.
613 -isocmap
615 Use the ISO Unicode Map instead of the default MS Unicode Map.
616 -dokern
618 Enables kerning if data is available.
619 -noembed
621 Disables embedding of the font file.
622 $font = $pdf->cjkfont($cjkname, [%options])
624 Returns a new CJK font object.
625 Examples:
627 $font = $pdf->cjkfont('korean');
629 $font = $pdf->cjkfont('traditional');
630 Valid %options are:
632 -encode
634 Changes the encoding of the font from its default.
635 See Also: PDF::API2::Resource::CIDFont::CJKFont
637 $font = $pdf->synfont($basefont, [%options])
639 Returns a new synthetic font object.
640 Examples:
642 $cf = $pdf->corefont('Times-Roman', -encode => 'latin1');
644 $sf = $pdf->synfont($cf, -slant => 0.85); # compressed 85%
645 $sfb = $pdf->synfont($cf, -bold => 1); # embolden by 10em
646 $sfi = $pdf->synfont($cf, -oblique => -12); # italic at -12 degrees
647 Valid %options are:
649 -slant
651 Slant/expansion factor (0.1-0.9 = slant, 1.1+ = expansion).
652 -oblique
654 Italic angle (+/-)
655 -bold
657 Emboldening factor (0.1+, bold = 1, heavy = 2, ...)
658 -space
660 Additional character spacing in ems (0-1000)
661 See Also: PDF::API2::Resource::Font::SynFont
663 $font = $pdf->bdfont($bdf_file)
665 Returns a new BDF font object, based on the specified Adobe BDF
666 file.
667 See Also: PDF::API2::Resource::Font::BdFont
669 $font = $pdf->unifont(@fontspecs, %options)
671 Returns a new uni-font object, based on the specified fonts and
672 options.
673 BEWARE: This is not a true pdf-object, but a virtual/abstract font
675 definition!
676 See Also: PDF::API2::Resource::UniFont.
678 Valid %options are:
680 -encode
682 Changes the encoding of the font from its default.
683
685 $jpeg = $pdf->image_jpeg($file)
686 Imports and returns a new JPEG image object.
687 $tiff = $pdf->image_tiff($file)
689 Imports and returns a new TIFF image object.
690 $pnm = $pdf->image_pnm($file)
692 Imports and returns a new PNM image object.
693 $png = $pdf->image_png($file)
695 Imports and returns a new PNG image object.
696 $gif = $pdf->image_gif($file)
698 Imports and returns a new GIF image object.
699 $gdf = $pdf->image_gd($gd_object, %options)
701 Imports and returns a new image object from GD::Image.
702 Options: The only option currently supported is "-lossless => 1".
704
706 $cs = $pdf->colorspace_act($file)
707 Returns a new colorspace object based on an Adobe Color Table file.
708 See PDF::API2::Resource::ColorSpace::Indexed::ACTFile for a
710 reference to the file format's specification.
711 $cs = $pdf->colorspace_web()
713 Returns a new colorspace-object based on the web color palette.
714 $cs = $pdf->colorspace_hue()
716 Returns a new colorspace-object based on the hue color palette.
717 See PDF::API2::Resource::ColorSpace::Indexed::Hue for an
719 explanation.
720 $cs = $pdf->colorspace_separation($tint, $color)
722 Returns a new separation colorspace object based on the parameters.
723 $tint can be any valid ink identifier, including but not limited
725 to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
726 'Orange'.
727 $color must be a valid color specification limited to: '#rrggbb',
729 '!hhssvv', '%ccmmyykk' or a "named color" (rgb).
730 The colorspace model will automatically be chosen based on the
732 specified color.
733 $cs = $pdf->colorspace_devicen(\@tintCSx, [$samples])
735 Returns a new DeviceN colorspace object based on the parameters.
736 Example:
738 $cy = $pdf->colorspace_separation('Cyan', '%f000');
740 $ma = $pdf->colorspace_separation('Magenta', '%0f00');
741 $ye = $pdf->colorspace_separation('Yellow', '%00f0');
742 $bk = $pdf->colorspace_separation('Black', '%000f');
743 $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
745 $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk,$pms023 ] );
747 The colorspace model will automatically be chosen based on the
749 first colorspace specified.
750
752 $bc = $pdf->xo_codabar(%options)
753 $bc = $pdf->xo_code128(%options)
754 $bc = $pdf->xo_2of5int(%options)
755 $bc = $pdf->xo_3of9(%options)
756 $bc = $pdf->xo_ean13(%options)
757 Creates the specified barcode object as a form XObject.
758
760 $xo = $pdf->xo_form()
761 Returns a new form XObject.
762 $egs = $pdf->egstate()
764 Returns a new extended graphics state object.
765 $obj = $pdf->pattern()
767 Returns a new pattern object.
768 $obj = $pdf->shading()
770 Returns a new shading object.
771 $otls = $pdf->outlines()
773 Returns a new or existing outlines object.
774
776 $pdf->resource($type, $key, $obj, $force)
777 Adds a resource to the global PDF tree.
778 Example:
780 $pdf->resource('Font', $fontkey, $fontobj);
782 $pdf->resource('XObject', $imagekey, $imageobj);
783 $pdf->resource('Shading', $shadekey, $shadeobj);
784 $pdf->resource('ColorSpace', $spacekey, $speceobj);
785 Note: You only have to add the required resources if they are NOT
787 handled by the font, image, shade or space methods.
788
790 This module does not work with perl's -l command-line switch.
791
793 PDF::API2 was originally written by Alfred Reibenschuh.
794 It is currently being maintained by Steve Simms.
796perl v5.12.2 2011-01-31 PDF::API2(3)