1PDF::API2(3)          User Contributed Perl Documentation         PDF::API2(3)
2
3
4

NAME

6       PDF::API2 - Create, modify, and examine PDF files
7

SYNOPSIS

9           use PDF::API2;
10
11           # Create a blank PDF file
12           $pdf = PDF::API2->new();
13
14           # Open an existing PDF file
15           $pdf = PDF::API2->open('some.pdf');
16
17           # Add a blank page
18           $page = $pdf->page();
19
20           # Retrieve an existing page
21           $page = $pdf->open_page($page_number);
22
23           # Set the page size
24           $page->size('Letter');
25
26           # Add a built-in font to the PDF
27           $font = $pdf->font('Helvetica-Bold');
28
29           # Add an external TrueType font to the PDF
30           $font = $pdf->font('/path/to/font.ttf');
31
32           # 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
38           # Save the PDF
39           $pdf->save('/path/to/new.pdf');
40

INPUT/OUTPUT METHODS

42   new
43           my $pdf = PDF::API2->new(%options);
44
45       Create a new PDF.
46
47       The following options are available:
48
49       •   file
50
51           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
55       •   compress
56
57           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
61   open
62           my $pdf = PDF::API2->open('/path/to/file.pdf', %options);
63
64       Open an existing PDF file.
65
66       The following option is available:
67
68       •   compress
69
70           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
74   save
75           $pdf->save('/path/to/file.pdf');
76
77       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
80       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
83   close
84           $pdf->close();
85
86       Close an open file (if relevant) and remove the object structure from
87       memory.
88
89       PDF::API2 contains circular references, so this call is necessary in
90       long-running processes to keep from running out of memory.
91
92       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
96   from_string
97           my $pdf = PDF::API2->from_string($pdf_string, %options);
98
99       Read a PDF document contained in a string.
100
101       The following option is available:
102
103       •   compress
104
105           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
109   to_string
110           my $string = $pdf->to_string();
111
112       Return the PDF document as a string.
113
114       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

METADATA METHODS

118   title
119           $title = $pdf->title();
120           $pdf = $pdf->title($title);
121
122       Get/set/clear the document's title.
123
124   author
125           $author = $pdf->author();
126           $pdf = $pdf->author($author);
127
128       Get/set/clear the name of the person who created the document.
129
130   subject
131           $subject = $pdf->subject();
132           $pdf = $pdf->subject($subject);
133
134       Get/set/clear the subject of the document.
135
136   keywords
137           $keywords = $pdf->keywords();
138           $pdf = $pdf->keywords($keywords);
139
140       Get/set/clear a space-separated string of keywords associated with the
141       document.
142
143   creator
144           $creator = $pdf->creator();
145           $pdf = $pdf->creator($creator);
146
147       Get/set/clear the name of the product that created the document prior
148       to its conversion to PDF.
149
150   producer
151           $producer = $pdf->producer();
152           $pdf = $pdf->producer($producer);
153
154       Get/set/clear the name of the product that converted the original
155       document to PDF.
156
157       PDF::API2 fills in this field when creating a PDF.
158
159   created
160           $date = $pdf->created();
161           $pdf = $pdf->created($date);
162
163       Get/set/clear the document's creation date.
164
165       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
170       When setting the date, "D:" will be prepended automatically if omitted.
171
172   modified
173           $date = $pdf->modified();
174           $pdf = $pdf->modified($date);
175
176       Get/set/clear the document's modification date.  The date format is as
177       described in "created" above.
178
179   info_metadata
180           # Get all keys and values
181           %info = $pdf->info_metadata();
182
183           # Get the value of one key
184           $value = $pdf->info_metadata($key);
185
186           # Set the value of one key
187           $pdf = $pdf->info_metadata($key, $value);
188
189       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
193       Pass "undef" as the value in order to remove the key from the
194       dictionary.
195
196   xml_metadata
197           $xml = $pdf->xml_metadata();
198           $pdf = $pdf->xml_metadata($xml);
199
200       Get/set the document's XML metadata stream.
201
202   version
203           $version = $pdf->version($new_version);
204
205       Get/set the PDF version (e.g. 1.4).
206
207   is_encrypted
208           $boolean = $pdf->is_encrypted();
209
210       Returns true if the opened PDF is encrypted.
211

INTERACTIVE FEATURE METHODS

213   outline
214           $outline = $pdf->outlines();
215
216       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
220       To examine or modify the outline tree, see PDF::API2::Outline.
221
222   open_action
223           $pdf = $pdf->open_action($page, $location, @args);
224
225       Set the destination in the PDF that should be displayed when the
226       document is opened.
227
228       $page may be either a page number or a page object.  The other
229       parameters are as described in PDF::API2::NamedDestination.
230
231   page_layout
232           $layout = $pdf->page_layout();
233           $pdf = $pdf->page_layout($layout);
234
235       Get/set the page layout that should be used when the PDF is opened.
236
237       $layout is one of the following:
238
239       •   single_page (or undef)
240
241           Display one page at a time.
242
243       •   one_column
244
245           Display the pages in one column (a.k.a. continuous).
246
247       •   two_column_left
248
249           Display the pages in two columns, with odd-numbered pages on the
250           left.
251
252       •   two_column_right
253
254           Display the pages in two columns, with odd-numbered pages on the
255           right.
256
257       •   two_page_left
258
259           Display two pages at a time, with odd-numbered pages on the left.
260
261       •   two_page_right
262
263           Display two pages at a time, with odd-numbered pages on the right.
264
265   page_mode
266           # Get
267           $mode = $pdf->page_mode();
268
269           # Set
270           $pdf = $pdf->page_mode($mode);
271
272       Get/set the page mode, which describes how the PDF should be displayed
273       when opened.
274
275       $mode is one of the following:
276
277       •   none (or undef)
278
279           Neither outlines nor thumbnails should be displayed.
280
281       •   outlines
282
283           Show the document outline.
284
285       •   thumbnails
286
287           Show the page thumbnails.
288
289       •   full_screen
290
291           Open in full-screen mode, with no menu bar, window controls, or any
292           other window visible.
293
294       •   optional_content
295
296           Show the optional content group panel.
297
298       •   attachments
299
300           Show the attachments panel.
301
302   viewer_preferences
303           # Get
304           %preferences = $pdf->viewer_preferences();
305
306           # Set
307           $pdf = $pdf->viewer_preferences(%preferences);
308
309       Get or set PDF viewer preferences, as described in
310       PDF::API2::ViewerPreferences.
311

PAGE METHODS

313   page
314            # Add a page to the end of the document
315            $page = $pdf->page();
316
317            # Insert a page before the specified page number
318            $page = $pdf->page($page_number);
319
320       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
324       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
327   open_page
328           $page = $pdf->open_page($page_number);
329
330       Returns the PDF::API2::Page object of page $page_number, if it exists.
331
332       If $page_number is 0 or -1, it will return the last page in the
333       document.
334
335   import_page
336           $page = $pdf->import_page($source_pdf, $source_page_num, $target_page_num);
337
338       Imports a page from $source_pdf and adds it to the specified position
339       in $pdf.
340
341       If $source_page_num or $target_page_num is 0 or -1, the last page in
342       the document is used.
343
344       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
348       Example:
349
350           my $pdf = PDF::API2->new();
351           my $source = PDF::API2->open('source.pdf');
352
353           # Add page 2 from the source PDF as page 1 of the new PDF
354           my $page = $pdf->import_page($source, 2);
355
356           $pdf->save('sample.pdf');
357
358       Note: You can only import a page from an existing PDF file.
359
360   embed_page
361           $xobject = $pdf->embed_page($source_pdf, $source_page_number);
362
363       Returns a Form XObject created by extracting the specified page from a
364       $source_pdf.
365
366       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
369       If $source_page_number is 0 or -1, it will return the last page in the
370       document.
371
372       Example:
373
374           my $pdf = PDF::API2->new();
375           my $source = PDF::API2->open('source.pdf');
376           my $page = $pdf->page();
377
378           # Import Page 2 from the source PDF
379           my $object = $pdf->embed_page($source, 2);
380
381           # 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
385           $pdf->save('sample.pdf');
386
387       Note: You can only import a page from an existing PDF file.
388
389   page_count
390           $integer = $pdf->page_count();
391
392       Return the number of pages in the document.
393
394   page_labels
395           $pdf = $pdf->page_labels($page_number, %options);
396
397       Describes how pages should be numbered beginning at the specified page
398       number.
399
400           # Generate a 30-page PDF
401           my $pdf = PDF::API2->new();
402           $pdf->page() for 1..30;
403
404           # 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
409           $pdf->save('sample.pdf');
410
411       The following options are available:
412
413       •   style
414
415           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
419           There is no default numbering style.  If omitted, the page label
420           will be just the prefix (if set) or an empty string.
421
422       •   prefix
423
424           The label prefix for pages in this range.
425
426       •   start
427
428           An integer (default: 1) representing the first value to be used in
429           this page range.
430
431   default_page_size
432           # Set
433           $pdf->default_page_size($size);
434
435           # Get
436           @rectangle = $pdf->default_page_size()
437
438       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
442       See "Page Sizes" in PDF::API2::Page for possible values.
443
444   default_page_boundaries
445           # Set
446           $pdf->default_page_boundaries(%boundaries);
447
448           # Get
449           %boundaries = $pdf->default_page_boundaries();
450
451       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
455       See the equivalent "page_boundaries" method in PDF::API2::Page for
456       details.
457

FONT METHODS

459   font
460           my $font = $pdf->font($name, %options)
461
462       Add a font to the PDF.  Returns the font object, to be used by
463       PDF::API2::Content.
464
465       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
468           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
474           $content->position(1 * 72, 9 * 72);
475           $content->font($font1, 24);
476           $content->text('Hello, World!');
477
478           $content->position(0, -36);
479           $content->font($font2, 12);
480           $content->text('This is some sample text.');
481
482           $pdf->save('sample.pdf');
483
484       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
487       TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph
488       Bitmap Distribution Format (bdf) fonts are supported.
489
490       The following %options are available:
491
492       •   format
493
494           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
499       •   kerning
500
501           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
505       •   afm_file (PostScript Type 1 fonts only)
506
507           Specifies the location of the font metrics file.
508
509       •   pfm_file (PostScript Type 1 fonts only)
510
511           Specifies the location of the printer font metrics file.  This
512           option overrides the -encode option.
513
514       •   embed (TrueType fonts only)
515
516           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
521   synthetic_font
522           $font = $pdf->synthetic_font($base_font, %options)
523
524       Create and return a new synthetic font object.  See
525       PDF::API2::Resource::Font::SynFont for details.
526
527   font_path
528           @directories = PDF::API2->font_path()
529
530       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
534   add_to_font_path
535           @directories = PDF::API2->add_to_font_path('/my/fonts', '/path/to/fonts');
536
537       Add one or more directories to the list of paths to be searched for
538       font files.
539
540       Returns the font search path.
541
542   set_font_path
543           @directories = PDF::API2->set_font_path('/my/fonts', '/path/to/fonts');
544
545       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
549       Returns the font search path.
550

GRAPHICS METHODS

552   image
553           $object = $pdf->image($file, %options);
554
555       Import a supported image type and return an object that can be placed
556       as part of a page's content:
557
558           my $pdf = PDF::API2->new();
559           my $page = $pdf->page();
560
561           my $image = $pdf->image('/path/to/image.jpg');
562           $page->object($image, 100, 100);
563
564           $pdf->save('sample.pdf');
565
566       $file may be either a file name, a filehandle, or a GD::Image object.
567
568       See "place" in PDF::API2::Content for details about placing images on a
569       page once they're imported.
570
571       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
575       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
579       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
586   barcode
587           $object = $pdf->barcode($format, $code, %options);
588
589       Generate and return a barcode that can be placed as part of a page's
590       content:
591
592           my $pdf = PDF::API2->new();
593           my $page = $pdf->page();
594
595           my $barcode = $pdf->barcode('ean13', '0123456789012');
596           $page->object($barcode, 100, 100);
597
598           $pdf->save('sample.pdf');
599
600       $format can be one of "codabar", "code128", "code39" (a.k.a. 3 of 9),
601       "ean128", "ean13", or "itf" (a.k.a. interleaved 2 of 5).
602
603       $code is the value to be encoded.  Start and stop characters are only
604       required when they're not static (e.g. for Codabar).
605
606       The following options are available:
607
608       •   bar_width
609
610           The width of the smallest bar or space in points (72 points = 1
611           inch).
612
613           If you're following a specification that gives bar width in mils
614           (thousandths of an inch), use this conversion: "$points = $mils /
615           1000 * 72".
616
617       •   bar_height
618
619           The base height of the barcode in points.
620
621       •   bar_extend
622
623           If present, bars for non-printing characters (e.g. start and stop
624           characters) will be extended downward by this many points, and
625           printing characters will be shown below their respective bars.
626
627           This is enabled by default for EAN-13 barcodes.
628
629       •   caption
630
631           If present, this value will be printed, centered, beneath the
632           barcode, and should be a human-readable representation of the
633           barcode.
634
635       •   font
636
637           A font object (created by "font") that will be used to print the
638           caption, or the printable characters when "bar_extend" is set.
639
640           Helvetica will be used by default.
641
642       •   font_size
643
644           The size of the font used for printing the caption or printable
645           characters.
646
647           The default will be calculated based on the barcode size, if
648           "bar_extend" is set, or 10 otherwise.
649
650       •   quiet_zone
651
652           A margin, in points, that will be place before the left and bottom
653           edges of the barcode (including the caption, if present).  This is
654           used to help barcode scanners tell where the barcode begins and
655           ends.
656
657           The default is the width of one encoded character.
658
659       •   bar_overflow
660
661           Shrinks the horizontal width of bars by this amount in points to
662           account for ink spread when printing.
663
664           The default is 0.01 points.
665
666       •   color
667
668           Draw bars using this color, which may be any value accepted by
669           "fillcolor" in PDF::API2::Content.
670
671           The default is black.
672
673   colorspace
674           $colorspace = $pdf->colorspace($type, @arguments);
675
676       Colorspaces can be added to a PDF to either specifically control the
677       output color on a particular device (spot colors, device colors) or to
678       save space by limiting the available colors to a defined color palette
679       (web-safe palette, ACT file).
680
681       Once added to the PDF, they can be used in place of regular hex codes
682       or named colors:
683
684           my $pdf = PDF::API2->new();
685           my $page = $pdf->page();
686           my $content = $page->graphics();
687
688           # Add colorspaces for a spot color and the web-safe color palette
689           my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
690           my $web = $pdf->colorspace('web');
691
692           # Fill using the spot color with 100% coverage
693           $content->fill_color($spot, 1.0);
694
695           # Stroke using the first color of the web-safe palette
696           $content->stroke_color($web, 0);
697
698           # Add a rectangle to the page
699           $content->rectangle(100, 100, 200, 200);
700           $content->paint();
701
702           $pdf->save('sample.pdf');
703
704       The following types of colorspaces are supported
705
706       •   spot
707
708               my $spot = $pdf->colorspace('spot', $tint, $alt_color);
709
710           Spot colors are used to instruct a device (usually a printer) to
711           use or emulate a particular ink color ($tint) for parts of the
712           document.  An $alt_color is provided for devices (e.g. PDF viewers)
713           that don't know how to produce the named color.  It can either be
714           an approximation of the color in RGB, CMYK, or HSV formats, or a
715           wildly different color (e.g. 100% magenta, %0F00) to make it clear
716           if the spot color isn't being used as expected.
717
718       •   web
719
720               my $web = $pdf->colorspace('web');
721
722           The web-safe color palette is a historical collection of colors
723           that was used when many display devices only supported 256 colors.
724
725       •   act
726
727               my $act = $pdf->colorspace('act', $filename);
728
729           An Adobe Color Table (ACT) file provides a custom palette of colors
730           that can be referenced by PDF graphics and text drawing commands.
731
732       •   device
733
734               my $devicen = $pdf->colorspace('device', @colorspaces);
735
736           A device-specific colorspace allows for precise color output on a
737           given device (typically a printing press), bypassing the normal
738           color interpretation performed by raster image processors (RIPs).
739
740           Device colorspaces are also needed if you want to blend spot
741           colors:
742
743               my $pdf = PDF::API2->new();
744               my $page = $pdf->page();
745               my $content = $page->graphics();
746
747               # Create a two-color device colorspace
748               my $yellow = $pdf->colorspace('spot', 'Yellow', '%00F0');
749               my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
750               my $device = $pdf->colorspace('device', $yellow, $spot);
751
752               # Fill using a blend of 25% yellow and 75% spot color
753               $content->fill_color($device, 0.25, 0.75);
754
755               # Stroke using 100% spot color
756               $content->stroke_color($device, 0, 1);
757
758               # Add a rectangle to the page
759               $content->rectangle(100, 100, 200, 200);
760               $content->paint();
761
762               $pdf->save('sample.pdf');
763
764   egstate
765           $resource = $pdf->egstate();
766
767       Creates and returns a new extended graphics state object, described in
768       PDF::API2::ExtGState.
769

BACKWARD COMPATIBILITY

771       Code written using PDF::API2 should continue to work unchanged for the
772       life of most long-term-stable (LTS) server distributions.
773       Specifically, it should continue working for versions of Perl that were
774       released within the past five years (the typical support window for LTS
775       releases) plus six months (allowing plenty of time for package freezes
776       prior to release).
777
778       In PDF::API2, method names, options, and functionality change over
779       time.  Functionality that's documented (not just in source code
780       comments) should continue working for the same time period of five
781       years and six months, though deprecation warnings may be added.  There
782       may be exceptions if your code happens to rely on bugs that get fixed,
783       including when a method in PDF::API2 is changed to more closely follow
784       the PDF specification.
785
786       Occasional breaking changes may be unavoidable or deemed small enough
787       in scope to be worth the benefit of making the change instead of
788       keeping the old behavior.  These will be noted in the Changes file as
789       items beginning with the phrase "Breaking Change".
790
791       Undocumented features, unreleased code, features marked as
792       experimental, and underlying data structures may change at any time.
793       An exception is for features that were previously released and
794       documented, which should continue to work for the above time period
795       after the documentation is removed.
796
797       Before migrating to a new LTS server version, it's recommended that you
798       upgrade to the latest version of PDF::API2, "use warnings", and check
799       your server logs for deprecation messages after exercising your code.
800       Once these are resolved, it should be safe to use future PDF::API2
801       releases during that LTS support window.
802
803       If your code uses a PDF::API2 method that isn't documented here, it has
804       probably been deprecated.  Search for it in the Migration section below
805       to find its replacement.
806

MIGRATION

808       Use this section to bring your existing code up to date with current
809       method names and options.  If you're not getting a deprecation warning,
810       this is optional, but still recommended.
811
812       For example, in cases where a method was simply renamed, the old name
813       will be set up as an alias for the new one, which can be maintained
814       indefinitely.  The main benefit of switching to the new name is to make
815       it easier to find the appropriate documentation when you need it.
816
817       new(-compress => 0)
818       new(-file => $filename)
819           Remove the hyphen from the option names.
820
821       new() with any options other than "compress" or "file"
822           Replace with calls to "INTERACTIVE FEATURE METHODS".  See the
823           deprecated "preferences" method for particular option names.
824
825       finishobjects
826       saveas
827       update
828           Replace with "save".
829
830       end
831       release
832           Replace with "close".
833
834       open_scalar
835       openScalar
836           Replace with "from_string".
837
838       stringify
839           Replace with "to_string".
840
841       info
842           Each of the hash keys now has its own accessor.  See "METADATA
843           METHODS".
844
845           For custom keys or if you prefer to give the key names as variables
846           (e.g. as part of a loop), use "info_metadata".
847
848       infoMetaAttributes
849           Use "info_metadata" without arguments to get a list of currently-
850           set keys in the Info dictionary (including any custom keys).  This
851           is slightly different behavior from calling "infoMetaAttributes"
852           without arguments, which always returns the standard key names and
853           any defined custom key names, whether or not they're present in the
854           PDF.
855
856           Calling "infoMetaAttributes" with arguments defines the list of
857           Info keys that are supported by the deprecated "info" method.  You
858           can now just call "info_metadata" with a standard or custom key and
859           value.
860
861       xmpMetadata
862           Replace with "xml_metadata".  Note that, when called with an
863           argument, "xml_metadata" returns the PDF object rather than the
864           value, to line up with most other PDF::API2 accessors.
865
866       isEncrypted
867           Replace with "is_encrypted".
868
869       outlines
870           Replace with "outline".
871
872       preferences
873           This functionality has been split into a few methods, aligning more
874           closely with the underlying PDF structure.  See the documentation
875           for each of the methods for revised option names.
876
877           •   -fullscreen, -thumbs, -outlines
878
879               Call "page_mode".
880
881           •   -singlepage, -onecolumn, -twocolumnleft, -twocolumnright
882
883               Call "page_layout".
884
885           •   -hidetoolbar, -hidemenubar, -hidewindowui, -fitwindow,
886               -centerwindow, -displaytitle, -righttoleft,
887               -afterfullscreenthumbs, -afterfullscreenoutlines,
888               -printscalingnone, -simplex, -duplexfliplongedge,
889               -duplexflipshortedge
890
891               Call "viewer_preferences".
892
893           •   -firstpage
894
895               Call "open_action".
896
897       openpage
898           Replace with "open_page".
899
900       importpage
901           Replace with "import_page".
902
903       importPageIntoForm
904           Replace with "embed_page".
905
906       pages
907           Replace with "page_count".
908
909       pageLabel
910           Replace with "page_labels".  Remove hyphens from the argument
911           names.  Add "style => 'decimal'" if there wasn't a "-style"
912           argument.
913
914       mediabox
915       cropbox
916       bleedbox
917       trimbox
918       artbox
919           Replace with "default_page_boundaries".  If using page size aliases
920           (e.g. "letter" or "A4"), check to ensure that the alias is still
921           supported (you'll get an error if it isn't).
922
923       synfont
924           Replace with "synthetic_font".
925
926       addFontDirs
927           Replace with "add_to_font_path".
928
929       corefont
930           Replace with "font".  Note that "font" requires that the font name
931           be an exact, case-sensitive match.  The full list can be found in
932           "STANDARD FONTS" in PDF::API2::Resource::Font::CoreFont.
933
934       ttfont
935           Replace with "font".  Replace "-noembed => 1" with "embed => 0".
936
937       bdfont
938           Replace with "font".
939
940       psfont
941           Replace with "font".  Rename options "-afmfile" and "-pfmfile" to
942           "afm_file" and "pfm_file".
943
944           Note that Adobe has announced that their products no longer support
945           Postscript Type 1 fonts, effective early 2023.  They recommend
946           using TrueType or OpenType fonts instead.
947
948       cjkfont
949       unifont
950           These are old methods from back when Unicode was still new and
951           poorly supported.  Replace them with calls to "font" using a
952           TrueType or OpenType font that has the characters you need.
953
954           If you're successfully using one of these two methods and feel they
955           shouldn't be deprecated, please contact me with your use case.
956
957       image_gd
958       image_gif
959       image_jpeg
960       image_png
961       image_pnm
962       image_tiff
963           Replace with "image".
964
965       xo_code128
966       xo_codabar
967       xo_2of5int
968       xo_3of9
969       xo_ean13
970           Replace with "barcode".  Replace arguments as follows:
971
972           •   "-color": "color"
973
974           •   "-fnsz": "font_size"
975
976           •   "-font": "font"
977
978           •   "-lmzn": "bar_extend"
979
980           •   "-ofwt": "bar_overflow"
981
982           •   "-quzn": "quiet_zone"
983
984           •   "-zone": "bar_height"
985
986               These options are simple renames.
987
988           •   "-mils": "bar_width"
989
990               This requires a conversion from mils to points.  The
991               "bar_width" documentation has sample code to do the conversion.
992
993           •   "-ean"
994
995               Specify "ean128" as the barcode format instead of "code128".
996
997       colorspace_act
998       colorspace_web
999       colorspace_separation
1000       colorspace_devicen
1001           Replace with "colorspace".
1002
1003       colorspace_hue
1004           This is deprecated because I wasn't able to find a corresponding
1005           standard.  Please contact me if you're using it, to avoid having it
1006           be removed in a future release.
1007
1008       default
1009           The optional changes in default behavior have all been deprecated.
1010
1011           Replace "pageencaps" with calls to "save" and "restore" when
1012           embedding or superimposing a page onto another, if needed.
1013
1014           "nounrotate" and "copyannots" will continue to work until better
1015           options are available, but should not be used in new code.
1016

AUTHOR

1018       PDF::API2 is developed and maintained by Steve Simms, with patches from
1019       numerous contributors who are credited in the Changes file.
1020
1021       It was originally written by Alfred Reibenschuh, extending code written
1022       by Martin Hosken.
1023

LICENSE

1025       This program is free software: you can redistribute it and/or modify it
1026       under the terms of the GNU Lesser General Public License as published
1027       by the Free Software Foundation, either version 2.1 of the License, or
1028       (at your option) any later version.
1029
1030       This library is distributed in the hope that it will be useful, but
1031       WITHOUT ANY WARRANTY; without even the implied warranty of
1032       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1033       Lesser General Public License for more details.
1034
1035
1036
1037perl v5.36.0                      2022-07-22                      PDF::API2(3)
Impressum