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

NAME

6       PDF::Create - Create PDF files.
7

VERSION

9       Version 1.46
10

DESCRIPTION

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
16       Documents can have several pages, a  table of content, an information
17       section and many other PDF elements.
18

SYNOPSIS

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
26       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
30       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
35       Example PDF creation with "PDF::Create" (see PDF::Create::Page for
36       details of methods available on a page):
37
38           use strict; use warnings;
39           use PDF::Create;
40
41           my $pdf = PDF::Create->new(
42               'filename'     => 'sample.pdf',
43               'Author'       => 'John Doe',
44               'Title'        => 'Sample PDF',
45               'CreationDate' => [ localtime ]
46           );
47
48           # Add a A4 sized page
49           my $root = $pdf->new_page('MediaBox' => $pdf->get_page_size('A4'));
50
51           # Add a page which inherits its attributes from $root
52           my $page1 = $root->new_page;
53
54           # Prepare a font
55           my $font = $pdf->font('BaseFont' => 'Helvetica');
56
57           # Prepare a Table of Content
58           my $toc = $pdf->new_outline('Title' => 'Title Page', 'Destination' => $page1);
59
60           # 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
65           # Add another page
66           my $page2 = $root->new_page;
67
68           # Draw some lines
69           $page2->line(0, 0,   592, 840);
70           $page2->line(0, 840, 592, 0);
71
72           $page2->string($font, 20, 50, 400, "default á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
73           $page2->string_underline($font, 20, 50, 400, "default á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
74
75           use utf8;
76           $page2->string($font, 20, 50, 350, "use utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
77           $page2->string_underline($font, 20, 50, 350, "use utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
78
79           no utf8;
80           $page2->string($font, 20, 50, 300, "no utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
81           $page2->string_underline($font, 20, 50, 300, "no utf8 á é í ó ú ñ  Á É Í Ó Ú Ñ ¿ ¡ a e i o u n'");
82
83           $toc->new_outline('Title' => 'Second Page', 'Destination' => $page2);
84
85           # Close the file and write the PDF
86           $pdf->close;
87

CONSTRUCTOR

89       The method "new(%params)" create a new pdf structure for your PDF. It
90       returns an object handle which can be used to add more stuff to the
91       PDF. The  parameter keys to the constructor are detailed as below:
92
93           +--------------+------------------------------------------------------------+
94           | Key          | Description                                                |
95           +--------------+------------------------------------------------------------+
96           |              |                                                            |
97           | filename     | Destination file that will contain resulting PDF or '-' for|
98           |              | stdout. If neither filename or fh are specified, the       |
99           |              | content will be stored in memory and returned when calling |
100           |              | close().                                                   |
101           |              |                                                            |
102           | fh           | Already opened filehandle that will contain resulting PDF. |
103           |              | See comment above regarding close().                       |
104           |              |                                                            |
105           | Version      | PDF Version to claim, can be 1.0 to 1.3 (default: 1.       |
106           |              |                                                            |
107           | PageMode     | How the document should appear when opened.Possible values |
108           |              | UseNone (Default), UseOutlines, UseThumbs and FullScreen   |
109           |              |                                                            |
110           | Author       | The name of the person who created this document.          |
111           |              |                                                            |
112           | Creator      | If the document was converted into a PDF document from     |
113           |              | another form, this is the name of the application that     |
114           |              | created the document.                                      |
115           |              |                                                            |
116           | Title        | The title of the document.                                 |
117           |              |                                                            |
118           | Subject      | The subject of the document.                               |
119           |              |                                                            |
120           | Keywords     | Keywords associated with the document.                     |
121           |              |                                                            |
122           | CreationDate | The date the document was created.This is passed as an     |
123           |              | anonymous array in the same format as localtime returns.   |
124           |              |                                                            |
125           | Debug        | The debug level, defaults to 0. It can be any positive     |
126           |              | integers.                                                  |
127           |              |                                                            |
128           +--------------+------------------------------------------------------------+
129
130       Example:
131
132           my $pdf = PDF::Create->new(
133               'filename'     => 'sample.pdf',
134               'Version'      => 1.2,
135               'PageMode'     => 'UseOutlines',
136               'Author'       => 'John Doe',
137               'Title'        => 'My Title',
138               'CreationDate' => [ localtime ]
139           );
140
141       If you are writing a CGI you can send your PDF on the fly to stdout /
142       directly to the browser using '-' as filename.
143
144       CGI Example:
145
146         use CGI;
147         use PDF::Create;
148
149         print CGI::header(-type => 'application/x-pdf', -attachment => 'sample.pdf');
150         my $pdf = PDF::Create->new(
151             'filename'     => '-',
152             'Author'       => 'John Doe',
153             'Title'        => 'My title',
154             'CreationDate' => [ localtime ]
155         );
156

METHODS

158   new_page(%params)
159       Add a page to the document using the given parameters. "new_page" must
160       be called first to initialize a root page, used as model for further
161       pages.Returns a handle to the newly created page. Parameters can be:
162
163           +-----------+---------------------------------------------------------------+
164           | Key       | Description                                                   |
165           +-----------+---------------------------------------------------------------+
166           |           |                                                               |
167           | Parent    | The parent of this page in the pages tree.This is page object.|
168           |           |                                                               |
169           | Resources | Resources required by this page.                              |
170           |           |                                                               |
171           | MediaBox  | Rectangle specifying the natural size of the page,for example |
172           |           | the dimensions of an A4 sheet of paper. The coordinates are   |
173           |           | measured in default user space units It must be the reference |
174           |           | of 4 values array.You can use C<get_page_size> to get to get  |
175           |           | the size of standard paper sizes.C<get_page_size> knows about |
176           |           | A0-A6, A4L (landscape), Letter, Legal, Broadsheet, Ledger,    |
177           |           | Tabloid, Executive and 36x36.                                 |
178           | CropBox   | Rectangle specifying the default clipping region for the page |
179           |           | when displayed or printed. The default is the value of the    |
180           |           | MediaBox.                                                     |
181           |           |                                                               |
182           | ArtBox    | Rectangle specifying  an area  of the page to be used when    |
183           |           | placing PDF content into another application. The default is  |
184           |           | the value of the CropBox. [PDF 1.3]                           |
185           |           |                                                               |
186           | TrimBox   | Rectangle specifying the  intended finished size of the page  |
187           |           | (for example, the dimensions of an A4 sheet of paper).In some |
188           |           | cases,the MediaBox will be a larger rectangle, which includes |
189           |           | printing instructions, cut marks or other content.The default |
190           |           | is the value of the CropBox. [PDF 1.3].                       |
191           |           |                                                               |
192           | BleedBox  | Rectangle specifying the region to which all page content     |
193           |           | should be clipped if the page is being output in a production |
194           |           | environment. In such environments, a bleed area is desired,   |
195           |           | to accommodate physical limitations of cutting, folding, and  |
196           |           | trimming  equipment. The actual  printed page may  include    |
197           |           | printer's marks that fall outside the bleed box. The default  |
198           |           | is the value of the CropBox.[PDF 1.3]                         |
199           |           |                                                               |
200           | Rotate    | Specifies the number of degrees the page should be rotated    |
201           |           | clockwise when it is displayed or printed. This value must be |
202           |           | zero (the default) or a multiple of 90. The entire page,      |
203           |           | including contents is rotated.                                |
204           |           |                                                               |
205           +-----------+---------------------------------------------------------------+
206
207       Example:
208
209           my $a4 = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );
210
211           my $page1 = $a4->new_page;
212           $page1->string($f1, 20, 306, 396, "some text on page 1");
213
214           my $page2 = $a4->new_page;
215           $page2->string($f1, 20, 306, 396, "some text on page 2");
216
217   font(%params)
218       Prepare a font using the given arguments. This font will be added to
219       the document only if it is used at least once before the close method
220       is called.Parameters are listed below:
221
222           +----------+----------------------------------------------------------------+
223           | Key      | Description                                                    |
224           +----------+----------------------------------------------------------------+
225           | Subtype  | Type of font. PDF defines some types of fonts. It must be one  |
226           |          | of the predefined type Type1, Type3, TrueType or Type0.In this |
227           |          | version, only Type1 is supported. This is the default value.   |
228           |          |                                                                |
229           | Encoding | Specifies the  encoding  from which the new encoding differs.  |
230           |          | It must be one of the predefined encodings MacRomanEncoding,   |
231           |          | MacExpertEncoding or WinAnsiEncoding. In this version, only    |
232           |          | WinAnsiEncoding is supported. This is the default value.       |
233           |          |                                                                |
234           | BaseFont | The PostScript name of the font. It can be one of the following|
235           |          | base fonts: Courier, Courier-Bold, Courier-BoldOblique,        |
236           |          | Courier-Oblique, Helvetica, Helvetica-Bold,                    |
237           |          | Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman,         |
238           |          | Times-Bold, Times-Italic, Times-BoldItalic or Symbol.          |
239           +----------+----------------------------------------------------------------+
240
241       The ZapfDingbats font is not supported in this version.Default font is
242       Helvetica.
243
244           my $f1 = $pdf->font('BaseFont' => 'Helvetica');
245
246   new_outline(%params)
247       Adds  an  outline  to  the  document using the given parameters. Return
248       the newly created outline. Parameters can be:
249
250           +-------------+-------------------------------------------------------------+
251           | Key         | Description                                                 |
252           +-------------+-------------------------------------------------------------+
253           |             |                                                             |
254           | Title       | The title of the outline. Mandatory.                        |
255           |             |                                                             |
256           | Destination | The Destination of this outline item. In this version,it is |
257           |             | only possible to give a page as destination. The default    |
258           |             | destination is the current page.                            |
259           |             |                                                             |
260           | Parent      | The parent of this outline in the outlines tree. This is an |
261           |             | outline object. This way you represent the tree of your     |
262           |             | outlines.                                                   |
263           |             |                                                             |
264           +-------------+-------------------------------------------------------------+
265
266       Example:
267
268           my $outline = $pdf->new_outline('Title' => 'Item 1');
269           $pdf->new_outline('Title' => 'Item 1.1', 'Parent' => $outline);
270           $pdf->new_outline('Title' => 'Item 1.2', 'Parent' => $outline);
271           $pdf->new_outline('Title' => 'Item 2');
272
273   get_page_size($name)
274       Returns the  size of standard paper used for MediaBox-parameter  of
275       "new_page".  "get_page_size" has  one  optional parameter to specify
276       the paper name. Possible values are a0-a6,
277       a4l,letter,broadsheet,ledger,tabloid,legal,executive and 36x36.
278       Default is a4.
279
280           my $root = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );
281
282   version($number)
283       Set and return version number. Valid version numbers are 1.0, 1.1, 1.2
284       and 1.3.
285
286   close(%params)
287       Close does the work of creating the PDF data from the objects collected
288       before.  You must call "close()" after you have added all the contents
289       as most of the real work building the  PDF is performed there. If omit
290       calling close you get no PDF output. Returns the raw content of the
291       PDF.  If "fh" was provided when creating object of "PDF::Create" then
292       it does not try to close the file handle. It is, therefore, advised you
293       call "flush()" rather than "close()".
294
295   flush()
296       Generate the PDF content and returns the raw content as it is.
297
298   reserve($name, $type)
299       Reserve the next object number for the given object type.
300
301   add_comment($message)
302       Add comment to the document.The string will show up in the PDF as
303       postscript-style comment:
304
305           % this is a postscript comment
306
307   annotation(%params)
308       Adds an annotation object, for the time being we only do the  'Link' -
309       'URI' kind This is a  sensitive area in the PDF document where text
310       annotations are shown or links launched. "PDF::Create" only supports
311       URI links at this time.
312
313       URI links  have two components,the text or graphics object and the area
314       where the mouseclick should occur.
315
316       For the object  to be clicked  on you'll use standard text of drawing
317       methods. To define the click-sensitive area and the destination URI.
318
319       Example:
320
321           # Draw a string and underline it to show it is a link
322           $pdf->string($f1, 10, 450, 200, 'http://www.cpan.org');
323
324           my $line = $pdf->string_underline($f1, 10, 450, 200, 'http://www.cpan.org');
325
326           # Create the hot area with the link to open on click
327           $pdf->annotation(
328               Subtype => 'Link',
329               URI     => 'http://www.cpan.org',
330               x       => 450,
331               y       => 200,
332               w       => $l,
333               h       => 15,
334               Border  => [0,0,0]
335           );
336
337       The point (x, y) is  the  bottom  left corner of the rectangle
338       containing hotspot rectangle, (w, h) are  the  width and height of the
339       hotspot rectangle. The Border describes the thickness of the border
340       surrounding the rectangle hotspot.
341
342       The function "string_underline" returns the width of the string, this
343       can be used directly for the width of the hotspot rectangle.
344
345   image($filename)
346       Prepare an XObject (image) using the given arguments. This image will
347       be added to the document if it is referenced at least once before the
348       close method is called.  In this version GIF,interlaced GIF and JPEG is
349       supported. Usage of interlaced GIFs are slower because they are
350       decompressed, modified and  compressed again. The gif support is
351       limited to images with a LZW minimum code size of 8. Small images with
352       few colors can have a smaller minimum code size and will not work. If
353       you get errors regarding JPEG compression, then the compression method
354       used in your JPEG file is not supported by "PDF::Image::JPEG". Try
355       resaving the JPEG file with different compression options (for example,
356       disable progressive compression).
357
358       Example:
359
360           my $img = $pdf->image('image.jpg');
361
362           $page->image(
363               image  => $img,
364               xscale => 0.25, # scale image for better quality
365               yscale => 0.25,
366               xpos   => 50,
367               ypos   => 60,
368               xalign => 0,
369               yalign => 2,
370           );
371
372   get_data()
373       If you did not ask the $pdf object to write its output to a file, you
374       can pick up the  pdf  code  by calling this method. It returns a big
375       string. You need to call "close" first.
376

LIMITATIONS

378       "PDF::Create" comes with a couple of limitations or known caveats:
379
380   PDF Size / Memory
381       Unless using a filehandle, "PDF::Create" assembles the entire PDF in
382       memory.  If you create very large documents on a machine with a small
383       amount of memory your program can fail because it runs out of memory.
384       If using a filehandle, data will be written immediately to the
385       filehandle after each method.
386
387   Small GIF images
388       Some gif images get created with a minimal lzw code size of less than
389       8. "PDF::Create" can not decode those and they must be converted.
390

SUPPORT

392       I support "PDF::Create" in my spare time between work and  family, so
393       the amount of work I put in is limited.
394
395       If you experience a problem make sure you are at the latest version
396       first many of things have already been fixed.
397
398       Please register  bug  at the CPAN bug tracking system at
399       <http://rt.cpan.org> or send email to "bug-PDF-Create [at] rt.cpan.org"
400
401       Be sure to include the following information:
402
403       - PDF::Create Version you are running
404       - Perl version (perl -v)
405       - Operating System vendor and version
406       - Details about your operating environment that might be related to the
407       issue being described
408       - Exact cut and pasted error or warning messages
409       - The shortest, clearest  code  you  can manage to write which
410       reproduces the bug described.
411
412       I  appreciate patches against the latest released version of
413       "PDF::Create" which fix the bug.
414
415       Feature request can be submitted like bugs. If you provide patch for a
416       feature which does not go against the "PDF::Create" philosophy (keep it
417       simple) then you have a good chance for it to be accepted.
418

SEE ALSO

420       Adobe PDF <http://www.adobe.com/devnet/pdf/pdf_reference.html>
421
422       PDF::Labels Routines to produce formatted pages of mailing labels in
423       PDF, uses PDF::Create internally.
424
425       PDF::Haru Perl interface to Haru Free PDF Library.
426
427       PDF::EasyPDF PDF creation from a one-file module, similar to
428       PDF::Create.
429
430       PDF::CreateSimple Yet another PDF creation module
431
432       PDF::Report A wrapper written for PDF::API2.
433

AUTHORS

435       Fabien Tassin
436
437       GIF and JPEG-support: Michael Gross (info@mdgrosse.net)
438
439       Maintenance since 2007: Markus Baertschi (markus@markus.org)
440
441       Currently maintained by Mohammad S Anwar (MANWAR) "<mohammad.anwar at
442       yahoo.com>"
443

REPOSITORY

445       <https://github.com/manwar/pdf-create>
446
448       Copyright 1999-2001,Fabien Tassin.All rights reserved.It may be used
449       and modified freely, but I do  request that this copyright notice
450       remain attached to the file.  You may modify this module as you
451       wish,but if you redistribute a modified version , please attach a note
452       listing the modifications you have made.
453
454       Copyright 2007 Markus Baertschi
455
456       Copyright 2010 Gary Lieberman
457

LICENSE

459       This is free software; you can redistribute it and / or modify it under
460       the same terms as Perl 5.6.0.
461
462
463
464perl v5.34.0                      2022-01-21                    PDF::Create(3)
Impressum