1PDF::Create(3) User Contributed Perl Documentation PDF::Create(3)
2
6 PDF::Create - create PDF files
7
9 use PDF::Create;
10 my $pdf = new PDF::Create('filename' => 'mypdf.pdf',
12 'Version' => 1.2,
13 'PageMode' => 'UseOutlines',
14 'Author' => 'John Doe',
15 'Title' => 'My Title',
16 'CreationDate' => [ localtime ],
17 );
18 # add a A4 sized page
19 my $root = $pdf->new_page('MediaBox' => $pdf->get_page_size('A4'));
20 # Add a page which inherits its attributes from $root
22 my $page = $root->new_page;
23 # Prepare 2 fonts
25 my $f1 = $pdf->font('Subtype' => 'Type1',
26 'Encoding' => 'WinAnsiEncoding',
27 'BaseFont' => 'Helvetica');
28 my $f2 = $pdf->font('Subtype' => 'Type1',
29 'Encoding' => 'WinAnsiEncoding',
30 'BaseFont' => 'Helvetica-Bold');
31 # Prepare a Table of Content
33 my $toc = $pdf->new_outline('Title' => 'Document',
34 'Destination' => $page);
35 $toc->new_outline('Title' => 'Section 1');
36 my $s2 = $toc->new_outline('Title' => 'Section 2',
37 'Status' => 'closed');
38 $s2->new_outline('Title' => 'Subsection 1');
39 $page->stringc($f2, 40, 306, 426, "PDF::Create");
41 $page->stringc($f1, 20, 306, 396, "version $PDF::Create::VERSION");
42 # Add another page
44 my $page2 = $root->new_page;
45 $page2->line(0, 0, 612, 792);
46 $page2->line(0, 792, 612, 0);
47 $toc->new_outline('Title' => 'Section 3');
49 $pdf->new_outline('Title' => 'Summary');
50 # Add something to the first page
52 $page->stringc($f1, 20, 306, 300, 'by John Doe <john.doe@example.com>');
53 # Add the missing PDF objects and a the footer then close the file
55 $pdf->close;
56
58 PDF::Create allows you to create PDF documents using a number of
59 primitives. The result is as a PDF file or stream.
60 PDF stands for Portable Document Format.
62 Documents can have several pages, a table of content, an information
64 section and many other PDF elements.
65
67 · new
68 Create a new pdf structure for your pdf.
70 Example:
72 my $pdf = new PDF::Create('filename' => 'mypdf.pdf',
74 'Version' => 1.2,
75 'PageMode' => 'UseOutlines',
76 'Author' => 'John Doe',
77 'Title' => 'My title',
78 'CreationDate' => [ localtime ],
79 );
80 filename: destination file that will contain the resulting PDF or
82 an already opened filehandle or '-' for stdout.
83 Version: can be 1.0 to 1.3 (default: 1.2)
85 PageMode: how the document should appear when opened.
87 Allowed values are:
89 - UseNone: Open document with neither outline nor
91 thumbnails visible. This is the default value.
92 - UseOutlines: Open document with outline visible.
94 - UseThumbs: Open document with thumbnails visible.
96 - FullScreen: Open document in full-screen mode. In
98 full-screen mode, there is no menu bar, window controls,
99 nor any other window present.
100 Author: the name of the person who created this document
102 Creator: If the document was converted into a PDF document
104 from another form, this is the name of the application
105 that
106 created the original document.
107 - Title: the title of the document
109 - Subject: the subject of the document
111 - Keywords: keywords associated with the document
113 - CreationDate: the date the document was created. This
115 is passed
116 as an anonymous array in the same format as localtime
117 returns.
118 (ie. a struct tm).
119 If you are writing a CGI and send your PDF on the fly to a browser
121 you can follow this CGI Example:
122 use CGI; use PDF::Create;
124 print CGI::header( -type => 'application/x-pdf', -attachment => 'sample.pdf' );
125 my $pdf = new PDF::Create('filename' => '-', # Stdout
126 'Author' => 'John Doe',
127 'Title' => 'My title',
128 'CreationDate' => [ localtime ],
129 );
130 The created object is returned.
132 · close
134 Most of the real work building the PDF is performed in the close
136 method. It can there fore not be omitted, like a file close.
137 · get_data
139 If you didn't ask the $pdf object to write its output to a file,
141 you can pick up the pdf code by calling this method. It returns a
142 big string. You need to call "close" first, mind.
143 · add_comment [string]
145 Add a comment to the document.
147 · new_outline [parameters]
149 Add an outline to the document using the given parameters. Return
151 the newly created outline.
152 Parameters can be:
154 - Title: the title of the outline. Mandatory.
156 - Destination: the destination of this outline. In this version,
158 it is only possible to give a page as destination. The default
159 destination is the current page.
160 - Parent: the parent of this outline in the outlines tree. This is
162 an outline object.
163 Example:
165 my $outline = $pdf->new_outline('Title' => 'Item 1',
167 'Destination' => $page);
168 $outline->new_outline('Title' => 'Item 1.1');
169 $pdf->new_outline('Title' => 'Item 1.2',
170 'Parent' => $outline);
171 $pdf->new_outline('Title' => 'Item 2');
172 · new_page
174 Add a page to the document using the given parameters. Return the
176 newly created page.
177 Parameters can be:
179 - Parent: the parent of this page in the pages tree. This is a
181 page object.
182 - Resources: Resources required by this page.
184 - MediaBox: Rectangle specifying the natural size of the page, for
186 example the dimensions of an A4 sheet of paper. The coordinates
187 are measured in default user space units. It must be the reference
188 of a 4 values array. You can use "get_page_size" to get the size
189 of standard paper sizes.
190 "get_page_size" knows about A0-A6, A4L (landscape), Letter,
191 Legal, Broadsheet, Ledger, Tabloid, Executive and 36x36.
192 - CropBox: Rectangle specifying the default clipping region for
194 the page when displayed or printed. The default is the value of
195 the MediaBox.
196 - ArtBox: Rectangle specifying an area of the page to be used when
198 placing PDF content into another application. The default is the
199 value of the CropBox. [PDF 1.3]
200 - TrimBox: Rectangle specifying the intended finished size of the
202 page (for example, the dimensions of an A4 sheet of paper). In
203 some cases, the MediaBox will be a larger rectangle, which
204 includes printing instructions, cut marks, or other content. The
205 default is the value of the CropBox. [PDF 1.3].
206 - BleedBox: Rectangle specifying the region to which all page
208 content should be clipped if the page is being output in a
209 production environment. In such environments, a bleed area is
210 desired, to accommodate physical limitations of cutting, folding,
211 and trimming equipment. The actual printed page may include
212 printer's marks that fall outside the bleed box. The default is
213 the value of the CropBox. [PDF 1.3]
214 - Rotate: Specifies the number of degrees the page should be
216 rotated clockwise when it is displayed or printed. This value must
217 be zero (the default) or a multiple of 90. The entire page,
218 including contents is rotated.
219 · get_page_size
221 Returns the size of standard paper sizes to use for MediaBox-
223 parameter of "new_page". "get_page_size" has one required
224 parameter to specify the paper name. Possible values are a0-a6,
225 letter, broadsheet, ledger, tabloid, legal, executive and 36x36.
226 Default is a4.
227 · font
229 Prepare a font using the given arguments. This font will be added
231 to the document only if it is used at least once before the close
232 method is called.
233 Parameters can be:
235 - Subtype: Type of font. PDF defines some types of fonts. It must
237 be one of the predefined type Type1, Type3, TrueType or Type0.
238 In this version, only Type1 is supported. This is the default
240 value.
241 - Encoding: Specifies the encoding from which the new encoding
243 differs. It must be one of the predefined encodings
244 MacRomanEncoding, MacExpertEncoding or WinAnsiEncoding.
245 In this version, only WinAnsiEncoding is supported. This is the
247 default value.
248 - BaseFont: The PostScript name of the font. It can be one of the
250 following base fonts: Courier, Courier-Bold, Courier-BoldOblique,
251 Courier-Oblique, Helvetica, Helvetica-Bold, Helvetica-BoldOblique,
252 Helvetica-Oblique, Times-Roman, Times-Bold, Times-Italic or Times-
253 BoldItalic.
254 The Symbol or ZapfDingbats fonts are not supported in this
256 version.
257 The default font is Helvetica.
259 · image filename
261 Prepare an XObject (image) using the given arguments. This image
263 will be added to the document if it is referenced at least once
264 before the close method is called. In this version GIF, interlaced
265 GIF and JPEG is supported. Usage of interlaced GIFs are slower
266 because they are decompressed, modified and compressed again. The
267 gif support is limited to images with a lwz min code size of 8.
268 Small images with few colors can have a smaller min code size.
269 Parameters:
271 - filename: file name of image (required).
273 Page methods
275 This section describes the methods that can be used by a
276 PDF::Create::Page object.
277 In its current form, this class is divided into two main parts, one for
279 drawing (using PostScript like paths) and one for writing.
280 Some methods are not described here because they must not be called
282 directly (e.g. "new" and "add").
283 · new_page params
285 Add a sub-page to the current page.
287 See "PDF::Create::new_page"
289 · string font size x y text
291 Add text to the current page using the font object at the given
293 size and position. The point (x, y) is the bottom left corner of
294 the rectangle containing the text.
295 Example :
297 my $f1 = $pdf->font('Subtype' => 'Type1',
299 'Encoding' => 'WinAnsiEncoding',
300 'BaseFont' => 'Helvetica');
301 $page->string($f1, 20, 306, 396, "some text");
302 · stringl font size x y text
304 Same as "string".
306 · stringr font size x y text
308 Same as "string" but right aligned.
310 · stringc font size x y text
312 Same as "string" but centered.
314 · printnl text font size x y
316 Similar to "string" but parses the string for newline and prints
318 each part on a separate line. Lines spacing is the same as the
319 font-size. Returns the number of lines.
320 Note the different parameter sequence. The first call should
322 specify all parameters, font is the absolute minimum, a warning
323 will be given for the missing y position and 800 will be assumed.
324 All subsequent invocations can omit all but the string parameters.
325 · string_width font text
327 Return the size of the text using the given font in default user
329 space units. This does not contain the size of the font yet.
330 · line x1 y1 x2 y2
332 Draw a line between (x1, y1) and (x2, y2).
334 · set_width w
336 Set the width of subsequent lines to w points.
338 · setrgbcolor r g b
340 Set the color of the subsequent drawing operations. R,G and B is a
342 value between 0.0 and 1.0.
343 Low level drawing methods
345 · moveto x y
346 Moves the current point to (x, y), omitting any connecting line
348 segment.
349 · lineto x y
351 Appends a straight line segment from the current point to (x, y).
353 The current point is (x, y).
354 · curveto x1 y1 x2 y2 x3 y3
356 Appends a Bezier curve to the path. The curve extends from the
358 current point to (x3 ,y3) using (x1 ,y1) and (x2 ,y2) as the
359 Bezier control points. The new current point is (x3 ,y3).
360 · rectangle x y w h
362 Adds a rectangle to the current path.
364 · closepath
366 Closes the current subpath by appending a straight line segment
368 from the current point to the starting point of the subpath.
369 · newpath
371 Ends the path without filling or stroking it.
373 · stroke
375 Strokes the path.
377 A typical usage is
379 $page->newpath;
381 $page->setrgbcolorstroke 0.1 0.3 0.8;
382 $page->moveto 100 100;
383 $page->lineto 200 100;
384 $page->stroke;
385 · closestroke
387 Closes and strokes the path.
389 · fill
391 Fills the path using the non-zero winding number rule.
393 · fill2
395 Fills the path using the even-odd rule
397 · image image_id xpos ypos xalign yalign xscale yscale rotate xskew
399 yskew
400 Inserts an image.
402 Parameters can be:
404 - image: Image id returned by PDF::image (required).
406 - xpos, ypos: Position of image (required).
408 - xalign, yalign: Alignment of image. 0 is left/bottom, 1 is
410 centered and 2 is right, top.
411 - xscale, yscale: Scaling of image. 1.0 is original size.
413 - rotate: Rotation of image. 0 is no rotation, 2*pi is 360X
415 rotation.
416 - xskew, yskew: Skew of image.
418
420 PDF::Create::Page, <http://www.adobe.com/devnet/pdf/pdf_reference.html>
421 http://github.com/markusb/pdf-create <http://github.com/markusb/pdf-
422 create>
423
425 Fabien Tassin (fta@sofaraway.org)
426 GIF and JPEG-support: Michael Gross (info@mdgrosse.net)
428 Maintenance since 2007: Markus Baertschi (markus@markus.org)
430
432 Copyright 1999-2001, Fabien Tassin. All rights reserved. It may be
433 used and modified freely, but I do request that this copyright notice
434 remain attached to the file. You may modify this module as you wish,
435 but if you redistribute a modified version, please attach a note
436 listing the modifications you have made.
437 Copyright 2007-, Markus Baertschi
439perl v5.12.0 2009-07-13 PDF::Create(3)