1PDF::API2(3) User Contributed Perl Documentation PDF::API2(3)
2
6 PDF::API2 - Create, modify, and examine 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->open_page($page_number);
22 # Set the page size
24 $page->size('Letter');
25 # Add a built-in font to the PDF
27 $font = $pdf->font('Helvetica-Bold');
28 # Add an external TrueType font to the PDF
30 $font = $pdf->font('/path/to/font.ttf');
31 # Add some text to the page
33 $text = $page->text();
34 $text->font($font, 20);
35 $text->position(200, 700);
36 $text->text('Hello World!');
37 # Save the PDF
39 $pdf->save('/path/to/new.pdf');
40
42 new
43 my $pdf = PDF::API2->new(%options);
44 Create a new PDF.
46 The following options are available:
48 • file
50 If you will be saving the PDF to disk and already know the
52 filename, you can include it here to open the file for writing
53 immediately. "file" may also be a filehandle.
54 • compress
56 By default, most of the PDF will be compressed to save space. To
58 turn this off (generally only useful for testing or debugging), set
59 "compress" to 0.
60 open
62 my $pdf = PDF::API2->open('/path/to/file.pdf', %options);
63 Open an existing PDF file.
65 The following option is available:
67 • compress
69 By default, most of the PDF will be compressed to save space. To
71 turn this off (generally only useful for testing or debugging), set
72 "compress" to 0.
73 save
75 $pdf->save('/path/to/file.pdf');
76 Write the PDF to disk and close the file. A filename is optional if
78 one was specified while opening or creating the PDF.
79 As a side effect, the document structure is removed from memory when
81 the file is saved, so it will no longer be usable.
82 close
84 $pdf->close();
85 Close an open file (if relevant) and remove the object structure from
87 memory.
88 PDF::API2 contains circular references, so this call is necessary in
90 long-running processes to keep from running out of memory.
91 This will be called automatically when you save or stringify a PDF.
93 You should only need to call it explicitly if you are reading PDF files
94 and not writing them.
95 from_string
97 my $pdf = PDF::API2->from_string($pdf_string, %options);
98 Read a PDF document contained in a string.
100 The following option is available:
102 • compress
104 By default, most of the PDF will be compressed to save space. To
106 turn this off (generally only useful for testing or debugging), set
107 "compress" to 0.
108 to_string
110 my $string = $pdf->to_string();
111 Return the PDF document as a string.
113 As a side effect, the document structure is removed from memory when
115 the string is created, so it will no longer be usable.
116
118 title
119 $title = $pdf->title();
120 $pdf = $pdf->title($title);
121 Get/set/clear the document's title.
123 author
125 $author = $pdf->author();
126 $pdf = $pdf->author($author);
127 Get/set/clear the name of the person who created the document.
129 subject
131 $subject = $pdf->subject();
132 $pdf = $pdf->subject($subject);
133 Get/set/clear the subject of the document.
135 keywords
137 $keywords = $pdf->keywords();
138 $pdf = $pdf->keywords($keywords);
139 Get/set/clear a space-separated string of keywords associated with the
141 document.
142 creator
144 $creator = $pdf->creator();
145 $pdf = $pdf->creator($creator);
146 Get/set/clear the name of the product that created the document prior
148 to its conversion to PDF.
149 producer
151 $producer = $pdf->producer();
152 $pdf = $pdf->producer($producer);
153 Get/set/clear the name of the product that converted the original
155 document to PDF.
156 PDF::API2 fills in this field when creating a PDF.
158 created
160 $date = $pdf->created();
161 $pdf = $pdf->created($date);
162 Get/set/clear the document's creation date.
164 The date format is "D:YYYYMMDDHHmmSSOHH'mm", where "D:" is a static
166 prefix identifying the string as a PDF date. The date may be truncated
167 at any point after the year. "O" is one of "+", "-", or "Z", with the
168 following "HH'mm" representing an offset from UTC.
169 When setting the date, "D:" will be prepended automatically if omitted.
171 modified
173 $date = $pdf->modified();
174 $pdf = $pdf->modified($date);
175 Get/set/clear the document's modification date. The date format is as
177 described in "created" above.
178 info_metadata
180 # Get all keys and values
181 %info = $pdf->info_metadata();
182 # Get the value of one key
184 $value = $pdf->info_metadata($key);
185 # Set the value of one key
187 $pdf = $pdf->info_metadata($key, $value);
188 Get/set/clear a key in the document's information dictionary. The
190 standard keys (title, author, etc.) have their own accessors, so this
191 is primarily intended for interacting with custom metadata.
192 Pass "undef" as the value in order to remove the key from the
194 dictionary.
195 xml_metadata
197 $xml = $pdf->xml_metadata();
198 $pdf = $pdf->xml_metadata($xml);
199 Get/set the document's XML metadata stream.
201 version
203 $version = $pdf->version($new_version);
204 Get/set the PDF version (e.g. 1.4).
206 is_encrypted
208 $boolean = $pdf->is_encrypted();
209 Returns true if the opened PDF is encrypted.
211
213 outline
214 $outline = $pdf->outlines();
215 Creates (if needed) and returns the document's outline tree, which is
217 also known as its bookmarks or the table of contents, depending on the
218 PDF reader.
219 To examine or modify the outline tree, see PDF::API2::Outline.
221 open_action
223 $pdf = $pdf->open_action($page, $location, @args);
224 Set the destination in the PDF that should be displayed when the
226 document is opened.
227 $page may be either a page number or a page object. The other
229 parameters are as described in PDF::API2::NamedDestination.
230 page_layout
232 $layout = $pdf->page_layout();
233 $pdf = $pdf->page_layout($layout);
234 Get/set the page layout that should be used when the PDF is opened.
236 $layout is one of the following:
238 • single_page (or undef)
240 Display one page at a time.
242 • one_column
244 Display the pages in one column (a.k.a. continuous).
246 • two_column_left
248 Display the pages in two columns, with odd-numbered pages on the
250 left.
251 • two_column_right
253 Display the pages in two columns, with odd-numbered pages on the
255 right.
256 • two_page_left
258 Display two pages at a time, with odd-numbered pages on the left.
260 • two_page_right
262 Display two pages at a time, with odd-numbered pages on the right.
264 page_mode
266 # Get
267 $mode = $pdf->page_mode();
268 # Set
270 $pdf = $pdf->page_mode($mode);
271 Get/set the page mode, which describes how the PDF should be displayed
273 when opened.
274 $mode is one of the following:
276 • none (or undef)
278 Neither outlines nor thumbnails should be displayed.
280 • outlines
282 Show the document outline.
284 • thumbnails
286 Show the page thumbnails.
288 • full_screen
290 Open in full-screen mode, with no menu bar, window controls, or any
292 other window visible.
293 • optional_content
295 Show the optional content group panel.
297 • attachments
299 Show the attachments panel.
301 viewer_preferences
303 # Get
304 %preferences = $pdf->viewer_preferences();
305 # Set
307 $pdf = $pdf->viewer_preferences(%preferences);
308 Get or set PDF viewer preferences, as described in
310 PDF::API2::ViewerPreferences.
311
313 page
314 # Add a page to the end of the document
315 $page = $pdf->page();
316 # Insert a page before the specified page number
318 $page = $pdf->page($page_number);
319 Returns a new page object. By default, the page is added to the end of
321 the document. If you include an existing page number, the new page
322 will be inserted in that position, pushing existing pages back.
323 If $page_number is -1, the new page is inserted as the second-last
325 page; if $page_number is 0, the new page is inserted as the last page.
326 open_page
328 $page = $pdf->open_page($page_number);
329 Returns the PDF::API2::Page object of page $page_number, if it exists.
331 If $page_number is 0 or -1, it will return the last page in the
333 document.
334 import_page
336 $page = $pdf->import_page($source_pdf, $source_page_num, $target_page_num);
337 Imports a page from $source_pdf and adds it to the specified position
339 in $pdf.
340 If $source_page_num or $target_page_num is 0, -1, or unspecified, the
342 last page in the document is used.
343 Note: If you pass a page object instead of a page number for
345 $target_page_num, the contents of the page will be merged into the
346 existing page.
347 Example:
349 my $pdf = PDF::API2->new();
351 my $source = PDF::API2->open('source.pdf');
352 # Add page 2 from the source PDF as page 1 of the new PDF
354 my $page = $pdf->import_page($source, 2);
355 $pdf->save('sample.pdf');
357 Note: You can only import a page from an existing PDF file.
359 embed_page
361 $xobject = $pdf->embed_page($source_pdf, $source_page_number);
362 Returns a Form XObject created by extracting the specified page from a
364 $source_pdf.
365 This is useful if you want to transpose the imported page somewhat
367 differently onto a page (e.g. two-up, four-up, etc.).
368 If $source_page_number is 0 or -1, it will return the last page in the
370 document.
371 Example:
373 my $pdf = PDF::API2->new();
375 my $source = PDF::API2->open('source.pdf');
376 my $page = $pdf->page();
377 # Import Page 2 from the source PDF
379 my $object = $pdf->embed_page($source, 2);
380 # Add it to the new PDF's first page at 1/2 scale
382 my ($x, $y) = (0, 0);
383 $page->object($object, $x, $y, 0.5);
384 $pdf->save('sample.pdf');
386 Note: You can only import a page from an existing PDF file.
388 page_count
390 $integer = $pdf->page_count();
391 Return the number of pages in the document.
393 page_labels
395 $pdf = $pdf->page_labels($page_number, %options);
396 Describes how pages should be numbered beginning at the specified page
398 number.
399 # Generate a 30-page PDF
401 my $pdf = PDF::API2->new();
402 $pdf->page() for 1..30;
403 # Number pages i to v, 1 to 20, and A-1 to A-5, respectively
405 $pdf->page_labels(1, style => 'roman');
406 $pdf->page_labels(6, style => 'decimal');
407 $pdf->page_labels(26, style => 'decimal', prefix => 'A-');
408 $pdf->save('sample.pdf');
410 The following options are available:
412 • style
414 One of "decimal" (standard decimal arabic numerals), "Roman"
416 (uppercase roman numerals), "roman" (lowercase roman numerals),
417 "Alpha" (uppercase letters), or "alpha" (lowercase letters).
418 There is no default numbering style. If omitted, the page label
420 will be just the prefix (if set) or an empty string.
421 • prefix
423 The label prefix for pages in this range.
425 • start
427 An integer (default: 1) representing the first value to be used in
429 this page range.
430 default_page_size
432 # Set
433 $pdf->default_page_size($size);
434 # Get
436 @rectangle = $pdf->default_page_size()
437 Set the default physical size for pages in the PDF. If called without
439 arguments, return the coordinates of the rectangle describing the
440 default physical page size.
441 See "Page Sizes" in PDF::API2::Page for possible values.
443 default_page_boundaries
445 # Set
446 $pdf->default_page_boundaries(%boundaries);
447 # Get
449 %boundaries = $pdf->default_page_boundaries();
450 Set default prepress page boundaries for pages in the PDF. If called
452 without arguments, returns the coordinates of the rectangles describing
453 each of the supported page boundaries.
454 See the equivalent "page_boundaries" method in PDF::API2::Page for
456 details.
457
459 font
460 my $font = $pdf->font($name, %options)
461 Add a font to the PDF. Returns the font object, to be used by
463 PDF::API2::Content.
464 The font $name is either the name of one of the standard 14 fonts (e.g.
466 Helvetica) or the path to a font file.
467 my $pdf = PDF::API2->new();
469 my $font1 = $pdf->font('Helvetica-Bold');
470 my $font2 = $pdf->font('/path/to/ComicSans.ttf');
471 my $page = $pdf->page();
472 my $content = $page->text();
473 $content->position(1 * 72, 9 * 72);
475 $content->font($font1, 24);
476 $content->text('Hello, World!');
477 $content->position(0, -36);
479 $content->font($font2, 12);
480 $content->text('This is some sample text.');
481 $pdf->save('sample.pdf');
483 The path can be omitted if the font file is in the current directory or
485 one of the directories returned by "font_path".
486 TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph
488 Bitmap Distribution Format (bdf) fonts are supported.
489 The following %options are available:
491 • format
493 The font format is normally detected automatically based on the
495 file's extension. If you're using a font with an atypical
496 extension, you can set "format" to one of "truetype" (TrueType or
497 OpenType), "type1" (PostScript Type 1), or "bitmap" (Adobe Bitmap).
498 • kerning
500 Kerning (automatic adjustment of space between pairs of characters)
502 is enabled by default if the font includes this information. Set
503 this option to false to disable.
504 • afm_file (PostScript Type 1 fonts only)
506 Specifies the location of the font metrics file.
508 • pfm_file (PostScript Type 1 fonts only)
510 Specifies the location of the printer font metrics file. This
512 option overrides the -encode option.
513 • embed (TrueType fonts only)
515 Fonts are embedded in the PDF by default, which is required to
517 ensure that they can be viewed properly on a device that doesn't
518 have the font installed. Set this option to false to prevent the
519 font from being embedded.
520 synthetic_font
522 $font = $pdf->synthetic_font($base_font, %options)
523 Create and return a new synthetic font object. See
525 PDF::API2::Resource::Font::SynFont for details.
526 font_path
528 @directories = PDF::API2->font_path()
529 Return the list of directories that will be searched (in order) in
531 addition to the current directory when you add a font to a PDF without
532 including the full path to the font file.
533 add_to_font_path
535 @directories = PDF::API2->add_to_font_path('/my/fonts', '/path/to/fonts');
536 Add one or more directories to the list of paths to be searched for
538 font files.
539 Returns the font search path.
541 set_font_path
543 @directories = PDF::API2->set_font_path('/my/fonts', '/path/to/fonts');
544 Replace the existing font search path. This should only be necessary
546 if you need to remove a directory from the path for some reason, or if
547 you need to reorder the list.
548 Returns the font search path.
550
552 image
553 $object = $pdf->image($file, %options);
554 Import a supported image type and return an object that can be placed
556 as part of a page's content:
557 my $pdf = PDF::API2->new();
559 my $page = $pdf->page();
560 my $image = $pdf->image('/path/to/image.jpg');
562 $page->object($image, 100, 100);
563 $pdf->save('sample.pdf');
565 $file may be either a file name, a filehandle, or a GD::Image object.
567 See "place" in PDF::API2::Content for details about placing images on a
569 page once they're imported.
570 The image format is normally detected automatically based on the file's
572 extension. If passed a filehandle, image formats GIF, JPEG, and PNG
573 will be detected based on the file's header.
574 If the file has an atypical extension or the filehandle is for a
576 different kind of image, you can set the "format" option to one of the
577 supported types: "gif", "jpeg", "png", "pnm", or "tiff".
578 Note: PNG images that include an alpha (transparency) channel go
580 through a relatively slow process of splitting the image into separate
581 RGB and alpha components as is required by images in PDFs. If you're
582 having performance issues, install PDF::API2::XS or Image::PNG::Libpng
583 to speed this process up by an order of magnitude; either module will
584 be used automatically if available.
585 barcode
587 $object = $pdf->barcode($format, $code, %options);
588 Generate and return a barcode that can be placed as part of a page's
590 content:
591 my $pdf = PDF::API2->new();
593 my $page = $pdf->page();
594 my $barcode = $pdf->barcode('ean13', '0123456789012');
596 $page->object($barcode, 100, 100);
597 my $qr_code = $pdf->barcode('qr', 'http://www.example.com');
599 $page->object($qr_code, 100, 300, 144 / $qr_code->width())
600 $pdf->save('sample.pdf');
602 $format can be one of "codabar", "code128", "code39" (a.k.a. 3 of 9),
604 "ean128", "ean13", "itf" (a.k.a. interleaved 2 of 5), or "qr".
605 $code is the value to be encoded. Start and stop characters are only
607 required when they're not static (e.g. for Codabar).
608 The following options are available:
610 • bar_width
612 The width of the smallest bar or space in points (72 points = 1
614 inch).
615 If you're following a specification that gives bar width in mils
617 (thousandths of an inch), use this conversion: "$points = $mils /
618 1000 * 72".
619 • bar_height
621 The base height of the barcode in points.
623 • bar_extend
625 If present, bars for non-printing characters (e.g. start and stop
627 characters) will be extended downward by this many points, and
628 printing characters will be shown below their respective bars.
629 This is enabled by default for EAN-13 barcodes.
631 • caption
633 If present, this value will be printed, centered, beneath the
635 barcode, and should be a human-readable representation of the
636 barcode.
637 • font
639 A font object (created by "font") that will be used to print the
641 caption, or the printable characters when "bar_extend" is set.
642 Helvetica will be used by default.
644 • font_size
646 The size of the font used for printing the caption or printable
648 characters.
649 The default will be calculated based on the barcode size, if
651 "bar_extend" is set, or 10 otherwise.
652 • quiet_zone
654 A margin, in points, that will be place before the left and bottom
656 edges of the barcode (including the caption, if present). This is
657 used to help barcode scanners tell where the barcode begins and
658 ends.
659 The default is the width of one encoded character.
661 • bar_overflow
663 Shrinks the horizontal width of bars by this amount in points to
665 account for ink spread when printing.
666 The default is 0.01 points.
668 • color
670 Draw bars using this color, which may be any value accepted by
672 "fillcolor" in PDF::API2::Content.
673 The default is black.
675 colorspace
677 $colorspace = $pdf->colorspace($type, @arguments);
678 Colorspaces can be added to a PDF to either specifically control the
680 output color on a particular device (spot colors, device colors) or to
681 save space by limiting the available colors to a defined color palette
682 (web-safe palette, ACT file).
683 Once added to the PDF, they can be used in place of regular hex codes
685 or named colors:
686 my $pdf = PDF::API2->new();
688 my $page = $pdf->page();
689 my $content = $page->graphics();
690 # Add colorspaces for a spot color and the web-safe color palette
692 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
693 my $web = $pdf->colorspace('web');
694 # Fill using the spot color with 100% coverage
696 $content->fill_color($spot, 1.0);
697 # Stroke using the first color of the web-safe palette
699 $content->stroke_color($web, 0);
700 # Add a rectangle to the page
702 $content->rectangle(100, 100, 200, 200);
703 $content->paint();
704 $pdf->save('sample.pdf');
706 The following types of colorspaces are supported
708 • spot
710 my $spot = $pdf->colorspace('spot', $tint, $alt_color);
712 Spot colors are used to instruct a device (usually a printer) to
714 use or emulate a particular ink color ($tint) for parts of the
715 document. An $alt_color is provided for devices (e.g. PDF viewers)
716 that don't know how to produce the named color. It can either be
717 an approximation of the color in RGB, CMYK, or HSV formats, or a
718 wildly different color (e.g. 100% magenta, %0F00) to make it clear
719 if the spot color isn't being used as expected.
720 • web
722 my $web = $pdf->colorspace('web');
724 The web-safe color palette is a historical collection of colors
726 that was used when many display devices only supported 256 colors.
727 • act
729 my $act = $pdf->colorspace('act', $filename);
731 An Adobe Color Table (ACT) file provides a custom palette of colors
733 that can be referenced by PDF graphics and text drawing commands.
734 • device
736 my $devicen = $pdf->colorspace('device', @colorspaces);
738 A device-specific colorspace allows for precise color output on a
740 given device (typically a printing press), bypassing the normal
741 color interpretation performed by raster image processors (RIPs).
742 Device colorspaces are also needed if you want to blend spot
744 colors:
745 my $pdf = PDF::API2->new();
747 my $page = $pdf->page();
748 my $content = $page->graphics();
749 # Create a two-color device colorspace
751 my $yellow = $pdf->colorspace('spot', 'Yellow', '%00F0');
752 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
753 my $device = $pdf->colorspace('device', $yellow, $spot);
754 # Fill using a blend of 25% yellow and 75% spot color
756 $content->fill_color($device, 0.25, 0.75);
757 # Stroke using 100% spot color
759 $content->stroke_color($device, 0, 1);
760 # Add a rectangle to the page
762 $content->rectangle(100, 100, 200, 200);
763 $content->paint();
764 $pdf->save('sample.pdf');
766 egstate
768 $resource = $pdf->egstate();
769 Creates and returns a new extended graphics state object, described in
771 PDF::API2::ExtGState.
772
774 Code written using PDF::API2 should continue to work unchanged for the
775 life of most long-term-stable (LTS) server distributions.
776 Specifically, it should continue working for versions of Perl that were
777 released within the past five years (the typical support window for LTS
778 releases) plus six months (allowing plenty of time for package freezes
779 prior to release).
780 In PDF::API2, method names, options, and functionality change over
782 time. Functionality that's documented (not just in source code
783 comments) should continue working for the same time period of five
784 years and six months, though deprecation warnings may be added. There
785 may be exceptions if your code happens to rely on bugs that get fixed,
786 including when a method in PDF::API2 is changed to more closely follow
787 the PDF specification.
788 Occasional breaking changes may be unavoidable or deemed small enough
790 in scope to be worth the benefit of making the change instead of
791 keeping the old behavior. These will be noted in the Changes file as
792 items beginning with the phrase "Breaking Change".
793 Undocumented features, unreleased code, features marked as
795 experimental, and underlying data structures may change at any time.
796 An exception is for features that were previously released and
797 documented, which should continue to work for the above time period
798 after the documentation is removed.
799 Before migrating to a new LTS server version, it's recommended that you
801 upgrade to the latest version of PDF::API2, "use warnings", and check
802 your server logs for deprecation messages after exercising your code.
803 Once these are resolved, it should be safe to use future PDF::API2
804 releases during that LTS support window.
805 If your code uses a PDF::API2 method that isn't documented here, it has
807 probably been deprecated. Search for it in the Migration section below
808 to find its replacement.
809
811 Use this section to bring your existing code up to date with current
812 method names and options. If you're not getting a deprecation warning,
813 this is optional, but still recommended.
814 For example, in cases where a method was simply renamed, the old name
816 will be set up as an alias for the new one, which can be maintained
817 indefinitely. The main benefit of switching to the new name is to make
818 it easier to find the appropriate documentation when you need it.
819 new(-compress => 0)
821 new(-file => $filename)
822 Remove the hyphen from the option names.
823 new() with any options other than "compress" or "file"
825 Replace with calls to "INTERACTIVE FEATURE METHODS". See the
826 deprecated "preferences" method for particular option names.
827 finishobjects
829 saveas
830 update
831 Replace with "save".
832 end
834 release
835 Replace with "close".
836 open_scalar
838 openScalar
839 Replace with "from_string".
840 stringify
842 Replace with "to_string".
843 info
845 Each of the hash keys now has its own accessor. See "METADATA
846 METHODS".
847 For custom keys or if you prefer to give the key names as variables
849 (e.g. as part of a loop), use "info_metadata".
850 infoMetaAttributes
852 Use "info_metadata" without arguments to get a list of currently-
853 set keys in the Info dictionary (including any custom keys). This
854 is slightly different behavior from calling "infoMetaAttributes"
855 without arguments, which always returns the standard key names and
856 any defined custom key names, whether or not they're present in the
857 PDF.
858 Calling "infoMetaAttributes" with arguments defines the list of
860 Info keys that are supported by the deprecated "info" method. You
861 can now just call "info_metadata" with a standard or custom key and
862 value.
863 xmpMetadata
865 Replace with "xml_metadata". Note that, when called with an
866 argument, "xml_metadata" returns the PDF object rather than the
867 value, to line up with most other PDF::API2 accessors.
868 isEncrypted
870 Replace with "is_encrypted".
871 outlines
873 Replace with "outline".
874 preferences
876 This functionality has been split into a few methods, aligning more
877 closely with the underlying PDF structure. See the documentation
878 for each of the methods for revised option names.
879 • -fullscreen, -thumbs, -outlines
881 Call "page_mode".
883 • -singlepage, -onecolumn, -twocolumnleft, -twocolumnright
885 Call "page_layout".
887 • -hidetoolbar, -hidemenubar, -hidewindowui, -fitwindow,
889 -centerwindow, -displaytitle, -righttoleft,
890 -afterfullscreenthumbs, -afterfullscreenoutlines,
891 -printscalingnone, -simplex, -duplexfliplongedge,
892 -duplexflipshortedge
893 Call "viewer_preferences".
895 • -firstpage
897 Call "open_action".
899 openpage
901 Replace with "open_page".
902 importpage
904 Replace with "import_page".
905 importPageIntoForm
907 Replace with "embed_page".
908 pages
910 Replace with "page_count".
911 pageLabel
913 Replace with "page_labels". Remove hyphens from the argument
914 names. Add "style => 'decimal'" if there wasn't a "-style"
915 argument.
916 mediabox
918 cropbox
919 bleedbox
920 trimbox
921 artbox
922 Replace with "default_page_boundaries". If using page size aliases
923 (e.g. "letter" or "A4"), check to ensure that the alias is still
924 supported (you'll get an error if it isn't).
925 synfont
927 Replace with "synthetic_font".
928 addFontDirs
930 Replace with "add_to_font_path".
931 corefont
933 Replace with "font". Note that "font" requires that the font name
934 be an exact, case-sensitive match. The full list can be found in
935 "STANDARD FONTS" in PDF::API2::Resource::Font::CoreFont.
936 ttfont
938 Replace with "font". Replace "-noembed => 1" with "embed => 0".
939 bdfont
941 Replace with "font".
942 psfont
944 Replace with "font". Rename options "-afmfile" and "-pfmfile" to
945 "afm_file" and "pfm_file".
946 Note that Adobe has announced that their products no longer support
948 Postscript Type 1 fonts, effective early 2023. They recommend
949 using TrueType or OpenType fonts instead.
950 cjkfont
952 unifont
953 These are old methods from back when Unicode was still new and
954 poorly supported. Replace them with calls to "font" using a
955 TrueType or OpenType font that has the characters you need.
956 If you're successfully using one of these two methods and feel they
958 shouldn't be deprecated, please contact me with your use case.
959 image_gd
961 image_gif
962 image_jpeg
963 image_png
964 image_pnm
965 image_tiff
966 Replace with "image".
967 xo_code128
969 xo_codabar
970 xo_2of5int
971 xo_3of9
972 xo_ean13
973 Replace with "barcode". Replace arguments as follows:
974 • "-color": "color"
976 • "-fnsz": "font_size"
978 • "-font": "font"
980 • "-lmzn": "bar_extend"
982 • "-ofwt": "bar_overflow"
984 • "-quzn": "quiet_zone"
986 • "-zone": "bar_height"
988 These options are simple renames.
990 • "-mils": "bar_width"
992 This requires a conversion from mils to points. The
994 "bar_width" documentation has sample code to do the conversion.
995 • "-ean"
997 Specify "ean128" as the barcode format instead of "code128".
999 colorspace_act
1001 colorspace_web
1002 colorspace_separation
1003 colorspace_devicen
1004 Replace with "colorspace".
1005 colorspace_hue
1007 This is deprecated because I wasn't able to find a corresponding
1008 standard. Please contact me if you're using it, to avoid having it
1009 be removed in a future release.
1010 default
1012 The optional changes in default behavior have all been deprecated.
1013 Replace "pageencaps" with calls to "save" and "restore" when
1015 embedding or superimposing a page onto another, if needed.
1016 "nounrotate" and "copyannots" will continue to work until better
1018 options are available, but should not be used in new code.
1019
1021 PDF::API2 is developed and maintained by Steve Simms, with patches from
1022 numerous contributors who are credited in the Changes file.
1023 It was originally written by Alfred Reibenschuh, extending code written
1025 by Martin Hosken.
1026
1028 This program is free software: you can redistribute it and/or modify it
1029 under the terms of the GNU Lesser General Public License as published
1030 by the Free Software Foundation, either version 2.1 of the License, or
1031 (at your option) any later version.
1032 This library is distributed in the hope that it will be useful, but
1034 WITHOUT ANY WARRANTY; without even the implied warranty of
1035 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1036 Lesser General Public License for more details.
1037perl v5.36.0 2023-01-20 PDF::API2(3)