1PDF::Create(3) User Contributed Perl Documentation PDF::Create(3)
2
6 PDF::Create - Create PDF files.
7
9 Version 1.43
10
12 "PDF::Create" allows you to create PDF document using a number of
13 primitives.The result is as a PDF file or stream. PDF stands for
14 Portable Document Format.
15 Documents can have several pages, a table of content, an information
17 section and many other PDF elements.
18
20 "PDF::Create" provides an easy module to create PDF output from your
21 perl script. It is designed to be easy to use and simple to install
22 and maintain. It provides a couple of subroutines to handle text,
23 fonts, images and drawing primitives. Simple documents are easy to
24 create with the supplied routines.
25 In addition to be reasonable simple "PDF::Create" is written in pure
27 Perl and has no external dependencies (libraries, other modules,
28 etc.). It should run on any platform where perl is available.
29 For complex stuff some understanding of the underlying Postscript/PDF
31 format is necessary. In this case it might be better go with the more
32 complete PDF::API2 modules to gain more features at the expense of a
33 steeper learning curve.
34 Example PDF creation with "PDF::Create" (see PDF::Create::Page for
36 details of methods available on a page):
37 use strict; use warnings;
39 use PDF::Create;
40 my $pdf = PDF::Create->new(
42 'filename' => 'sample.pdf',
43 'Author' => 'John Doe',
44 'Title' => 'Sample PDF',
45 'CreationDate' => [ localtime ]
46 );
47 # Add a A4 sized page
49 my $root = $pdf->new_page('MediaBox' => $pdf->get_page_size('A4'));
50 # Add a page which inherits its attributes from $root
52 my $page1 = $root->new_page;
53 # Prepare a font
55 my $font = $pdf->font('BaseFont' => 'Helvetica');
56 # Prepare a Table of Content
58 my $toc = $pdf->new_outline('Title' => 'Title Page', 'Destination' => $page1);
59 # Write some text
61 $page1->stringc($font, 40, 306, 426, 'PDF::Create');
62 $page1->stringc($font, 20, 306, 396, "version $PDF::Create::VERSION");
63 $page1->stringc($font, 20, 306, 300, 'by John Doe <john.doe@example.com>');
64 # Add another page
66 my $page2 = $root->new_page;
67 # Draw some lines
69 $page2->line(0, 0, 592, 840);
70 $page2->line(0, 840, 592, 0);
71 $toc->new_outline('Title' => 'Second Page', 'Destination' => $page2);
73 # Close the file and write the PDF
75 $pdf->close;
76
78 The method "new(%params)" create a new pdf structure for your PDF. It
79 returns an object handle which can be used to add more stuff to the
80 PDF. The parameter keys to the constructor are detailed as below:
81 +--------------+------------------------------------------------------------+
83 | Key | Description |
84 +--------------+------------------------------------------------------------+
85 | | |
86 | filename | Destination file that will contain resulting PDF or '-' for|
87 | | stdout. If neither filename or fh are specified, the |
88 | | content will be stored in memory and returned when calling |
89 | | close(). |
90 | | |
91 | fh | Already opened filehandle that will contain resulting PDF. |
92 | | See comment above regarding close(). |
93 | | |
94 | Version | PDF Version to claim, can be 1.0 to 1.3 (default: 1. |
95 | | |
96 | PageMode | How the document should appear when opened.Possible values |
97 | | UseNone (Default), UseOutlines, UseThumbs and FullScreen |
98 | | |
99 | Author | The name of the person who created this document. |
100 | | |
101 | Creator | If the document was converted into a PDF document from |
102 | | another form, this is the name of the application that |
103 | | created the document. |
104 | | |
105 | Title | The title of the document. |
106 | | |
107 | Subject | The subject of the document. |
108 | | |
109 | Keywords | Keywords associated with the document. |
110 | | |
111 | CreationDate | The date the document was created.This is passed as an |
112 | | anonymous array in the same format as localtime returns. |
113 | | |
114 | Debug | The debug level, defaults to 0. It can be any positive |
115 | | integers. |
116 | | |
117 +--------------+------------------------------------------------------------+
118 Example:
120 my $pdf = PDF::Create->new(
122 'filename' => 'sample.pdf',
123 'Version' => 1.2,
124 'PageMode' => 'UseOutlines',
125 'Author' => 'John Doe',
126 'Title' => 'My Title',
127 'CreationDate' => [ localtime ]
128 );
129 If you are writing a CGI you can send your PDF on the fly to stdout /
131 directly to the browser using '-' as filename.
132 CGI Example:
134 use CGI;
136 use PDF::Create;
137 print CGI::header(-type => 'application/x-pdf', -attachment => 'sample.pdf');
139 my $pdf = PDF::Create->new(
140 'filename' => '-',
141 'Author' => 'John Doe',
142 'Title' => 'My title',
143 'CreationDate' => [ localtime ]
144 );
145
147 new_page(%params)
148 Add a page to the document using the given parameters. "new_page" must
149 be called first to initialize a root page, used as model for further
150 pages.Returns a handle to the newly created page. Parameters can be:
151 +-----------+---------------------------------------------------------------+
153 | Key | Description |
154 +-----------+---------------------------------------------------------------+
155 | | |
156 | Parent | The parent of this page in the pages tree.This is page object.|
157 | | |
158 | Resources | Resources required by this page. |
159 | | |
160 | MediaBox | Rectangle specifying the natural size of the page,for example |
161 | | the dimensions of an A4 sheet of paper. The coordinates are |
162 | | measured in default user space units It must be the reference |
163 | | of 4 values array.You can use C<get_page_size> to get to get |
164 | | the size of standard paper sizes.C<get_page_size> knows about |
165 | | A0-A6, A4L (landscape), Letter, Legal, Broadsheet, Ledger, |
166 | | Tabloid, Executive and 36x36. |
167 | CropBox | Rectangle specifying the default clipping region for the page |
168 | | when displayed or printed. The default is the value of the |
169 | | MediaBox. |
170 | | |
171 | ArtBox | Rectangle specifying an area of the page to be used when |
172 | | placing PDF content into another application. The default is |
173 | | the value of the CropBox. [PDF 1.3] |
174 | | |
175 | TrimBox | Rectangle specifying the intended finished size of the page |
176 | | (for example, the dimensions of an A4 sheet of paper).In some |
177 | | cases,the MediaBox will be a larger rectangle, which includes |
178 | | printing instructions, cut marks or other content.The default |
179 | | is the value of the CropBox. [PDF 1.3]. |
180 | | |
181 | BleedBox | Rectangle specifying the region to which all page content |
182 | | should be clipped if the page is being output in a production |
183 | | environment. In such environments, a bleed area is desired, |
184 | | to accommodate physical limitations of cutting, folding, and |
185 | | trimming equipment. The actual printed page may include |
186 | | printer's marks that fall outside the bleed box. The default |
187 | | is the value of the CropBox.[PDF 1.3] |
188 | | |
189 | Rotate | Specifies the number of degrees the page should be rotated |
190 | | clockwise when it is displayed or printed. This value must be |
191 | | zero (the default) or a multiple of 90. The entire page, |
192 | | including contents is rotated. |
193 | | |
194 +-----------+---------------------------------------------------------------+
195 Example:
197 my $a4 = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );
199 my $page1 = $a4->new_page;
201 $page1->string($f1, 20, 306, 396, "some text on page 1");
202 my $page2 = $a4->new_page;
204 $page2->string($f1, 20, 306, 396, "some text on page 2");
205 font(%params)
207 Prepare a font using the given arguments. This font will be added to
208 the document only if it is used at least once before the close method
209 is called.Parameters are listed below:
210 +----------+----------------------------------------------------------------+
212 | Key | Description |
213 +----------+----------------------------------------------------------------+
214 | Subtype | Type of font. PDF defines some types of fonts. It must be one |
215 | | of the predefined type Type1, Type3, TrueType or Type0.In this |
216 | | version, only Type1 is supported. This is the default value. |
217 | | |
218 | Encoding | Specifies the encoding from which the new encoding differs. |
219 | | It must be one of the predefined encodings MacRomanEncoding, |
220 | | MacExpertEncoding or WinAnsiEncoding. In this version, only |
221 | | WinAnsiEncoding is supported. This is the default value. |
222 | | |
223 | BaseFont | The PostScript name of the font. It can be one of the following|
224 | | base fonts: Courier, Courier-Bold, Courier-BoldOblique, |
225 | | Courier-Oblique, Helvetica, Helvetica-Bold, |
226 | | Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman, |
227 | | Times-Bold, Times-Italic, Times-BoldItalic or Symbol. |
228 +----------+----------------------------------------------------------------+
229 The ZapfDingbats font is not supported in this version.Default font is
231 Helvetica.
232 my $f1 = $pdf->font('BaseFont' => 'Helvetica');
234 new_outline(%params)
236 Adds an outline to the document using the given parameters. Return
237 the newly created outline. Parameters can be:
238 +-------------+-------------------------------------------------------------+
240 | Key | Description |
241 +-------------+-------------------------------------------------------------+
242 | | |
243 | Title | The title of the outline. Mandatory. |
244 | | |
245 | Destination | The Destination of this outline item. In this version,it is |
246 | | only possible to give a page as destination. The default |
247 | | destination is the current page. |
248 | | |
249 | Parent | The parent of this outline in the outlines tree. This is an |
250 | | outline object. This way you represent the tree of your |
251 | | outlines. |
252 | | |
253 +-------------+-------------------------------------------------------------+
254 Example:
256 my $outline = $pdf->new_outline('Title' => 'Item 1');
258 $pdf->new_outline('Title' => 'Item 1.1', 'Parent' => $outline);
259 $pdf->new_outline('Title' => 'Item 1.2', 'Parent' => $outline);
260 $pdf->new_outline('Title' => 'Item 2');
261 get_page_size($name)
263 Returns the size of standard paper used for MediaBox-parameter of
264 "new_page". "get_page_size" has one optional parameter to specify
265 the paper name. Possible values are a0-a6,
266 a4l,letter,broadsheet,ledger,tabloid,legal,executive and 36x36.
267 Default is a4.
268 my $root = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );
270 version($number)
272 Set and return version number. Valid version numbers are 1.0, 1.1, 1.2
273 and 1.3.
274 close(%params)
276 Close does the work of creating the PDF data from the objects collected
277 before. You must call "close()" after you have added all the contents
278 as most of the real work building the PDF is performed there. If omit
279 calling close you get no PDF output. Returns the raw content of the
280 PDF. If "fh" was provided when creating object of "PDF::Create" then
281 it does not try to close the file handle. It is, therefore, advised you
282 call "flush()" rather than "close()".
283 flush()
285 Generate the PDF content and returns the raw content as it is.
286 reserve($name, $type)
288 Reserve the next object number for the given object type.
289 add_comment($message)
291 Add comment to the document.The string will show up in the PDF as
292 postscript-style comment:
293 % this is a postscript comment
295 annotation(%params)
297 Adds an annotation object, for the time being we only do the 'Link' -
298 'URI' kind This is a sensitive area in the PDF document where text
299 annotations are shown or links launched. "PDF::Create" only supports
300 URI links at this time.
301 URI links have two components,the text or graphics object and the area
303 where the mouseclick should occur.
304 For the object to be clicked on you'll use standard text of drawing
306 methods. To define the click-sensitive area and the destination URI.
307 Example:
309 # Draw a string and undeline it to show it is a link
311 $pdf->string($f1, 10, 450, 200, 'http://www.cpan.org');
312 my $line = $pdf->string_underline($f1, 10, 450, 200, 'http://www.cpan.org');
314 # Create the hot area with the link to open on click
316 $pdf->annotation(
317 Subtype => 'Link',
318 URI => 'http://www.cpan.org',
319 x => 450,
320 y => 200,
321 w => $l,
322 h => 15,
323 Border => [0,0,0]
324 );
325 The point (x, y) is the bottom left corner of the rectangle
327 containing hotspot rectangle, (w, h) are the width and height of the
328 hotspot rectangle. The Border describes the thickness of the border
329 surrounding the rectangle hotspot.
330 The function "string_undeline" returns the width of the string, this
332 can be used directly for the width of the hotspot rectangle.
333 image($filename)
335 Prepare an XObject (image) using the given arguments. This image will
336 be added to the document if it is referenced at least once before the
337 close method is called. In this version GIF,interlaced GIF and JPEG is
338 supported. Usage of interlaced GIFs are slower because they are
339 decompressed, modified and compressed again. The gif support is
340 limited to images with a LZW minimum code size of 8. Small images with
341 few colors can have a smaller minimum code size and will not work. If
342 you get errors regarding JPEG compression, then the compression method
343 used in your JPEG file is not supported by "PDF::Image::JPEG". Try
344 resaving the JPEG file with different compression options (for example,
345 disable progressive compression).
346 Example:
348 my $img = $pdf->image('image.jpg');
350 $page->image(
352 image => $img,
353 xscale => 0.25, # scale image for better quality
354 yscale => 0.25,
355 xpos => 50,
356 ypos => 60,
357 xalign => 0,
358 yalign => 2,
359 );
360 get_data()
362 If you did not ask the $pdf object to write its output to a file, you
363 can pick up the pdf code by calling this method. It returns a big
364 string. You need to call "close" first.
365
367 "PDF::Create" comes with a couple of limitations or known caveats:
368 PDF Size / Memory
370 Unless using a filehandle, "PDF::Create" assembles the entire PDF in
371 memory. If you create very large documents on a machine with a small
372 amount of memory your program can fail because it runs out of memory.
373 If using a filehandle, data will be written immediately to the
374 filehandle after each method.
375 Small GIF images
377 Some gif images get created with a minimal lzw code size of less than
378 8. "PDF::Create" can not decode those and they must be converted.
379
381 I support "PDF::Create" in my spare time between work and family, so
382 the amount of work I put in is limited.
383 If you experience a problem make sure you are at the latest version
385 first many of things have already been fixed.
386 Please register bug at the CPAN bug tracking system at
388 <http://rt.cpan.org> or send email to "bug-PDF-Create [at] rt.cpan.org"
389 Be sure to include the following information:
391 - PDF::Create Version you are running
393 - Perl version (perl -v)
394 - Operating System vendor and version
395 - Details about your operating environment that might be related to the
396 issue being described
397 - Exact cut and pasted error or warning messages
398 - The shortest, clearest code you can manage to write which
399 reproduces the bug described.
400 I appreciate patches against the latest released version of
402 "PDF::Create" which fix the bug.
403 Feature request can be submitted like bugs. If you provide patch for a
405 feature which does not go against the "PDF::Create" philosophy (keep it
406 simple) then you have a good chance for it to be accepted.
407
409 Adobe PDF <http://www.adobe.com/devnet/pdf/pdf_reference.html>
410 PDF::Labels Routines to produce formatted pages of mailing labels in
412 PDF, uses PDF::Create internally.
413 PDF::Haru Perl interface to Haru Free PDF Library.
415 PDF::EasyPDF PDF creation from a one-file module, similar to
417 PDF::Create.
418 PDF::CreateSimple Yet another PDF creation module
420 PDF::Report A wrapper written for PDF::API2.
422
424 Fabien Tassin
425 GIF and JPEG-support: Michael Gross (info@mdgrosse.net)
427 Maintenance since 2007: Markus Baertschi (markus@markus.org)
429 Currently maintained by Mohammad S Anwar (MANWAR) "<mohammad.anwar at
431 yahoo.com>"
432
434 <https://github.com/manwar/pdf-create>
435
437 Copyright 1999-2001,Fabien Tassin.All rights reserved.It may be used
438 and modified freely, but I do request that this copyright notice
439 remain attached to the file. You may modify this module as you
440 wish,but if you redistribute a modified version , please attach a note
441 listing the modifications you have made.
442 Copyright 2007 Markus Baertschi
444 Copyright 2010 Gary Lieberman
446
448 This is free software; you can redistribute it and / or modify it under
449 the same terms as Perl 5.6.0.
450perl v5.28.0 2017-09-23 PDF::Create(3)