1PDF::Builder(3) User Contributed Perl Documentation PDF::Builder(3)
2
6 PDF::Builder - Facilitates the creation and modification of PDF files
7
9 use PDF::Builder;
10 # Create a blank PDF file
12 $pdf = PDF::Builder->new();
13 # Open an existing PDF file
15 $pdf = PDF::Builder->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'); # or mediabox('Letter')
25 # Add a built-in font to the PDF
27 $font = $pdf->font('Helvetica-Bold'); # or corefont('Helvetica-Bold')
28 # Add an external TrueType (TTF) font to the PDF
30 $font = $pdf->font('/path/to/font.ttf'); # or ttfont() in this case
31 # Add some text to the page
33 $text = $page->text();
34 $text->font($font, 20);
35 $text->position(200, 700); # or translate()
36 $text->text('Hello World!');
37 # Save the PDF
39 $pdf->saveas('/path/to/new.pdf');
40
42 See the file README.md (in downloadable package and on CPAN) for a
43 summary of prerequisites and tools needed to install PDF::Builder, both
44 mandatory and optional.
45 SOFTWARE DEVELOPMENT KIT
47 There are four levels of involvement with PDF::Builder. Depending on
48 what you want to do, different kinds of installs are recommended. See
49 "Software Development Kit" in PDF::Builder::Docs for suggestions.
50 OPTIONAL LIBRARIES
52 PDF::Builder can make use of some optional libraries, which are not
53 required for a successful installation, but improve speed and
54 capabilities. See "Optional Libraries" in PDF::Builder::Docs for more
55 information.
56 STRINGS (CHARACTER TEXT)
58 There are some things you should know about character encoding (for
59 text), before you dive in to coding. Please go to "Strings (Character
60 Text)" in PDF::Builder::Docs and have a read.
61 RENDERING ORDER
63 Invoking "text" and "graphics" methods can lead to unexpected results
64 (a different ordering of output than intended). See "Rendering Order"
65 in PDF::Builder::Docs for more information.
66 PDF VERSIONS SUPPORTED
68 PDF::Builder is mostly PDF 1.4-compliant, but there are complications
69 you should be aware of. Please read "PDF Versions Supported" in
70 PDF::Builder::Docs for details.
71 SUPPORTED PERL VERSIONS (BACKWARDS COMPATIBILITY GOALS)
73 PDF::Builder intends to support all major Perl versions that were
74 released in the past six years, plus one, in order to continue working
75 for the life of most long-term-stable (LTS) server distributions. See
76 the <https://www.cpan.org/src/> table First release in each branch of
77 Perl x.xxxx0 "Major" release dates.
78 For example, a version of PDF::Builder released on 2018-06-05 would
80 support the last major version of Perl released on or after 2012-06-05
81 (5.18), and then one before that, which would be 5.16. Alternatively,
82 the last major version of Perl released before 2012-06-05 is 5.16.
83 The intent is to avoid expending unnecessary effort in supporting very
85 old (obsolete) versions of Perl.
86 Anticipated Support Cutoff Dates
88 Note that these are not hard and fast dates. In particular, we develop
90 on Strawberry Perl, which is currently stuck at release 5.32! We'll
91 have to see whether we can get around this problem in the summer of
92 2023, if Strawberry hasn't yet gotten up to at least 5.36 by then.
93 • 5.24 current minimum supported version, until next PDF::Builder
95 release after 30 May, 2023
96 • 5.26 future minimum supported version, until next PDF::Builder
98 release after 23 June, 2024
99 • 5.28 future minimum supported version, until next PDF::Builder
101 release after 22 May, 2025
102 • 5.30 future minimum supported version, until next PDF::Builder
104 release after 20 June, 2026
105 • 5.32 future minimum supported version, until next PDF::Builder
107 release after 20 May, 2027
108 • 5.34 future minimum supported version, until next PDF::Builder
110 release after 28 May, 2028
111 If you need to use this module on a server with an extremely out-of-
113 date version of Perl, consider using either plenv or Perlbrew to run a
114 newer version of Perl without needing admin privileges.
115 On the other hand, any feature in PDF::Builder should continue to work
117 unchanged for the life of most long-term-stable (LTS) server
118 distributions. Their lifetime is usually about six (6) years. Note
119 that this does not constitute a statement of warranty, but that we
120 intend to try to keep any particular release of PDF::Builder working
121 for a period of years. Of course, it helps if you periodically update
122 your Perl installation to something released in the recent past.
123 KNOWN ISSUES
125 This module does not work with perl's -l command-line switch.
126 There is a file INFO/KNOWN_INCOMP which lists known incompatibilities
128 with PDF::API2, in case you're thinking of porting over something from
129 that world, or have experience there and want to try PDF::Builder.
130 There is also a file INFO/DEPRECATED, which lists things which are
131 planned to be removed at some point.
132 HISTORY
134 The history of PDF::Builder is a complex and exciting saga... OK, it
135 may be mildly interesting. Have a look at "History" in
136 PDF::Builder::Docs section.
137 AUTHOR
139 PDF::API2 was originally written by Alfred Reibenschuh. See the HISTORY
140 section for more information.
141 It was maintained by Steve Simms, who is still contributing new code to
143 it (which often ends up in PDF::Builder).
144 PDF::Builder is currently being maintained by Phil M. Perry.
146 SUPPORT
148 The full source is on https://github.com/PhilterPaper/Perl-PDF-Builder.
149 The release distribution is on CPAN:
151 https://metacpan.org/pod/PDF::Builder.
152 Bug reports are on
154 https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc
155 (with "bug" label), feature requests have an "enhancement" label, and
156 general discussions (architecture, roadmap, etc.) have a "general
157 discussion" label.
158 Do not under any circumstances open a PR (Pull Request) to report a
160 bug. It is a waste of both your and our time and effort. Open a
161 regular ticket (issue), and attach a Perl (.pl) program illustrating
162 the problem, if possible. If you believe that you have a program
163 patch, and offer to share it as a PR, we may give the go-ahead.
164 Unsolicited PRs may be closed without further action.
165 LICENSE
167 This software is Copyright (c) 2017-2023 by Phil M. Perry.
168 This is free software, licensed under:
170 The GNU Lesser General Public License (LGPL) Version 2.1, February 1999
172 (The master copy of this license lives on the GNU website.)
174 (A copy is provided in the INFO/LICENSE file for your convenience.)
175 This section of Builder.pm is intended only as a very brief summary of
177 the license; please consider INFO/LICENSE to be the controlling
178 version, if there is any conflict or ambiguity between the two.
179 This program is free software; you can redistribute it and/or modify it
181 under the terms of the GNU Lesser General Public License, as published
182 by the Free Software Foundation, either version 2.1 of the License, or
183 (at your option) any later version of this license.
184 NOTE: there are several files in this distribution which were
186 incorporated from outside sources and carry different licenses. If a
187 file states that it is under a license different than LGPL 2.1, that
188 license and its terms will apply to that file, and not LGPL 2.1.
189 This library is distributed in the hope that it will be useful, but
191 WITHOUT ANY WARRANTY; without even the implied warranty of
192 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
193 General Public License for more details.
194
196 $pdf = PDF::Builder->new(%opts)
197 Creates a new PDF object.
198 Options
200 file
202 If you will be saving it as a file and already know the
203 filename, you can give the 'file' option to minimize possible
204 memory requirements later on (the file is opened immediately
205 for writing, rather than waiting until the "save"). The "file"
206 may also be a filehandle.
207 compress
209 The 'compress' option can be given to specify stream
210 compression: default is 'flate', 'none' (or 0) is no
211 compression. No other compression methods are currently
212 supported.
213 outver
215 The 'outver' option defaults to 1.4 as the output PDF version
216 and the highest allowed feature version (attempts to use
217 anything higher will give a warning). If an existing PDF with
218 a higher version is read in, "outver" will be increased to that
219 version, with a warning.
220 msgver
222 The 'msgver' option value of 1 (default) gives a warning
223 message if the 'outver' PDF level has to be bumped up due to
224 either a higher PDF level file being read in, or a higher level
225 feature was requested. A value of 0 suppresses the warning
226 message.
227 diaglevel
229 The 'diaglevel' option can be given to specify the level of
230 diagnostics given by IntegrityCheck(). The default is level 2
231 (errors and warnings). See "IntegrityCheck" in
232 PDF::Builder::Docs for more information.
233 Example:
235 $pdf = PDF::Builder->new();
237 ...
238 print $pdf->to_string();
239 $pdf = PDF::Builder->new(compress => 'none');
241 # equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)
242 $pdf = PDF::Builder->new();
244 ...
245 $pdf->saveas('our/new.pdf');
246 $pdf = PDF::Builder->new(file => 'our/new.pdf');
248 ...
249 $pdf->save();
250 $pdf->default_page_size($size); # Set
252 @rectangle = $pdf->default_page_size() # Get
253 Set the default physical size for pages in the PDF. If called
254 without arguments, return the coordinates of the rectangle
255 describing the default physical page size.
256 This is essentially an alternate method of defining the mediabox()
258 call, and added for compatibility with PDF::API2.
259 See "Page Sizes" in PDF::Builder::Page for possible values.
261 $pdf->default_page_boundaries(%boundaries); # Set
263 %boundaries = $pdf->default_page_boundaries(); # Get
264 Set default prepress page boundaries for pages in the PDF. If
265 called without arguments, returns the coordinates of the rectangles
266 describing each of the supported page boundaries.
267 See the equivalent "page_boundaries" method in PDF::Builder::Page
269 for details.
270
272 $pdf = PDF::Builder->open($pdf_file, %opts)
273 Opens an existing PDF file. See new() for options.
274 Example:
276 $pdf = PDF::Builder->open('our/old.pdf');
278 ...
279 $pdf->saveas('our/new.pdf');
280 $pdf = PDF::Builder->open('our/to/be/updated.pdf');
282 ...
283 $pdf->update();
284 $pdf = PDF::Builder->from_string($pdf_string, %opts)
286 Opens a PDF contained in a string. See new() for other options.
287 diags => 1
289 Display warnings when non-conforming PDF structure is found,
290 and fix up where possible. See PDF::Builder::Basic::PDF::File
291 for more information.
292 Example:
294 # Read a PDF into a string, for the purpose of demonstration
296 open $fh, 'our/old.pdf' or croak $@;
297 undef $/; # Read the whole file at once
298 $pdf_string = <$fh>;
299 $pdf = PDF::Builder->from_string($pdf_string);
301 ...
302 $pdf->saveas('our/new.pdf');
303 Alternate name: "open_scalar"
305 "from_string" was formerly known as "open_scalar" (and even before
307 that, as "openScalar"), and this older name is still valid as an
308 alternative to "from_string". It is possible that "open_scalar"
309 will be deprecated and then removed some time in the future, so it
310 may be advisable to use "from_string" in new work.
311 $string = $pdf->to_string()
313 Return the document as a string and remove the object structure
314 from memory.
315 Caution: Although the object $pdf will still exist, it is no longer
317 usable for any purpose after invoking this method! You will receive
318 error messages about "can't call method new_obj on an undefined
319 value".
320 Example:
322 $pdf = PDF::Builder->new();
324 ...
325 print $pdf->to_string();
326 Alternate name: "stringify"
328 "to_string" was formerly known as "stringify", and this older name
330 is still valid as an alternative to "to_string". It is possible
331 that "stringify" will be deprecated and then removed some time in
332 the future, so it may be advisable to use "to_string" in new work.
333 $pdf->finishobjects(@objects)
335 Force objects to be written to file if possible.
336 Example:
338 $pdf = PDF::Builder->new(file => 'our/new.pdf');
340 ...
341 $pdf->finishobjects($page, $gfx, $txt);
342 ...
343 $pdf->save();
344 Note: this method is now considered obsolete, and may be
346 deprecated. It allows for objects to be written to disk in advance
347 of finally saving and closing the file. Otherwise, it's no
348 different than just calling save() when all changes have been made.
349 There's no memory advantage since "ship_out" doesn't remove objects
350 from memory.
351 $pdf->update()
353 Saves a previously opened document.
354 Example:
356 $pdf = PDF::Builder->open('our/to/be/updated.pdf');
358 ...
359 $pdf->update();
360 Note: it is considered better to simply save() the file, rather
362 than calling update(). They end up doing the same thing, anyway.
363 This method may be deprecated in the future.
364 $pdf->saveas($file)
366 Save the document to $file and remove the object structure from
367 memory.
368 Caution: Although the object $pdf will still exist, it is no longer
370 usable for any purpose after invoking this method! You will receive
371 error messages about "can't call method new_obj on an undefined
372 value".
373 Example:
375 $pdf = PDF::Builder->new();
377 ...
378 $pdf->saveas('our/new.pdf');
379 $pdf->save()
381 $pdf->save(filename)
382 Save the document to an already-defined file (or filename) and
383 remove the object structure from memory. Optionally, a new
384 filename may be given.
385 Caution: Although the object $pdf will still exist, it is no longer
387 usable for any purpose after invoking this method! You will receive
388 error messages about "can't call method new_obj on an undefined
389 value".
390 Example:
392 $pdf = PDF::Builder->new(file => 'file_to_output');
394 ...
395 $pdf->save();
396 Note: now that save() can take a filename as an argument, it
398 effectively is interchangeable with saveas(). This is strictly for
399 compatibility with recent changes to PDF::API2. Unlike PDF::API2,
400 we are not deprecating the saveas() method, because in user
401 interfaces, "save" normally means that the current filename is
402 known and is to be used, while "saveas" normally means that
403 (whether or not there is a current filename) a new filename is to
404 be used.
405 $pdf->close();
407 Close an open file (if relevant) and remove the object structure
408 from memory.
409 PDF::API2 contains circular references, so this call is necessary
411 in long-running processes to keep from running out of memory.
412 This will be called automatically when you save or stringify a PDF.
414 You should only need to call it explicitly if you are reading PDF
415 files and not writing them.
416 Alternate names: "release" and "end"
418 $pdf->end()
420 Remove the object structure from memory. PDF::Builder contains
421 circular references, so this call is necessary in long-running
422 processes to keep from running out of memory.
423 This will be called automatically when you save or to_string a PDF.
425 You should only need to call it explicitly if you are reading PDF
426 files and not writing them.
427 This (and release) are older and now deprecated names formerly used
429 in PDF::API2 and PDF::Builder. You should try to avoid having to
430 explicitly call them.
431 METADATA METHODS
433 $title = $pdf->title();
434 $pdf = $pdf->title($title);
435 Get/set/clear the document's title.
436 $author = $pdf->author();
438 $pdf = $pdf->author($author);
439 Get/set/clear the name of the person who created the document.
440 $subject = $pdf->subject();
442 $pdf = $pdf->subject($subject);
443 Get/set/clear the subject of the document.
444 $keywords = $pdf->keywords();
446 $pdf = $pdf->keywords($keywords);
447 Get/set/clear a space-separated string of keywords associated with
448 the document.
449 $creator = $pdf->creator();
451 $pdf = $pdf->creator($creator);
452 Get/set/clear the name of the product that created the document
453 prior to its conversion to PDF.
454 $producer = $pdf->producer();
456 $pdf = $pdf->producer($producer);
457 Get/set/clear the name of the product that converted the original
458 document to PDF.
459 PDF::Builder fills in this field when creating a PDF.
461 $date = $pdf->created();
463 $pdf = $pdf->created($date);
464 Get/set/clear the document's creation date.
465 The date format is "D:YYYYMMDDHHmmSSOHH'mm", where "D:" is a static
467 prefix identifying the string as a PDF date. The date may be
468 truncated at any point after the year. "O" is one of "+", "-", or
469 "Z", with the following "HH'mm" representing an offset from UTC.
470 When setting the date, "D:" will be prepended automatically if
472 omitted.
473 $date = $pdf->modified();
475 $pdf = $pdf->modified($date);
476 Get/set/clear the document's modification date. The date format is
477 as described in "created" above.
478 %info = $pdf->info_metadata(); # Get all keys and values
480 $value = $pdf->info_metadata($key); # Get the value of one key
481 $pdf = $pdf->info_metadata($key, $value); # Set the value of one key
482 Get/set/clear a key in the document's information dictionary. The
483 standard keys (title, author, etc.) have their own accessors, so
484 this is primarily intended for interacting with custom metadata.
485 Pass "undef" as the value in order to remove the key from the
487 dictionary.
488 %infohash = $pdf->info()
490 %infohash = $pdf->info(%infohash)
491 Gets/sets the info structure of the document.
492 See "info Example" in PDF::Builder::Docs section for an example of
494 the use of this method.
495 Note: this method is still available, for compatibility purposes.
497 It is better to use individual accessors or "info_metadata"
498 instead.
499 @metadata_attributes = $pdf->infoMetaAttributes()
501 @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
502 Gets/sets the supported info-structure tags.
503 Example:
505 @attributes = $pdf->infoMetaAttributes;
507 print "Supported Attributes: @attr\n";
508 @attributes = $pdf->infoMetaAttributes('CustomField1');
510 print "Supported Attributes: @attributes\n";
511 Note: this method is still available for compatibility purposes,
513 but the use of "info_metadata" instead is encouraged.
514 $xml = $pdf->xml_metadata();
516 $pdf = $pdf->xml_metadata($xml);
517 Gets/sets the document's XML metadata stream.
518 $xml = $pdf->xmpMetadata() # Get
520 $xml = $pdf->xmpMetadata($xml) # Set (also returns $xml value)
521 Gets/sets the XMP XML data stream.
522 See "XMP XML example" in PDF::Builder::Docs section for an example
524 of the use of this method.
525 This method is considered obsolete. Use "xml_metadata" instead.
527 $val = $pdf->default($parameter)
529 $pdf->default($parameter, $value)
530 Gets/sets the default value for a behavior of PDF::Builder.
531 Supported Parameters:
533 nounrotate
535 prohibits Builder from rotating imported/opened page to re-
536 create a default pdf-context.
537 pageencaps
539 enables Builder's adding save/restore commands upon
540 importing/opening pages to preserve graphics-state for
541 modification.
542 copyannots
544 enables importing of annotations (*EXPERIMENTAL*).
545 CAUTION: Perl::Critic (tools/1_pc.pl) has started flagging the name
547 "default" as a reserved keyword in higher Perl versions. Use with
548 caution, and be aware that this name may have to be changed in the
549 future.
550 $version = $pdf->version() # Get
552 $version = $pdf->version($version) # Set (also returns newly set
553 version)
554 Gets/sets the PDF version (e.g., 1.5). For compatibility with
555 earlier releases, if no decimal point is given, assume "1."
556 precedes the number given.
557 A warning message is given if you attempt to decrease the PDF
559 version, as you might have already read in a higher level file, or
560 used a higher level feature.
561 See PDF::Builder::Basic::PDF::File for additional information on
563 the "version" method.
564 $bool = $pdf->is_encrypted()
566 Checks if the previously opened PDF is encrypted.
567 Alternate name: "isEncrypted"
569 This is the older name; it is kept for compatibility with
571 PDF::API2.
572
574 $otls = $pdf->outline()
575 Creates (if needed) and returns the document's 'outline' tree,
576 which is also known as its 'bookmarks' or the 'table of contents',
577 depending on the PDF reader being used.
578 To examine or modify the outline tree, see PDF::Builder::Outlines.
580 Alternate name: "outlines"
582 This is the older name; it is kept for compatibility.
584 $layout = $pdf->page_layout();
586 $pdf = $pdf->page_layout($layout);
587 Gets/sets the page layout that should be used when the PDF is
588 opened.
589 $layout is one of the following:
591 single_page (or undef)
593 Display one page at a time.
594 one_column
596 Display the pages in one column (a.k.a. continuous).
597 two_column_left
599 Display the pages in two columns, with odd-numbered pages on
600 the left.
601 two_column_right
603 Display the pages in two columns, with odd-numbered pages on
604 the right.
605 two_page_left
607 Display two pages at a time, with odd-numbered pages on the
608 left.
609 two_page_right
611 Display two pages at a time, with odd-numbered pages on the
612 right.
613 This has been split out from preferences() for compatibility with
615 PDF::API2. It also can both set (assign) and get (query) the
616 settings used.
617 $mode = $pdf->page_mode(); # Get
619 $pdf = $pdf->page_mode($mode); # Set
620 Gets/sets the page mode, which describes how the PDF should be
621 displayed when opened.
622 $mode is one of the following:
624 none (or undef)
626 Neither outlines nor thumbnails should be displayed.
627 outlines
629 Show the document outline.
630 thumbnails
632 Show the page thumbnails.
633 full_screen
635 Open in full-screen mode, with no menu bar, window controls, or
636 any other window visible.
637 optional_content
639 Show the optional content group panel.
640 attachments
642 Show the attachments panel.
643 This has been split out from preferences() for compatibility with
645 PDF::API2. It also can both set (assign) and get (query) the
646 settings used.
647 %preferences = $pdf->viewer_preferences(); # Get
649 $pdf = $pdf->viewer_preferences(%preferences); # Set
650 Gets/sets PDF viewer preferences, as described in
651 PDF::Builder::ViewerPreferences.
652 This has been split out from preferences() for compatibility with
654 PDF::API2. It also can both set (assign) and get (query) the
655 settings used.
656 $pdf->preferences(%opts)
658 Controls viewing preferences for the PDF, including the Page Mode,
659 Page Layout, Viewer, and Initial Page Options. See "Preferences -
660 set user display preferences" in PDF::Builder::Docs for details on
661 all these option groups, and "Page Fit Options" in
662 PDF::Builder::Docs for page positioning.
663 Note: the various preferences have been split out into their own
665 methods. It is preferred that you use these specific methods.
666
668 $page = $pdf->page()
669 $page = $pdf->page($page_number)
670 Returns a new page object. By default, the page is added to the
671 end of the document. If you give an existing page number, the new
672 page will be inserted in that position, pushing existing pages back
673 by 1 (e.g., page(5) would insert an empty page 5, with the old page
674 5 now page 6, etc.
675 If $page_number is -1, the new page is inserted as the second-to-
677 last page; if $page_number is 0, the new page is inserted as the
678 last page.
679 Example:
681 $pdf = PDF::Builder->new();
683 # Add a page. This becomes page 1.
685 $page = $pdf->page();
686 # Add a new first page. $page becomes page 2.
688 $another_page = $pdf->page(1);
689 $page = $pdf->open_page($page_number)
691 Returns the PDF::Builder::Page object of page $page_number. This
692 is similar to "$page = $pdf->page()", except that $page is not a
693 new, empty page; but contains the contents of that existing page.
694 If $page_number is 0, -1, or unspecified, it will return the last
696 page in the document. If the requested page is out of range, the
697 $page returned will be undefined.
698 Example:
700 $pdf = PDF::Builder->open('our/99page.pdf');
702 $page = $pdf->open_page(1); # returns the first page
703 $page = $pdf->open_page(99); # returns the last page
704 $page = $pdf->open_page(-1); # returns the last page
705 $page = $pdf->open_page(999); # returns undef
706 $page = $pdf->open_page(0); # returns the last page
707 $page = $pdf->open_page(); # returns the last page
708 Alternate name: "openpage"
710 This is the older name; it is kept for compatibility until after
712 June 2023 (deprecated, as previously announced).
713 $page = $pdf->import_page($source_pdf)
715 $page = $pdf->import_page($source_pdf, $source_page_number)
716 $page = $pdf->import_page($source_pdf, $source_page_number,
717 $target_page_number)
718 $page = $pdf->import_page($source_pdf, $source_page_number,
719 $target_page_object)
720 Imports a page from $source_pdf and adds it to the specified
721 position in $pdf.
722 If the $source_page_number is omitted, 0, or -1; the last page of
724 the source is imported. If the $target_page_number is omitted, 0,
725 or -1; the imported page will be placed as the new last page of the
726 target ($pdf). Otherwise, as with the page() method, the page will
727 be inserted before an existing page of that number.
728 Note: If you pass a page object instead of a page number for
730 $target_page_number, the contents of the page will be merged into
731 the existing page.
732 Example:
734 my $pdf = PDF::Builder->new();
736 my $source = PDF::Builder->open('source.pdf');
737 # Add page 2 from the old PDF as page 1 of the new PDF
739 my $page = $pdf->import_page($source, 2);
740 $pdf->saveas('sample.pdf');
742 Note: You can only import a page from an existing PDF file.
744 $xoform = $pdf->embed_page($source_pdf, $source_page_number)
746 Returns a Form XObject created by extracting the specified page
747 from $source_pdf.
748 This is useful if you want to transpose the imported page somewhat
750 differently onto a page (e.g. two-up, four-up, etc.).
751 If $source_page_number is 0 or -1, it will return the last page in
753 the document.
754 Example:
756 my $pdf = PDF::Builder->new();
758 my $source = PDF::Builder->open('source.pdf');
759 my $page = $pdf->page();
760 # Import Page 2 from the source PDF
762 my $object = $pdf->embed_page($source, 2);
763 # Add it to the new PDF's first page at 1/2 scale
765 my ($x, $y) = (0, 0);
766 $page->object($xo, $x, $y, 0.5);
767 $pdf->save('sample.pdf');
769 Note: You can only import a page from an existing PDF file.
771 Alternate name: "importPageIntoForm"
773 This is the older name; it is kept for compatibility.
775 $count = $pdf->page_count()
777 Returns the number of pages in the document.
778 Alternate name: "pages"
780 This is the old name; it is kept for compatibility.
782 $pdf->page_labels($page_number, $opts)
784 Sets page label numbering format, for the Reader's page-selection
785 slider thumb (not the outline/bookmarks). At this time, there is no
786 method to automatically synchronize a page's label with the
787 outline/bookmarks, or to somewhere on the printed page.
788 Note that many PDF Readers ignore these settings, and (at most)
790 simply give you the physical page number 1, 2, 3,... instead of the
791 page label specified here.
792 # Generate a 30-page PDF
794 my $pdf = PDF::Builder->new();
795 $pdf->page() for 1..30;
796 # Number pages i to v, 1 to 20, and A-1 to A-5, respectively
798 $pdf->page_labels(1, 'style' => 'roman');
799 $pdf->page_labels(6, 'style' => 'decimal');
800 $pdf->page_labels(26, 'style' => 'decimal', 'prefix' => 'A-');
801 $pdf->save('sample.pdf');
803 Supported Options:
805 style
807 Roman (I,II,III,...), roman (i,ii,iii,...), decimal
808 (1,2,3,...), Alpha (A,B,C,...), alpha (a,b,c,...), or
809 nocounter. This is the styling of the counter part of the label
810 (unless "nocounter", in which case there is no counter output).
811 start
813 (Re)start numbering the counter at given page number (this is a
814 decimal integer, not the styled counter). By default it starts
815 at 1, and resets to 1 at each call to page_labels()! You need
816 to explicitly give "start" if you want to continue counting at
817 the current page number when you call page_labels(), whether or
818 not you are changing the format.
819 Also note that the counter starts at physical page 1, while the
821 page $index number in the page_labels() call (as well as the
822 PDF PageLabels dictionary) starts at logical page (index) 0.
823 prefix
825 Text prefix for numbering, such as an Appendix letter B-. If
826 "style" is nocounter, just this text is used, otherwise a
827 styled counter will be appended. If "style" is omitted,
828 remember that it will default to a decimal number, which will
829 be appended to the prefix.
830 According to the Adobe/ISO PDF specification, a prefix of
832 'Content' has a special meaning, in that any /S counter is
833 ignored and only that text is used. However, this appears to
834 be ignored (use a style of nocounter to suppress the counter).
835 Example:
837 # Start with lowercase Roman Numerals at the 1st page, starting with i (1)
839 $pdf->page_labels(0,
840 'style' => 'roman',
841 );
842 # Switch to Arabic (decimal) at the 5th page, starting with 1
844 $pdf->page_labels(4,
845 'style' => 'decimal',
846 );
847 # invalid style at the 25th page, should just continue
849 # with decimal at the current counter
850 $pdf->page_labels(24,
851 'style' => 'raman_noodles', # fail over to decimal
852 # note that PDF::API2 will see the 'r' and treat it as 'roman'
853 'start' => 21, # necessary, otherwise would restart at 1
854 );
855 # No page label at the 31st and 32nd pages. Note that this could be
857 # confusing to the person viewing the PDF, but may be appropriate if
858 # the page itself has no numbering.
859 $pdf->page_labels(30,
860 'style' => 'nocounter',
861 );
862 # Numbering for Appendix A at the 33rd page, A-1, A-2,...
864 $pdf->page_labels(32,
865 'start' => 1, # unnecessary
866 'prefix' => 'A-'
867 );
868 # Numbering for Appendix B at the 37th page, B-1, B-2,...
870 $pdf->page_labels( 36,
871 'prefix' => 'B-'
872 );
873 # Numbering for the Index at the 41st page, Index I, Index II,...
875 $pdf->page_labels(40,
876 'style' => 'Roman',
877 'start' => 1, # unnecessary
878 'prefix' => 'Index ' # note trailing space
879 );
880 # Unnumbered 'Index' at the 45th page, Index, Index,...
882 $pdf->page_labels(40,
883 'style' => 'nocounter',
884 'prefix' => 'Index '
885 );
886 Alternate name: "pageLabel"
888 This old method name is retained for compatibility with old user
890 code. Note that with "pageLabel", you need to make the "options"
891 list an anonymous hash by placing { } around the entire list, even
892 if it has only one item in it.
893 $pdf->userunit($value)
895 Sets the global UserUnit, defining the scale factor to multiply any
896 size or coordinate by. For example, userunit(72) results in a User
897 Unit of 72 points, or 1 inch.
898 See "User Units" in PDF::Builder::Docs for more information.
900 $pdf->mediabox($name)
902 $pdf->mediabox($name, 'orient' => 'orientation')
903 $pdf->mediabox($w,$h)
904 $pdf->mediabox($llx,$lly, $urx,$ury)
905 ($llx,$lly, $urx,$ury) = $pdf->mediabox()
906 Sets (or gets) the global MediaBox, defining the width and height
907 (or by corner coordinates, or by standard name) of the output page
908 itself, such as the physical paper size.
909 See "Media Box" in PDF::Builder::Docs for more information. The
911 method always returns the current bounds (after any set operation).
912 $pdf->cropbox($name)
914 $pdf->cropbox($name, 'orient' => 'orientation')
915 $pdf->cropbox($w,$h)
916 $pdf->cropbox($llx,$lly, $urx,$ury)
917 ($llx,$lly, $urx,$ury) = $pdf->cropbox()
918 Sets (or gets) the global CropBox. This will define the media size
919 to which the output will later be clipped.
920 See "Crop Box" in PDF::Builder::Docs for more information. The
922 method always returns the current bounds (after any set operation).
923 $pdf->bleedbox($name)
925 $pdf->bleedbox($name, 'orient' => 'orientation')
926 $pdf->bleedbox($w,$h)
927 $pdf->bleedbox($llx,$lly, $urx,$ury)
928 ($llx,$lly, $urx,$ury) = $pdf->bleedbox()
929 Sets (or gets) the global BleedBox. This is typically used for hard
930 copy printing where you want ink to go to the edge of the cut
931 paper.
932 See "Bleed Box" in PDF::Builder::Docs for more information. The
934 method always returns the current bounds (after any set operation).
935 $pdf->trimbox($name)
937 $pdf->trimbox($name, 'orient' => 'orientation')
938 $pdf->trimbox($w,$h)
939 $pdf->trimbox($llx,$lly, $urx,$ury)
940 ($llx,$lly, $urx,$ury) = $pdf->trimbox()
941 Sets (or gets) the global TrimBox. This is supposed to be the
942 actual dimensions of the finished page (after trimming of the
943 paper).
944 See "Trim Box" in PDF::Builder::Docs for more information. The
946 method always returns the current bounds (after any set operation).
947 $pdf->artbox($name)
949 $pdf->artbox($name, 'orient' => 'orientation')
950 $pdf->artbox($w,$h)
951 $pdf->artbox($llx,$lly, $urx,$ury)
952 ($llx,$lly, $urx,$ury) = $pdf->artbox()
953 Sets (or gets) the global ArtBox. This is supposed to define "the
954 extent of the page's meaningful content".
955 See "Art Box" in PDF::Builder::Docs for more information. The
957 method always returns the current bounds (after any set operation).
958
960 $font = $pdf->corefont($fontname, %opts)
961 Returns a new Adobe core font object. For details, see "Core Fonts"
962 in PDF::Builder::Docs. Note that this is an Adobe-standard corefont
963 name, and not a file name.
964 See also PDF::Builder::Resource::Font::CoreFont.
966 $font = $pdf->psfont($ps_file, %opts)
968 Returns a new Adobe Type1 ("PostScript") font object. For details,
969 see "PS Fonts" in PDF::Builder::Docs.
970 See also PDF::Builder::Resource::Font::Postscript.
972 $font = $pdf->ttfont($ttf_file, %opts)
974 Returns a new TrueType (or OpenType) font object. For details, see
975 "TrueType Fonts" in PDF::Builder::Docs.
976 $font = $pdf->bdfont($bdf_file, @opts)
978 Returns a new BDF (bitmapped distribution format) font object,
979 based on the specified Adobe BDF file.
980 See also PDF::Builder::Resource::Font::BdFont
982 $font = $pdf->cjkfont($cjkname, %opts)
984 Returns a new CJK font object. These are TrueType-like fonts for
985 East Asian languages (Chinese, Japanese, Korean). For details, see
986 "CJK Fonts" in PDF::Builder::Docs.
987 NOTE: "cjkfont" is quite old and is not well supported. We
989 recommend that you try using "ttfont" (or another font routine, if
990 not TTF/OTF) with the appropriate CJK font file. Most appear to be
991 .ttf or .otf format. PDFs created using "cjkfont" may not be fully
992 portable, and support for "cjkfont" may be dropped in a future
993 release. We would appreciate hearing from you if you are
994 successfully using "cjkfont", and are unable to use "ttfont"
995 instead.
996 Among other things, "cjkfont" selections are limited, as they
998 require CMAP files; they may or may not subset correctly; and they
999 can not be used as the base for synthetic fonts.
1000 See also PDF::Builder::Resource::CIDFont::CJKFont
1002 $font = $pdf->font($name, %opts)
1004 A convenience function to add a font to the PDF without having to
1005 specify the format. Returns the font object, to be used by
1006 PDF::Builder::Content.
1007 The font $name is either the name of one of the standard 14 fonts
1009 ("STANDARD FONTS" in PDF::Builder::Resource::Font::CoreFont), such
1010 as Helvetica or the path to a font file. There are 15 additional
1011 core fonts on a Windows system. Note that the exact name of a core
1012 font needs to be given. The file extension (if path given)
1013 determines what type of font file it is.
1014 my $pdf = PDF::Builder->new();
1016 my $font1 = $pdf->font('Helvetica-Bold');
1017 my $font2 = $pdf->font('/path/to/ComicSans.ttf');
1018 my $page = $pdf->page();
1019 my $content = $page->text();
1020 $content->position(1 * 72, 9 * 72);
1022 $content->font($font1, 24);
1023 $content->text('Hello, World!');
1024 $content->position(0, -36);
1026 $content->font($font2, 12);
1027 $content->text('This is some sample text.');
1028 $pdf->saveas('sample.pdf');
1030 The path can be omitted if the font file is in the current
1032 directory or one of the directories returned by "font_path".
1033 TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe
1035 Glyph Bitmap Distribution Format (bdf) fonts are supported.
1036 The following options (%opts) are available:
1038 format
1040 The font format is normally detected automatically based on the
1041 file's extension. If you're using a font with an atypical
1042 extension, you can set "format" to one of "truetype" (TrueType
1043 or OpenType), "type1" (PostScript Type 1), or "bitmap" (Adobe
1044 Bitmap).
1045 dokern
1047 Kerning (automatic adjustment of space between pairs of
1048 characters) is enabled by default if the font includes this
1049 information. Set this option to false to disable.
1050 afm_file (PostScript Type 1 fonts only)
1052 Specifies the location of the font metrics file.
1053 pfm_file (PostScript Type 1 fonts only)
1055 Specifies the location of the printer font metrics file. This
1056 option overrides the encode option.
1057 embed (TrueType fonts only)
1059 Fonts are embedded in the PDF by default, which is required to
1060 ensure that they can be viewed properly on a device that
1061 doesn't have the font installed. Set this option to false to
1062 prevent the font from being embedded.
1063 @directories = PDF::Builder->font_path()
1065 Return the list of directories that will be searched (in order) in
1066 addition to the current directory when you add a font to a PDF
1067 without including the full path to the font file.
1068 @directories = PDF::Builder::add_to_font_path('/my/fonts',
1070 '/path/to/fonts', ...)
1071 Adds one or more directories to the list of paths to be searched
1072 for font files.
1073 Returns the font search path.
1075 Alternate name: "addFontDirs"
1077 Prior to recent changes to PDF::API2, this method was
1079 addFontDirs(). This method is still available, but may be
1080 deprecated some time in the future.
1081 @directories = PDF::Builder->set_font_path('/my/fonts',
1083 '/path/to/fonts');
1084 Replace the existing font search path. This should only be
1085 necessary if you need to remove a directory from the path for some
1086 reason, or if you need to reorder the list.
1087 Returns the font search path.
1089 $font = $pdf->synfont($basefont, %opts)
1091 Returns a new synthetic font object. These are modifications to a
1092 core (or PS/T1 or TTF/OTF) font, where the font may be replaced by
1093 a Type1 or Type3 PostScript font. This does not appear to work
1094 with CJK fonts (created with "cjkfont" method). For details, see
1095 "Synthetic Fonts" in PDF::Builder::Docs.
1096 See also PDF::Builder::Resource::Font::SynFont
1098 Alternate name: "synthetic_font"
1100 Prior to recent PDF::API2 changes, the routine to create modified
1102 fonts was "synfont". PDF::API2 has renamed it to "synthetic_font",
1103 which I don't like, but to maintain compatibility, "synthetic_font"
1104 is available as an alias.
1105 There are also some minor option differences (incompatibilities)
1107 discussed in "SynFont", including the value of 'bold' between the
1108 two entry points.
1109 $font = $pdf->unifont(@fontspecs, %opts)
1111 Returns a new uni-font object, based on the specified fonts and
1112 options.
1113 BEWARE: This is not a true PDF-object, but a virtual/abstract font
1115 definition!
1116 See also PDF::Builder::Resource::UniFont.
1118 Valid options (%opts) are:
1120 encode
1122 Changes the encoding of the font from its default.
1123 Font Manager methods
1125 The Font Manager is automatically initialized.
1126 @list = $pdf->font_settings() # Get
1128 $pdf->font_settings(%info) # Set
1129 Change one or more default settings. See
1130 PDF::Builder::FontManager/font_settings for details.
1131 $rc = $pdf->add_font_path("a directory path", %opts)
1133 Add a search path for Font Manager font entries. See
1134 PDF::Builder::FontManager/add_font_path for details.
1135 $rc = $pdf->add_font(%info)
1137 Add a font (face) definition to the Font Manager list. See
1138 PDF::Builder::FontManager/add_font for details.
1139 @current = $pdf->get_font() # Get
1141 $font = $pdf->get_font(%info) # Set
1142 Retrieve a ready-to-use font, or find out what the current one is.
1143 See PDF::Builder::FontManager/get_font for details.
1144 $pdf->dump_font_tables()
1146 Dump all known font information to STDOUT. See
1147 PDF::Builder::FontManager/dump_font_tables for details.
1148
1150 $object = $pdf->image($file, %opts);
1151 A convenience function to attempt to determine the image type, and
1152 import a file of that type and return an object that can be placed
1153 as part of a page's content:
1154 my $pdf = PDF::Builder->new();
1156 my $page = $pdf->page();
1157 my $image = $pdf->image('/path/to/image.jpg');
1159 $page->object($image, 100, 100);
1160 $pdf->save('sample.pdf');
1162 $file may be either a file name, a filehandle, or a
1164 PDF::Builder::Resource::XObject::Image::GD object.
1165 Caution: Do not confuse this "image" ($pdf->) with the image method
1167 found in the graphics (gfx) class ($gfx->), used to actually place
1168 a read-in or decoded image on the page!
1169 See "image" in PDF::Builder::Content for details about placing
1171 images on a page once they're imported.
1172 The image format is normally detected automatically based on the
1174 file's extension (.gif, .png, .tif/.tiff, .jpg/.jpeg,
1175 .pnm/.pbm/.pgm/.ppm). If passed a filehandle, image formats GIF,
1176 JPEG, PNM, and PNG will be detected based on the file's header.
1177 Unfortunately, at this time, other image formats (TIFF and GD)
1178 cannot be automatically detected. (TIFF could be, except that
1179 image_tiff() cannot use a filehandle anyway as input when using the
1180 libtiff library, which is highly recommended.)
1181 If the file has an atypical extension or the filehandle is for a
1183 different kind of image, you can set the "format" option to one of
1184 the supported types: "gif", "jpeg", "png", "pnm", or "tiff".
1185 Note: PNG images that include an alpha (transparency) channel go
1187 through a relatively slow process of splitting the image into
1188 separate RGB and alpha components as is required by images in PDFs.
1189 If you're having performance issues, install Image::PNG::Libpng to
1190 speed this process up by an order of magnitude; either module will
1191 be used automatically if available. See the "image_png" method for
1192 details.
1193 Note: TIFF image processing is very slow if using the pure Perl
1195 decoder. We highly recommend using the Graphics::TIFF library to
1196 improve performance. See the "image_tiff" method for details.
1197 $jpeg = $pdf->image_jpeg($file, %opts)
1199 Imports and returns a new JPEG image object. $file may be either a
1200 filename or a filehandle.
1201 See PDF::Builder::Resource::XObject::Image::JPEG for additional
1203 information and "examples/Content.pl" for some examples of placing
1204 an image on a page.
1205 $tiff = $pdf->image_tiff($file, %opts)
1207 Imports and returns a new TIFF image object. $file may be either a
1208 filename or a filehandle. For details, see "TIFF Images" in
1209 PDF::Builder::Docs.
1210 See PDF::Builder::Resource::XObject::Image::TIFF and
1212 PDF::Builder::Resource::XObject::Image::TIFF_GT for additional
1213 information and "examples/Content.pl" for some examples of placing
1214 an image on a page (JPEG, but the principle is the same). There is
1215 an optional TIFF library (TIFF_GT) described, that gives more
1216 capability than the default one. However, note that $file can only
1217 be a filename when using this library.
1218 $rc = $pdf->LA_GT()
1220 Returns 1 if the library name (package) Graphics::TIFF is
1221 installed, and 0 otherwise. For this optional library, this call
1222 can be used to know if it is safe to use certain functions. For
1223 example:
1224 if ($pdf->LA_GT() {
1226 # is installed and usable
1227 } else {
1228 # not available. you will be running the old, pure PERL code
1229 }
1230 $pnm = $pdf->image_pnm($file, %opts)
1232 Imports and returns a new PNM image object. $file may be either a
1233 filename or a filehandle.
1234 See PDF::Builder::Resource::XObject::Image::PNM for additional
1236 information and "examples/Content.pl" for some examples of placing
1237 an image on a page (JPEG, but the principle is the same).
1238 $png = $pdf->image_png($file, %opts)
1240 Imports and returns a new PNG image object. $file may be either a
1241 filename or a filehandle. For details, see "PNG Images" in
1242 PDF::Builder::Docs.
1243 See PDF::Builder::Resource::XObject::Image::PNG and
1245 PDF::Builder::Resource::XObject::Image::PNG_IPL for additional
1246 information and "examples/Content.pl" for some examples of placing
1247 an image on a page (JPEG, but the principle is the same).
1248 There is an optional PNG library (PNG_IPL) described, that gives
1250 more capability than the default one. However, note that $file can
1251 only be a filename when using this library.
1252 $rc = $pdf->LA_IPL()
1254 Returns 1 if the library name (package) Image::PNG::Libpng is
1255 installed, and 0 otherwise. For this optional library, this call
1256 can be used to know if it is safe to use certain functions. For
1257 example:
1258 if ($pdf->LA_IPL() {
1260 # is installed and usable
1261 } else {
1262 # not available. don't use 16bps or interlaced PNG image files
1263 }
1264 $gif = $pdf->image_gif($file, %opts)
1266 Imports and returns a new GIF image object. $file may be either a
1267 filename or a filehandle.
1268 See PDF::Builder::Resource::XObject::Image::GIF for additional
1270 information and "examples/Content.pl" for some examples of placing
1271 an image on a page (JPEG, but the principle is the same).
1272 $gdf = $pdf->image_gd($gd_object, %opts)
1274 Imports and returns a new image object from Image::GD.
1275 See PDF::Builder::Resource::XObject::Image::GD for additional
1277 information and "examples/Content.pl" for some examples of placing
1278 an image on a page (JPEG, but the principle is the same).
1279
1281 $colorspace = $pdf->colorspace($type, @arguments)
1282 Colorspaces can be added to a PDF to either specifically control
1283 the output color on a particular device (spot colors, device
1284 colors) or to save space by limiting the available colors to a
1285 defined color palette (web-safe palette, ACT file).
1286 Once added to the PDF, they can be used in place of regular hex
1288 codes or named colors:
1289 my $pdf = PDF::Builder->new();
1291 my $page = $pdf->page();
1292 my $content = $page->graphics();
1293 # Add colorspaces for a spot color and the web-safe color palette
1295 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
1296 my $web = $pdf->colorspace('web');
1297 # Fill using the spot color with 100% coverage
1299 $content->fill_color($spot, 1.0);
1300 # Stroke using the first color of the web-safe palette
1302 $content->stroke_color($web, 0);
1303 # Add a rectangle to the page
1305 $content->rectangle(100, 100, 200, 200);
1306 $content->paint();
1307 $pdf->save('sample.pdf');
1309 The following types of colorspaces are supported
1311 spot
1313 my $spot = $pdf->colorspace('spot', $tint, $alt_color);
1314 Spot colors are used to instruct a device (usually a printer)
1316 to use or emulate a particular ink color ($tint) for parts of
1317 the document. An $alt_color is provided for devices (e.g. PDF
1318 viewers) that don't know how to produce the named color. It can
1319 either be an approximation of the color in RGB, CMYK, or HSV
1320 formats, or a wildly different color (e.g. 100% magenta, %0F00)
1321 to make it clear if the spot color isn't being used as
1322 expected.
1323 web
1325 my $web = $pdf->colorspace('web');
1326 The web-safe color palette is a historical collection of colors
1328 that was used when many display devices only supported 256
1329 colors.
1330 act
1332 my $act = $pdf->colorspace('act', $filename);
1333 An Adobe Color Table (ACT) file provides a custom palette of
1335 colors that can be referenced by PDF graphics and text drawing
1336 commands.
1337 device
1339 my $devicen = $pdf->colorspace('device', @colorspaces);
1340 A device-specific colorspace allows for precise color output on
1342 a given device (typically a printing press), bypassing the
1343 normal color interpretation performed by raster image
1344 processors (RIPs).
1345 Device colorspaces are also needed if you want to blend spot
1347 colors:
1348 my $pdf = PDF::Builder->new();
1350 my $page = $pdf->page();
1351 my $content = $page->graphics();
1352 # Create a two-color device colorspace
1354 my $yellow = $pdf->colorspace('spot', 'Yellow', '%00F0');
1355 my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
1356 my $device = $pdf->colorspace('device', $yellow, $spot);
1357 # Fill using a blend of 25% yellow and 75% spot color
1359 $content->fill_color($device, 0.25, 0.75);
1360 # Stroke using 100% spot color
1362 $content->stroke_color($device, 0, 1);
1363 # Add a rectangle to the page
1365 $content->rectangle(100, 100, 200, 200);
1366 $content->paint();
1367 $pdf->save('sample.pdf');
1369 $cs = $pdf->colorspace_act($file)
1371 Returns a new colorspace object based on an Adobe Color Table file.
1372 See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a
1374 reference to the file format's specification.
1375 $cs = $pdf->colorspace_web()
1377 Returns a new colorspace-object based on the "web-safe" color
1378 palette.
1379 $cs = $pdf->colorspace_hue()
1381 Returns a new colorspace-object based on the hue color palette.
1382 See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an
1384 explanation.
1385 $cs = $pdf->colorspace_separation($tint, $color)
1387 Returns a new separation colorspace object based on the parameters.
1388 $tint can be any valid ink identifier, including but not limited
1390 to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
1391 'Orange'.
1392 $color must be a valid color specification limited to: '#rrggbb',
1394 '!hhssvv', '%ccmmyykk' or a "named color" (rgb).
1395 The colorspace model will automatically be chosen based on the
1397 specified color.
1398 $cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
1400 $cs = $pdf->colorspace_devicen(\@tintCSx)
1401 Returns a new DeviceN colorspace object based on the parameters.
1402 Example:
1404 $cy = $pdf->colorspace_separation('Cyan', '%f000');
1406 $ma = $pdf->colorspace_separation('Magenta', '%0f00');
1407 $ye = $pdf->colorspace_separation('Yellow', '%00f0');
1408 $bk = $pdf->colorspace_separation('Black', '%000f');
1409 $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
1411 $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
1413 The colorspace model will automatically be chosen based on the
1415 first colorspace specified.
1416
1418 These are glue routines to the actual barcode rendering routines
1419 found elsewhere.
1420 $bc = $pdf->xo_codabar(%opts)
1422 $bc = $pdf->xo_code128(%opts)
1423 $bc = $pdf->xo_2of5int(%opts)
1424 $bc = $pdf->xo_3of9(%opts)
1425 $bc = $pdf->xo_ean13(%opts)
1426 Creates the specified barcode object as a form XObject.
1427
1429 $xo = $pdf->xo_form()
1430 Returns a new form XObject.
1431 $egs = $pdf->egstate()
1433 Returns a new extended graphics state object, as described in
1434 PDF::Builder::Resource::ExtGState.
1435 $obj = $pdf->pattern(%opts)
1437 Returns a new pattern object.
1438 $obj = $pdf->shading(%opts)
1440 Returns a new shading object.
1441 $ndest = $pdf->named_destination()
1443 Returns a new or existing named destination object.
1444perl v5.36.0 2023-01-23 PDF::Builder(3)