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 = $page->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->open_scalar($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->open_scalar($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 -simplex
153 Print single-sided by default.
154 -duplexflipshortedge
156 Print duplex by default and flip on the short edge of the
157 sheet.
158 -duplexfliplongedge
160 Print duplex by default and flip on the long edge of the sheet.
161 Initial Page Options:
163 -firstpage => [ $page, %options ]
165 Specifying the page (either a page number or a page object) to
166 be displayed, plus one of the following options:
167 -fit => 1
169 Display the page designated by page, with its contents
170 magnified just enough to fit the entire page within the
171 window both horizontally and vertically. If the required
172 horizontal and vertical magnification factors are
173 different, use the smaller of the two, centering the page
174 within the window in the other dimension.
175 -fith => $top
177 Display the page designated by page, with the vertical
178 coordinate top positioned at the top edge of the window and
179 the contents of the page magnified just enough to fit the
180 entire width of the page within the window.
181 -fitv => $left
183 Display the page designated by page, with the horizontal
184 coordinate left positioned at the left edge of the window
185 and the contents of the page magnified just enough to fit
186 the entire height of the page within the window.
187 -fitr => [ $left, $bottom, $right, $top ]
189 Display the page designated by page, with its contents
190 magnified just enough to fit the rectangle specified by the
191 coordinates left, bottom, right, and top entirely within
192 the window both horizontally and vertically. If the
193 required horizontal and vertical magnification factors are
194 different, use the smaller of the two, centering the
195 rectangle within the window in the other dimension.
196 -fitb => 1
198 Display the page designated by page, with its contents
199 magnified just enough to fit its bounding box entirely
200 within the window both horizontally and vertically. If the
201 required horizontal and vertical magnification factors are
202 different, use the smaller of the two, centering the
203 bounding box within the window in the other dimension.
204 -fitbh => $top
206 Display the page designated by page, with the vertical
207 coordinate top positioned at the top edge of the window and
208 the contents of the page magnified just enough to fit the
209 entire width of its bounding box within the window.
210 -fitbv => $left
212 Display the page designated by page, with the horizontal
213 coordinate left positioned at the left edge of the window
214 and the contents of the page magnified just enough to fit
215 the entire height of its bounding box within the window.
216 -xyz => [ $left, $top, $zoom ]
218 Display the page designated by page, with the coordinates
219 (left, top) positioned at the top-left corner of the window
220 and the contents of the page magnified by the factor zoom.
221 A zero (0) value for any of the parameters left, top, or
222 zoom specifies that the current value of that parameter is
223 to be retained unchanged.
224 Example:
226 $pdf->preferences(
228 -fullscreen => 1,
229 -onecolumn => 1,
230 -afterfullscreenoutlines => 1,
231 -firstpage => [$page, -fit => 1],
232 );
233 $val = $pdf->default($parameter)
235 $pdf->default($parameter, $value)
236 Gets/sets the default value for a behaviour of PDF::API2.
237 Supported Parameters:
239 nounrotate
241 prohibits API2 from rotating imported/opened page to re-create
242 a default pdf-context.
243 pageencaps
245 enables than API2 will add save/restore commands upon
246 imported/opened pages to preserve graphics-state for
247 modification.
248 copyannots
250 enables importing of annotations (*EXPERIMENTAL*).
251 $version = $pdf->version([$new_version])
253 Get/set the PDF version (e.g. 1.4)
254 $bool = $pdf->isEncrypted()
256 Checks if the previously opened PDF is encrypted.
257 %infohash = $pdf->info(%infohash)
259 Gets/sets the info structure of the document.
260 Example:
262 %h = $pdf->info(
264 'Author' => "Alfred Reibenschuh",
265 'CreationDate' => "D:20020911000000+01'00'",
266 'ModDate' => "D:YYYYMMDDhhmmssOHH'mm'",
267 'Creator' => "fredos-script.pl",
268 'Producer' => "PDF::API2",
269 'Title' => "some Publication",
270 'Subject' => "perl ?",
271 'Keywords' => "all good things are pdf"
272 );
273 print "Author: $h{Author}\n";
274 @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
276 Gets/sets the supported info-structure tags.
277 Example:
279 @attributes = $pdf->infoMetaAttributes;
281 print "Supported Attributes: @attr\n";
282 @attributes = $pdf->infoMetaAttributes('CustomField1');
284 print "Supported Attributes: @attributes\n";
285 $xml = $pdf->xmpMetadata($xml)
287 Gets/sets the XMP XML data stream.
288 Example:
290 $xml = $pdf->xmpMetadata();
292 print "PDFs Metadata reads: $xml\n";
293 $xml=<<EOT;
294 <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
295 <?adobe-xap-filters esc="CRLF"?>
296 <x:xmpmeta
297 xmlns:x='adobe:ns:meta/'
298 x:xmptk='XMP toolkit 2.9.1-14, framework 1.6'>
299 <rdf:RDF
300 xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
301 xmlns:iX='http://ns.adobe.com/iX/1.0/'>
302 <rdf:Description
303 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
304 xmlns:pdf='http://ns.adobe.com/pdf/1.3/'
305 pdf:Producer='Acrobat Distiller 6.0.1 for Macintosh'></rdf:Description>
306 <rdf:Description
307 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
308 xmlns:xap='http://ns.adobe.com/xap/1.0/'
309 xap:CreateDate='2004-11-14T08:41:16Z'
310 xap:ModifyDate='2004-11-14T16:38:50-08:00'
311 xap:CreatorTool='FrameMaker 7.0'
312 xap:MetadataDate='2004-11-14T16:38:50-08:00'></rdf:Description>
313 <rdf:Description
314 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
315 xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/'
316 xapMM:DocumentID='uuid:919b9378-369c-11d9-a2b5-000393c97fd8'/></rdf:Description>
317 <rdf:Description
318 rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8'
319 xmlns:dc='http://purl.org/dc/elements/1.1/'
320 dc:format='application/pdf'>
321 <dc:description>
322 <rdf:Alt>
323 <rdf:li xml:lang='x-default'>Adobe Portable Document Format (PDF)</rdf:li>
324 </rdf:Alt>
325 </dc:description>
326 <dc:creator>
327 <rdf:Seq>
328 <rdf:li>Adobe Systems Incorporated</rdf:li>
329 </rdf:Seq>
330 </dc:creator>
331 <dc:title>
332 <rdf:Alt>
333 <rdf:li xml:lang='x-default'>PDF Reference, version 1.6</rdf:li>
334 </rdf:Alt>
335 </dc:title>
336 </rdf:Description>
337 </rdf:RDF>
338 </x:xmpmeta>
339 <?xpacket end='w'?>
340 EOT
341 $xml = $pdf->xmpMetadata($xml);
343 print "PDF metadata now reads: $xml\n";
344 $pdf->pageLabel($index, $options)
346 Sets page label options.
347 Supported Options:
349 -style
351 Roman, roman, decimal, Alpha or alpha.
352 -start
354 Restart numbering at given number.
355 -prefix
357 Text prefix for numbering.
358 Example:
360 # Start with Roman Numerals
362 $pdf->pageLabel(0, {
363 -style => 'roman',
364 });
365 # Switch to Arabic
367 $pdf->pageLabel(4, {
368 -style => 'decimal',
369 });
370 # Numbering for Appendix A
372 $pdf->pageLabel(32, {
373 -start => 1,
374 -prefix => 'A-'
375 });
376 # Numbering for Appendix B
378 $pdf->pageLabel( 36, {
379 -start => 1,
380 -prefix => 'B-'
381 });
382 # Numbering for the Index
384 $pdf->pageLabel(40, {
385 -style => 'Roman'
386 -start => 1,
387 -prefix => 'Index '
388 });
389 $pdf->finishobjects(@objects)
391 Force objects to be written to file if possible.
392 Example:
394 $pdf = PDF::API2->new(-file => 'our/new.pdf');
396 ...
397 $pdf->finishobjects($page, $gfx, $txt);
398 ...
399 $pdf->save();
400 $pdf->update()
402 Saves a previously opened document.
403 Example:
405 $pdf = PDF::API2->open('our/to/be/updated.pdf');
407 ...
408 $pdf->update();
409 $pdf->saveas($file)
411 Save the document to $file and remove the object structure from
412 memory.
413 Example:
415 $pdf = PDF::API2->new();
417 ...
418 $pdf->saveas('our/new.pdf');
419 $string = $pdf->stringify()
421 Return the document as a string and remove the object structure
422 from memory.
423 Example:
425 $pdf = PDF::API2->new();
427 ...
428 print $pdf->stringify();
429 $pdf->end()
431 Remove the object structure from memory. PDF::API2 contains
432 circular references, so this call is necessary in long-running
433 processes to keep from running out of memory.
434 This will be called automatically when you save or stringify a PDF.
436 You should only need to call it explicitly if you are reading PDF
437 files and not writing them.
438
440 $page = $pdf->page()
441 $page = $pdf->page($page_number)
442 Returns a new page object. By default, the page is added to the
443 end of the document. If you include an existing page number, the
444 new page will be inserted in that position, pushing existing pages
445 back.
446 If $page_number is -1, the new page is inserted as the second-last
448 page; if $page_number is 0, the new page is inserted as the last
449 page.
450 Example:
452 $pdf = PDF::API2->new();
454 # Add a page. This becomes page 1.
456 $page = $pdf->page();
457 # Add a new first page. $page becomes page 2.
459 $another_page = $pdf->page(1);
460 $page = $pdf->openpage($page_number)
462 Returns the PDF::API2::Page object of page $page_number.
463 If $page_number is 0 or -1, it will return the last page in the
465 document.
466 Example:
468 $pdf = PDF::API2->open('our/99page.pdf');
470 $page = $pdf->openpage(1); # returns the first page
471 $page = $pdf->openpage(99); # returns the last page
472 $page = $pdf->openpage(-1); # returns the last page
473 $page = $pdf->openpage(999); # returns undef
474 $xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)
476 Returns a Form XObject created by extracting the specified page
477 from $source_pdf.
478 This is useful if you want to transpose the imported page somewhat
480 differently onto a page (e.g. two-up, four-up, etc.).
481 If $source_page_number is 0 or -1, it will return the last page in
483 the document.
484 Example:
486 $pdf = PDF::API2->new();
488 $old = PDF::API2->open('our/old.pdf');
489 $page = $pdf->page();
490 $gfx = $page->gfx();
491 # Import Page 2 from the old PDF
493 $xo = $pdf->importPageIntoForm($old, 2);
494 # Add it to the new PDF's first page at 1/2 scale
496 $gfx->formimage($xo, 0, 0, 0.5);
497 $pdf->saveas('our/new.pdf');
499 Note: You can only import a page from an existing PDF file.
501 $page = $pdf->import_page($source_pdf, $source_page_number,
503 $target_page_number)
504 Imports a page from $source_pdf and adds it to the specified
505 position in $pdf.
506 If $source_page_number or $target_page_number is 0 or -1, the last
508 page in the document is used.
509 Note: If you pass a page object instead of a page number for
511 $target_page_number, the contents of the page will be merged into
512 the existing page.
513 Example:
515 $pdf = PDF::API2->new();
517 $old = PDF::API2->open('our/old.pdf');
518 # Add page 2 from the old PDF as page 1 of the new PDF
520 $page = $pdf->import_page($old, 2);
521 $pdf->saveas('our/new.pdf');
523 Note: You can only import a page from an existing PDF file.
525 $count = $pdf->pages()
527 Returns the number of pages in the document.
528 $pdf->mediabox($name)
530 $pdf->mediabox($w, $h)
531 $pdf->mediabox($llx, $lly, $urx, $ury)
532 Sets the global mediabox.
533 Example:
535 $pdf = PDF::API2->new();
537 $pdf->mediabox('A4');
538 ...
539 $pdf->saveas('our/new.pdf');
540 $pdf = PDF::API2->new();
542 $pdf->mediabox(595, 842);
543 ...
544 $pdf->saveas('our/new.pdf');
545 $pdf = PDF::API2->new;
547 $pdf->mediabox(0, 0, 595, 842);
548 ...
549 $pdf->saveas('our/new.pdf');
550 $pdf->cropbox($name)
552 $pdf->cropbox($w, $h)
553 $pdf->cropbox($llx, $lly, $urx, $ury)
554 Sets the global cropbox.
555 $pdf->bleedbox($name)
557 $pdf->bleedbox($w, $h)
558 $pdf->bleedbox($llx, $lly, $urx, $ury)
559 Sets the global bleedbox.
560 $pdf->trimbox($name)
562 $pdf->trimbox($w, $h)
563 $pdf->trimbox($llx, $lly, $urx, $ury)
564 Sets the global trimbox.
565 $pdf->artbox($name)
567 $pdf->artbox($w, $h)
568 $pdf->artbox($llx, $lly, $urx, $ury)
569 Sets the global artbox.
570
572 @directories = PDF::API2::addFontDirs($dir1, $dir2, ...)
573 Adds one or more directories to the search path for finding font
574 files.
575 Returns the list of searched directories.
577 $font = $pdf->corefont($fontname, [%options])
579 Returns a new Adobe core font object.
580 Examples:
582 $font = $pdf->corefont('Times-Roman');
584 $font = $pdf->corefont('Times-Bold');
585 $font = $pdf->corefont('Helvetica');
586 $font = $pdf->corefont('ZapfDingbats');
587 Valid %options are:
589 -encode
591 Changes the encoding of the font from its default.
592 -dokern
594 Enables kerning if data is available.
595 See Also: PDF::API2::Resource::Font::CoreFont.
597 $font = $pdf->psfont($ps_file, [%options])
599 Returns a new Adobe Type1 font object.
600 Examples:
602 $font = $pdf->psfont('Times-Book.pfa', -afmfile => 'Times-Book.afm');
604 $font = $pdf->psfont('/fonts/Synest-FB.pfb', -pfmfile => '/fonts/Synest-FB.pfm');
605 Valid %options are:
607 -encode
609 Changes the encoding of the font from its default.
610 -afmfile
612 Specifies the location of the font metrics file.
613 -pfmfile
615 Specifies the location of the printer font metrics file. This
616 option overrides the -encode option.
617 -dokern
619 Enables kerning if data is available.
620 $font = $pdf->ttfont($ttf_file, [%options])
622 Returns a new TrueType or OpenType font object.
623 Examples:
625 $font = $pdf->ttfont('Times.ttf');
627 $font = $pdf->ttfont('Georgia.otf');
628 Valid %options are:
630 -encode
632 Changes the encoding of the font from its default.
633 -isocmap
635 Use the ISO Unicode Map instead of the default MS Unicode Map.
636 -dokern
638 Enables kerning if data is available.
639 -noembed
641 Disables embedding of the font file.
642 $font = $pdf->cjkfont($cjkname, [%options])
644 Returns a new CJK font object.
645 Examples:
647 $font = $pdf->cjkfont('korean');
649 $font = $pdf->cjkfont('traditional');
650 Valid %options are:
652 -encode
654 Changes the encoding of the font from its default.
655 See Also: PDF::API2::Resource::CIDFont::CJKFont
657 $font = $pdf->synfont($basefont, [%options])
659 Returns a new synthetic font object.
660 Examples:
662 $cf = $pdf->corefont('Times-Roman', -encode => 'latin1');
664 $sf = $pdf->synfont($cf, -slant => 0.85); # compressed 85%
665 $sfb = $pdf->synfont($cf, -bold => 1); # embolden by 10em
666 $sfi = $pdf->synfont($cf, -oblique => -12); # italic at -12 degrees
667 Valid %options are:
669 -slant
671 Slant/expansion factor (0.1-0.9 = slant, 1.1+ = expansion).
672 -oblique
674 Italic angle (+/-)
675 -bold
677 Emboldening factor (0.1+, bold = 1, heavy = 2, ...)
678 -space
680 Additional character spacing in ems (0-1000)
681 See Also: PDF::API2::Resource::Font::SynFont
683 $font = $pdf->bdfont($bdf_file)
685 Returns a new BDF font object, based on the specified Adobe BDF
686 file.
687 See Also: PDF::API2::Resource::Font::BdFont
689 $font = $pdf->unifont(@fontspecs, %options)
691 Returns a new uni-font object, based on the specified fonts and
692 options.
693 BEWARE: This is not a true pdf-object, but a virtual/abstract font
695 definition!
696 See Also: PDF::API2::Resource::UniFont.
698 Valid %options are:
700 -encode
702 Changes the encoding of the font from its default.
703
705 $jpeg = $pdf->image_jpeg($file)
706 Imports and returns a new JPEG image object. $file may be either a
707 filename or a filehandle.
708 $tiff = $pdf->image_tiff($file)
710 Imports and returns a new TIFF image object. $file may be either a
711 filename or a filehandle.
712 $pnm = $pdf->image_pnm($file)
714 Imports and returns a new PNM image object. $file may be either a
715 filename or a filehandle.
716 $png = $pdf->image_png($file)
718 Imports and returns a new PNG image object. $file may be either a
719 filename or a filehandle.
720 $gif = $pdf->image_gif($file)
722 Imports and returns a new GIF image object. $file may be either a
723 filename or a filehandle.
724 $gdf = $pdf->image_gd($gd_object, %options)
726 Imports and returns a new image object from GD::Image.
727 Options: The only option currently supported is "-lossless => 1".
729
731 $cs = $pdf->colorspace_act($file)
732 Returns a new colorspace object based on an Adobe Color Table file.
733 See PDF::API2::Resource::ColorSpace::Indexed::ACTFile for a
735 reference to the file format's specification.
736 $cs = $pdf->colorspace_web()
738 Returns a new colorspace-object based on the web color palette.
739 $cs = $pdf->colorspace_hue()
741 Returns a new colorspace-object based on the hue color palette.
742 See PDF::API2::Resource::ColorSpace::Indexed::Hue for an
744 explanation.
745 $cs = $pdf->colorspace_separation($tint, $color)
747 Returns a new separation colorspace object based on the parameters.
748 $tint can be any valid ink identifier, including but not limited
750 to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
751 'Orange'.
752 $color must be a valid color specification limited to: '#rrggbb',
754 '!hhssvv', '%ccmmyykk' or a "named color" (rgb).
755 The colorspace model will automatically be chosen based on the
757 specified color.
758 $cs = $pdf->colorspace_devicen(\@tintCSx, [$samples])
760 Returns a new DeviceN colorspace object based on the parameters.
761 Example:
763 $cy = $pdf->colorspace_separation('Cyan', '%f000');
765 $ma = $pdf->colorspace_separation('Magenta', '%0f00');
766 $ye = $pdf->colorspace_separation('Yellow', '%00f0');
767 $bk = $pdf->colorspace_separation('Black', '%000f');
768 $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
770 $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk,$pms023 ] );
772 The colorspace model will automatically be chosen based on the
774 first colorspace specified.
775
777 $bc = $pdf->xo_codabar(%options)
778 $bc = $pdf->xo_code128(%options)
779 $bc = $pdf->xo_2of5int(%options)
780 $bc = $pdf->xo_3of9(%options)
781 $bc = $pdf->xo_ean13(%options)
782 Creates the specified barcode object as a form XObject.
783
785 $xo = $pdf->xo_form()
786 Returns a new form XObject.
787 $egs = $pdf->egstate()
789 Returns a new extended graphics state object.
790 $obj = $pdf->pattern()
792 Returns a new pattern object.
793 $obj = $pdf->shading()
795 Returns a new shading object.
796 $otls = $pdf->outlines()
798 Returns a new or existing outlines object.
799
801 This module does not work with perl's -l command-line switch.
802
804 PDF::API2 was originally written by Alfred Reibenschuh.
805 It is currently being maintained by Steve Simms.
807perl v5.28.0 2018-07-15 PDF::API2(3)