1PDF::Reuse(3) User Contributed Perl Documentation PDF::Reuse(3)
2
6 PDF::Reuse - Reuse and mass produce PDF documents
7
9 use PDF::Reuse;
10 prFile('myFile.pdf');
11 prText(100, 500, 'Hello World !');
12 prEnd();
13
15 This module could be used when you want to mass produce similar (but
16 not identical) PDF documents and reuse templates, JavaScripts and some
17 other components. It is functional to be fast, and to give your
18 programs capacity to produce many pages per second and very big PDF
19 documents if necessary.
20 The module produces PDF-1.4 files. Some features of PDF-1.5, like
22 "object streams" and "cross reference streams", are supported, but only
23 at an experimental level. More testing is needed. (If you get problems
24 with a new document from Acrobat 6 or higher, try to save it or
25 recreate it as a PDF-1.4 document first, before using it together with
26 this module.)
27 Templates
29 Use your favorite program, probably a commercial visual tool, to
30 produce single PDF-files to be used as templates, and then use this
31 module to mass produce files from them.
32 (If you want small PDF-files or want special graphics, you can use
34 this module also, but visual tools are often most practical.)
35 Lists
37 The module uses "XObjects" extensively. This is a format that makes
38 it possible create big lists, which are compact at the same time.
39 PDF-operators
41 The module gives you a good possibility to program at a "low level"
42 with the basic graphic operators of PDF, if that is what you want to
43 do. You can build your own libraries of low level routines, with PDF-
44 directives "controlled" by Perl.
45 Archive-format
47 If you want, you get your new documents logged in a format suitable
48 for archiving or transfer.
49 PDF::Reuse::Tutorial might show you best what you can do with this
51 module.
52 JavaScript
54 You can attach JavaScripts to your PDF-files.
55 You can have libraries of JavaScripts. No cutting or pasting, and
57 those who include the scripts in documents only need to know how to
58 initiate them. (Of course those who write the scripts have to know
59 Acrobat JavaScript well.)
60 Remarks about JavaScript
62 Some of the functions handling JavaScript have to be rewritten for
63 Acrobat 7.
64 There are many limitations with Acrobat JavaScript, and the rules often
66 change. So what works for one version of Acrobat/Reader, might not
67 work for another. Another complication is this: When documents are
68 downloaded via the net by Acrobat, they are most often converted (!)
69 and necessary JavaScripts are lost.
70
72 All functions which are successful return specified values or 1.
73 The module doesn't make any attempt to import anything from encrypted
75 files.
76
78 To write a program with PDF::Reuse, you need these components:
79
81 prFile - define output
82 Alternative 1:
83 prFile ( $fileName );
85 Alternative 2 with parameters in an anonymous hash:
87 prFile ( { Name => $fileName,
89 HideToolbar => 1, # 1 or 0
90 HideMenubar => 1, # 1 or 0
91 HideWindowUI => 1, # 1 or 0
92 FitWindow => 1, # 1 or 0
93 CenterWindow => 1 } ); # 1 or 0
94 Alternative 3:
96 prFile ( $r ); # For mod_perl 2 pass the request object
98 $fileName is optional, just like the rest of the parameters. File to
100 create. If another file is current when this function is called, the
101 first one is written and closed. Only one file is processed at a single
102 moment. If $fileName is undefined, output is written to STDOUT.
103 HideToolbar, HideMenubar, HideWindowUI, FitWindow and CenterWindow
105 control the way the document is initially displayed.
106 Look at any program in this documentation for examples. prInitVars()
108 shows how this function could be used together with a web server.
109 prEnd - end/flush buffers
111 prEnd ()
112 When the processing is going to end, the buffers of the last file has
114 to be written to the disc. If this function is not called, the page
115 structure, xref part and so on will be lost.
116 Look at any program in this documentation for an example.
118
120 prAdd - add "low level" instructions
121 prAdd ( $string )
122 With this command you can add whatever you want to the current content
124 stream. No syntactical checks are made, but if you use an internal
125 name, the module tries to add the resource of the "name object" to the
126 "Resources" of current page. "Name objects" always begin with a '/'.
127 (In this documentation I often use talk about an "internal name". It
129 denotes a "name object". When PDF::Reuse creates these objects, it
130 assigns Ft1, Ft2, Ft3 ... for fonts, Ig1, Ig2, Ig3 for images, Fo1 ..
131 for forms, Cs1 .. for Color spaces, Pt1 .. for patterns, Sh1 .. for
132 shading directories, Gs0 .. for graphic state parameter dictionaries.
133 These names are kept until the program finishes, and my ambition is
134 also to keep the resources available in internal tables.)
135 This is a simple and very powerful function. You should study the
137 examples and the "PDF-reference manual", if you want to use it.(When
138 this text is written, a possible link to download it is:
139 http://partners.adobe.com/asn/developer/acrosdk/docs.html)
140 This function is intended to give you detail control at a low level.
142 use PDF::Reuse;
144 use strict;
145 prFile('myFile.pdf');
147 my $string = "150 600 100 50 re\n"; # a rectangle
148 $string .= "0 0 1 rg\n"; # blue (to fill)
149 $string .= "b\n"; # fill and stroke
150 prAdd($string);
151 prEnd();
152 prBookmark - define bookmarks
154 prBookmark($reference)
155 Defines a "bookmark". $reference refers to a hash or array of hashes
157 which looks something like this:
158 { text => 'Document',
160 act => 'this.pageNum = 0; this.scroll(40, 500);',
161 kids => [ { text => 'Chapter 1',
162 act => '1, 40, 600'
163 },
164 { text => 'Chapter 2',
165 act => '10, 40, 600'
166 }
167 ]
168 }
169 Each hash can have these components:
171 text the text shown beside the bookmark
173 act the action to be triggered. Has to be a JavaScript action.
174 (Three simple numbers are translated to page, x and y in the
175 sentences: this.pageNum = page; this.scroll(x, y); )
176 kids will have a reference to another hash or array of hashes
177 close if this component is present, the bookmark will be closed
178 when the document is opened
179 color 3 numbers, RGB-colors e.g. '0.5 0.5 1' for light blue
180 style 0, 1, 2, or 3. 0 = Normal, 1 = Italic, 2 = Bold, 3 = Bold Italic
181 Creating bookmarks for a document:
183 use PDF::Reuse;
185 use strict;
186 my @pageMarks;
188 prFile('myDoc.pdf');
190 for (my $i = 0; $i < 100; $i++)
192 { prText(40, 600, 'Something is written');
193 # ...
194 my $page = $i + 1;
195 my $bookMark = { text => "Page $page",
196 act => "$i, 40, 700" };
197 push @pageMarks, $bookMark;
198 prPage();
199 }
200 prBookmark( { text => 'Document',
201 close => 1,
202 kids => \@pageMarks } );
203 prEnd();
204 Traditionally bookmarks have mainly been used for navigation within a
206 document, but they can be used for many more things. You can e.g. use
207 them to navigate within your data. You can let your users go to
208 external links also, so they can "drill down" to other documents.
209 See "Remarks about JavaScript"
211 prCompress - compress/zip added streams
213 prCompress (1)
214 '1' here is a directive to compress all new streams of the current
216 file. Streams which are included with prForm, prDocForm, prDoc or
217 prSinglePage are not changed. New JavaScripts are also created as
218 streams and compressed, if they are at least 100 bytes long. The
219 streams are compressed in memory, so probably there is a limit of how
220 big they can be.
221 prCompress(); is a directive not to compress. This is default.
223 See e.g. "Starting to reuse" in the tutorial for an example.
225 prDoc - include pages from a document
227 prDoc ( $documentName, $firstPage, $lastPage )
228 or with the parameters in an anonymous hash:
230 prDoc ( { file => $documentName,
232 first => $firstPage,
233 last => $lastPage } );
234 Returns number of extracted pages.
236 If "first" is not given, 1 is assumed. If "last" is not given, you
238 don't have any upper limit. N.B. The numbering of the pages differs
239 from Acrobat JavaScript. In JavaScript the first page has index 0.
240 Adds pages from a document to the one you are creating. N.B. From
242 version 0.32 of this module: If there are contents created with with
243 prText, prImage,prAdd, prForm and so on, prDoc tries to put the
244 contents on the first extracted page from the old document.
245 If it is the first interactive component ( prDoc() or prDocForm() ) the
247 interactive functions are kept and also merged with JavaScripts you
248 have added, if any. But, if you specify a first page different than 1
249 or a last page, no JavaScript are extracted from the document, because
250 then there is a risk that an included JavaScript function might refer
251 to something not included.
252 use PDF::Reuse;
254 use strict;
255 prFile('myFile.pdf'); # file to make
257 prJs('customerResponse.js'); # include a JavaScript file
258 prInit('nameAddress(12, 150, 600);'); # init a JavaScript function
259 prForm('best.pdf'); # page 1 from best.pdf
260 prPage();
261 prDoc('long.pdf'); # a document with 11 pages
262 prForm('best.pdf'); # page 1 from best.pdf
263 prText(150, 700, 'Customer Data'); # a line of text
264 prEnd();
265 To extract pages 2-3 and 5-7 from a document and create a new document:
267 use PDF::Reuse;
269 use strict;
270 prFile('new.pdf');
272 prDoc( { file => 'old.pdf',
273 first => 2,
274 last => 3 });
275 prDoc( { file => 'old.pdf',
276 first => 5,
277 last => 7 });
278 prEnd();
279 To add a form, image and page number to each page of an 16 pages long
281 document (The document Battery.pdf is cropped so each page is fairly
282 small) You could also have used prSinglePage, look at a very similar
283 example under that function.
284 use PDF::Reuse;
286 use PDF::Reuse::Util;
287 use strict;
288 prFile('test.pdf');
290 my $pageNumber = 0;
292 for (my $page = 1; $page < 17; $page++)
294 { $pageNumber++;
295 prForm( { file =>'Words.pdf',
296 page => 5,
297 x => 150,
298 y => 150} );
299 prImage( { file =>'Media.pdf',
301 page => 6,
302 imageNo => 1,
303 x => 450,
304 y => 450 } );
305 blackText();
306 prText( 360, 250, $pageNumber);
307 prDoc('Battery.pdf', $pageNumber, $pageNumber);
308 }
309 prEnd;
310 prDocDir - set directory for produced documents
312 prDocDir ( $directoryName )
313 Sets directory for produced documents
315 use PDF::Reuse;
317 use strict;
318 prDocDir('C:/temp/doc');
320 prFile('myFile.pdf'); # writes to C:\temp\doc\myFile.pdf
321 prForm('myFile.pdf'); # page 1 from ..\myFile.pdf
322 prText(200, 600, 'New text');
323 prEnd();
324 prDocForm - use an interactive page as a form
326 Alternative 1) You put your parameters in an anonymous hash (only file
327 is really necessary, the others get default values if not given).
328 prDocForm ( { file => $pdfFile, # template file
330 page => $page, # page number (of imported template)
331 adjust => $adjust, # try to fill the media box
332 effect => $effect, # action to be taken
333 tolerant => $tolerant, # continue even with an invalid form
334 x => $x, # $x points from the left
335 y => $y, # $y points from the bottom
336 rotate => $degree, # rotate
337 size => $size, # multiply everything by $size
338 xsize => $xsize, # multiply horizontally by $xsize
339 ysize => $ysize } ) # multiply vertically by $ysize
340 Ex.:
341 my $internalName = prDocForm ( {file => 'myFile.pdf',
342 page => 2 } );
343 Alternative 2) You put your parameters in this order
345 prDocForm ( $pdfFile, [$page, $adjust, $effect, $tolerant, $x, $y, $degree,
347 $size, $xsize, $ysize] )
348 Anyway the function returns in list context: $intName, @BoundingBox,
350 $numberOfImages, in scalar context: $internalName of the form.
351 Look at prForm() for an explanation of the parameters.
353 N.B. Usually you shouldn't adjust or change size and proportions of an
355 interactive page. The graphic and interactive components are
356 independent of each other and there is a great risk that any
357 coordination is lost.
358 This function redefines a page to an "XObject" (the graphic parts),
360 then the page can be reused in a much better way. Unfortunately there
361 is an important limitation here. "XObjects" can only have single
362 streams. If the page consists of many streams, you should concatenate
363 them first. Adobe Acrobat can do that. (If it is an important file,
364 take a copy of it first. Sometimes the procedure fails.) Open the
365 document with Acrobat. Then choose the the "TouchUp Text" tool (icon or
366 from the tools menu). Select a line of text somewhere on the page.
367 Right-click the mouse. Choose "Attributes".Change font size or anything
368 else, and then you change it back to the old value. Save the document.
369 If there was no text on the page, use some other "Touch Up" tool.
370 use PDF::Reuse;
372 use strict;
373 prDocDir('C:/temp/doc');
375 prFile('newForm.pdf');
376 prField('Mr/Ms', 'Mr');
377 prField('First_Name', 'Lars');
378 prDocForm('myFile.pdf');
379 prFontSize(24);
380 prText(75, 790, 'This text is added');
381 prEnd();
382 (You can use the output from the example in prJs() as input to this
384 example. Remember to save that file before closing it.)
385 See Remarks about JavaScript
387 prExtract - extract an object group
389 prExtract ( $pdfFile, $pageNo, $oldInternalName )
390 oldInternalName, a "name"-object. This is the internal name you find
392 in the original file. Returns a $newInternalName which can be used for
393 "low level" programming. You have better look at graphObj_pl and
394 modules it has generated for the tutorial, e.g. thermometer.pm, to see
395 how this function can be used.
396 When you call this function, the necessary objects will be copied to
398 your new PDF-file, and you can refer to them with the new name you
399 receive.
400 prField - assign a value to an interactive field
402 prField ( $fieldName, $value )
403 $fieldName is an interactive field in the document you are creating.
405 It has to be spelled exactly the same way here as it spelled in the
406 document. $value is what you want to assigned to the field. Put all
407 your sentences with prField early in your script. After prFile and
408 before prDoc or prDocForm and of course before prEnd. Each sentence
409 with prField is translated to JavaScript and merged with old JavaScript
410 See prDocForm() for an example
412 If you are going to assign a value to a field consisting of several
414 lines, you can write like this:
415 my $string = "This is the first line \r second line \n 3:rd line";
417 prField('fieldName', $string);
418 You can also let '$value' be a snippet of JavaScript-code that assigns
420 something to the field. Then you have to put 'js:' first in "$value"
421 like this:
422 my $sentence = encrypt('This will be decrypted by "unPack"(JavaScript) ');
424 prField('Interest_9', "js: unPack('$sentence')");
425 If you refer to a JavaScript function, it has to be included with prJs
427 first. (The JavaScript interpreter will simply not be aware of old
428 functions in the PDF-document, when the initiation is done.)
429 prFont - set current font
431 prFont ( $fontName )
432 $fontName is an "external" font name. The parameter is optional. In
434 list context returns $internalName, $externalName, $oldInternalName,
435 $oldExternalname The first two variables refer to the current font, the
436 two later to the font before the change. In scalar context returns
437 b<$internalName>
438 If a font wasn't found, Helvetica will be set. These names are always
440 recognized: Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic,
441 Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica,
442 Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique or abbreviated
443 TR, TB, TI, TBI, C, CB, CO, CBO, H, HB, HO, HBO. (Symbol and
444 ZapfDingbats or abbreviated S, Z, also belong to the predefined fonts,
445 but there is something with them that I really don't understand. You
446 should print them first on a page, and then use other fonts, otherwise
447 they are not displayed.)
448 You can also use a font name from an included page. It has to be
450 spelled exactly as it is done there. Look in the file and search for
451 "/BaseFont" and the font name. But take care, e.g. the PDFMaker which
452 converts to PDF from different Microsoft programs, only defines exactly
453 those letters you can see on the page. You can use the font, but
454 perhaps some of your letters were not defined.
455 In the distribution there is an utility program, 'reuseComponent_pl',
457 which displays included fonts in a PDF-file and prints some letters.
458 Run it to see the name of the font and if it is worth extracting.
459 use PDF::Reuse;
461 use strict;
462 prFile('myFile.pdf');
463 ####### One possibility #########
465 prFont('Times-Roman'); # Just setting a font
467 prFontSize(20);
468 prText(180, 790, "This is a heading");
469 ####### Another possibility #######
471 my $font = prFont('C'); # Setting a font, getting an
473 # internal name
474 prAdd("BT /$font 12 Tf 25 760 Td (This is some other text)Tj ET");
475 prEnd();
476 The example above shows you two ways of setting and using a font. One
478 simple, and one complicated with a possibility to detail control.
479 prFontSize - set current font size
481 prFontSize ( $size )
482 Returns $actualSize, $fontSizeBeforetheChange. Without parameters
484 prFontSize() sets the size to 12 points, which is default.
485 prForm - use a page from an old document as a form/background
487 Alternative 1) You put your parameters in an anonymous hash (only file
488 is really necessary, the others get default values if not given).
489 prForm ( { file => $pdfFile, # template file
491 page => $page, # page number (of imported template)
492 adjust => $adjust, # try to fill the media box
493 effect => $effect, # action to be taken
494 tolerant => $tolerant, # continue even with an invalid form
495 x => $x, # $x points from the left
496 y => $y, # $y points from the bottom
497 rotate => $degree, # rotate
498 size => $size, # multiply everything by $size
499 xsize => $xsize, # multiply horizontally by $xsize
500 ysize => $ysize } ) # multiply vertically by $ysize
501 Ex.:
502 my $internalName = prForm ( {file => 'myFile.pdf',
503 page => 2 } );
504 Alternative 2) You put your parameters in this order
506 prForm ( $pdfFile, $page, $adjust, $effect, $tolerant, $x, $y, $degree,
508 $size, $xsize, $ysize )
509 Anyway the function returns in list context: $intName, @BoundingBox,
511 $numberOfImages, in scalar context: $internalName of the form.
512 if page is excluded 1 is assumed.
514 adjust, could be 1, 2 or 0/nothing. If it is 1, the program tries to
516 adjust the form to the current media box (paper size) and keeps the
517 proportions unchanged. If it is 2, the program tries to fill as much
518 of the media box as possible, without regards to the original
519 proportions. If this parameter is given, "x", "y", "rotate", "size",
520 "xsize" and "ysize" will be ignored.
521 effect can have 3 values: 'print', which is default, loads the page in
523 an internal table, adds it to the document and prints it to the current
524 page. 'add', loads the page and adds it to the document. (Now you can
525 "manually" manage the way you want to print it to different pages
526 within the document.) 'load' just loads the page in an internal table.
527 (You can now take parts of a page like fonts and objects and manage
528 them, without adding all the page to the document.)You don't get any
529 defined internal name of the form, if you let this parameter be 'load'.
530 tolerant can be nothing or something. If it is undefined, you will get
532 an error if your program tries to load a page which the system cannot
533 really handle, if it e.g. consists of many streams. If it is set to
534 something, you have to test the first return value $internalName to
535 know if the function was successful. Look at the program
536 'reuseComponent_pl' for an example of usage.
537 x where to start along the x-axis (cannot be combined with "adjust")
539 y where to start along the y-axis (cannot be combined with "adjust")
541 rotate A degree 0-360 to rotate the form counter-clockwise. (cannot be
543 combined with "adjust") Often the form disappears out of the media box
544 if degree >= 90. Then you can move it back with the x and
545 y-parameters. If degree == 90, you can add the width of the form to x,
546 If degree == 180 add both width and height to x and y, and if degree ==
547 270 you can add the height to y.
548 rotate can also by one of 'q1', 'q2' or 'q3'. Then the system rotates
550 the form clockwise 90, 180 or 270 degrees and tries to keep the form
551 within the media box.
552 The rotation takes place after the form has been resized or moved.
554 Ex. To rotate from portrait (595 x 842 pt) to landscape (842 x 595 pt)
556 use PDF::Reuse;
558 use strict;
559 prFile('New_Report.pdf');
561 prMbox(0, 0, 842, 595);
562 prForm({file => 'cert1.pdf',
564 rotate => 'q1' } );
565 prEnd();
566 The same rotation can be achieved like this:
568 use PDF::Reuse;
570 use strict;
571 prFile('New_Report.pdf');
573 prMbox(0, 0, 842, 595);
574 prForm({file => 'cert1.pdf',
576 rotate => 270,
577 y => 595 } );
578 prEnd();
579 size multiply every measure by this value (cannot be combined with
581 "adjust")
582 xsize multiply horizontally by this value (cannot be combined with
584 "adjust")
585 ysize multiply vertically by $ysize (cannot be combined with "adjust")
587 This function redefines a page to an "XObject" (the graphic parts),
589 then the page can be reused and referred to as a unit. Unfortunately
590 there is an important limitation here. "XObjects" can only have single
591 streams. If the page consists of many streams, you should concatenate
592 them first. Adobe Acrobat can do that. (If it is an important file,
593 take a copy of it first. Sometimes the procedure fails.) Open the
594 document with Acrobat. Then choose the "TouchUp Text" tool. Select a
595 line of text somewhere. Right-click the mouse. Choose "Attributes".
596 Change font size or anything else, and then you change it back to the
597 old value. Save the document. You could alternatively save the file as
598 Postscript and redistill it with the distiller or with Ghost script,
599 but this is a little more risky. You might loose fonts or something
600 else. Another alternative could be to use prSinglePage().
601 use PDF::Reuse;
603 use strict;
604 prFile('myFile.pdf');
606 prForm('best.pdf'); # Takes page No 1
607 prText(75, 790, 'Dear Mr Gates');
608 # ...
609 prPage();
610 prMbox(0, 0, 900, 960);
611 my @vec = prForm( { file => 'EUSA.pdf',
612 adjust => 1 } );
613 prPage();
614 prMbox();
615 prText(35, 760, 'This is the final page');
616 # More text ..
618 #################################################################
620 # We want to put a miniature of EUSA.pdf, 35 points from the left
621 # 85 points up, and in the format 250 X 200 points
622 #################################################################
623 my $xScale = 250 / ($vec[3] - $vec[1]);
625 my $yScale = 200 / ($vec[4] - $vec[2]);
626 prForm ({ file => 'EUSA.pdf',
628 xsize => $xScale,
629 ysize => $yScale,
630 x => 35,
631 y => 85 });
632 prEnd();
634 The first prForm(), in the code, is a simple and "normal" way of using
636 the the function. The second time it is used, the size of the imported
637 page is changed. It is adjusted to the media box which is current at
638 that moment. Also data about the form is taken, so you can control
639 more in detail how it will be displayed.
640 prGetLogBuffer - get the log buffer.
642 prGetLogBuffer ()
643 returns a $buffer of the log of the current page. (It could be used
645 e.g. to calculate a MD5-digest of what has been registered that far,
646 instead of accumulating the single values) A log has to be active, see
647 prLogDir() below
648 Look at "Using the template" and "Restoring a document from the log" in
650 the tutorial for examples of usage.
651 prGraphState - define a graphic state parameter dictionary
653 prGraphState ( $string )
654 This is a "low level" function. Returns $internalName. The $string has
656 to be a complete dictionary with initial "<<" and terminating ">>". No
657 syntactical checks are made. Perhaps you will never have to use this
658 function.
659 use PDF::Reuse;
661 use strict;
662 prFile('myFile.pdf');
664 ###################################################
666 # Draw a triangle with Gs0 (automatically defined)
667 ###################################################
668 my $str = "q\n";
670 $str .= "/Gs0 gs\n";
671 $str .= "150 700 m\n";
672 $str .= "225 800 l\n";
673 $str .= "300 700 l\n";
674 $str .= "150 700 l\n";
675 $str .= "S\n";
676 $str .= "Q\n";
677 prAdd($str);
678 ########################################################
680 # Define a new graph. state param. dic. and draw a new
681 # triangle further down
682 ########################################################
683 $str = '<</Type/ExtGState/SA false/SM 0.02/TR2 /Default'
685 . '/LW 15/LJ 1/ML 1>>';
686 my $gState = prGraphState($str);
687 $str = "q\n";
688 $str .= "/$gState gs\n";
689 $str .= "150 500 m\n";
690 $str .= "225 600 l\n";
691 $str .= "300 500 l\n";
692 $str .= "150 500 l\n";
693 $str .= "S\n";
694 $str .= "Q\n";
695 prAdd($str);
696 prEnd();
698 prImage - reuse an image from an old PDF document
700 Alternative 1) You put your parameters in an anonymous hash (only file
701 is really necessary, the others get default values if not given).
702 prImage( { file => $pdfFile, # template file
704 page => $page, # page number
705 imageNo => $imageNo # image number
706 adjust => $adjust, # try to fill the media box
707 effect => $effect, # action to be taken
708 x => $x, # $x points from the left
709 y => $y, # $y points from the bottom
710 rotate => $degree, # rotate
711 size => $size, # multiply everything by $size
712 xsize => $xsize, # multiply horizontally by $xsize
713 ysize => $ysize } ) # multiply vertically by $ysize
714 Ex.:
715 prImage( { file => 'myFile.pdf',
716 page => 10,
717 imageNo => 2 } );
718 Alternative 2) You put your parameters in this order
720 prImage ( $pdfFile, [$page, $imageNo, $effect, $adjust, $x, $y, $degree,
722 $size, $xsize, $ysize] )
723 Returns in scalar context $internalName As a list $internalName,
725 $width, $height
726 Assumes that $pageNo and $imageNo are 1, if not specified. If $effect
728 is given and anything else then 'print', the image will be defined in
729 the document, but not shown at this moment.
730 For all other parameters, look at prForm().
732 use PDF::Reuse;
734 use strict;
735 prFile('myFile.pdf');
737 my @vec = prImage({ file => 'best.pdf',
738 x => 10,
739 y => 400,
740 xsize => 0.9,
741 ysize => 0.8 } );
742 prText(35, 760, 'This is some text');
743 # ...
744 prPage();
745 my @vec2 = prImage( { file => 'destiny.pdf',
746 page => 1,
747 imageNo => 1,
748 effect => 'add' } );
749 prText(25, 760, "There shouldn't be any image on this page");
750 prPage();
751 ########################################################
752 # Now we make both images so that they could fit into
753 # a box 300 X 300 points, and they are displayed
754 ########################################################
755 prText(25, 800, 'This is the first image :');
757 my $xScale = 300 / $vec[1];
759 my $yScale = 300 / $vec[2];
760 if ($xScale < $yScale)
761 { $yScale = $xScale;
762 }
763 else
764 { $xScale = $yScale;
765 }
766 prImage({ file => 'best.pdf',
767 x => 25,
768 y => 450,
769 xsize => $xScale,
770 ysize => $yScale} );
771 prText(25, 400, 'This is the second image :');
773 $xScale = 300 / $vec2[1];
775 $yScale = 300 / $vec2[2];
776 if ($xScale < $yScale)
777 { $yScale = $xScale;
778 }
779 else
780 { $xScale = $yScale;
781 }
782 prImage({ file => 'destiny.pdf',
783 x => 25,
784 y => 25,
785 xsize => $xScale,
786 ysize => $yScale} );
787 prEnd();
789 On the first page an image is displayed in a simple way. While the
791 second page is processed, prImage(), loads an image, but it is not
792 shown here. On the 3:rd page, the two images are scaled and shown.
793 In the distribution there is an utility program, 'reuseComponent_pl',
795 which displays included images in a PDF-file and their "names".
796 prInit - add JavaScript to be executed at initiation
798 prInit ( $string, $duplicateCode )
799 $string can be any JavaScript code, but you can only refer to functions
801 included with prJs. The JavaScript interpreter will not know other
802 functions in the document. Often you can add new things, but you can't
803 remove or change interactive fields, because the interpreter hasn't
804 come that far, when initiation is done.
805 $duplicateCode is undefined or anything. It duplicates the JavaScript
807 code which has been used at initiation, so you can look at it from
808 within Acrobat and debug it. It makes the document bigger. This
809 parameter is deprecated.
810 use PDF::Reuse;
812 use strict;
813 prFile('myFile.pdf');
815 prInit('app.alert("This is displayed when opening the document");');
816 prEnd();
818 Remark: Avoid to use "return" in the code you use at initiation. If
820 your user has downloaded a page with Web Capture, and after that opens
821 a PDF-document where a JavaScript is run at initiation and that
822 JavaScript contains a return-statement, a bug occurs. The JavaScript
823 interpreter "exits" instead of returning, the execution of the
824 JavaScript might finish to early. This is a bug in Acrobat/Reader 5.
825 prInitVars - initiate global variables and internal tables
827 prInitVars(1)
828 If you run programs with PDF::Reuse as persistent procedures, you
830 probably need to initiate global variables. If you have '1' or anything
831 as parameter, internal tables for forms, images, fonts and interactive
832 functions are not initiated. The module "learns" offset and sizes of
833 used objects, and can process them faster, but at the same time the
834 size of the program grows.
835 use PDF::Reuse;
837 use strict;
838 prInitVars(); # To initiate ALL global variables and tables
839 # prInitVars(1); # To make it faster, but more memory consuming
840 $| = 1;
842 print STDOUT "Content-Type: application/pdf \n\n";
843 prFile(); # To send the document uncatalogued to STDOUT
845 prForm('best.pdf');
847 prText(25, 790, 'Dear Mr. Anders Persson');
848 # ...
849 prEnd();
850 If you call this function without parameters all global variables,
852 including the internal tables, are initiated.
853 prAltJpeg - import a low-res jpeg-image for display and a high-res
855 jpeg-image for printing
856 prAltJpeg ( $imageData, $width, $height, $format, $altImageData, $altWidth, $altHeight, $altFormat )
857 $imageData contains 1 single jpeg-image. $width and $height also have
859 to be specified. $format indicates the format the image data takes: 0
860 for file, 1 for binary string. $altImageData etc. follows the same
861 foramt. Returns the $internalName
862 use PDF::Reuse;
864 use Image::Info qw(image_info dim);
865 use strict;
866 my $file = 'myImage.jpg';
868 my $info = image_info($file);
869 my ($width, $height) = dim($info); # Get the dimensions
870 my $colortype = $info->{color_type}; # get color space
871 my $alt_file = 'myImage.jpg';
873 my $alt_info = image_info($alt_file);
874 my ($alt_width, $alt_height) = dim($alt_info);
875 prFile('myFile.pdf');
877 my $intName = prAltJpeg("$file", # Define the image
878 $width, # in the document
879 $height,
880 0,
881 "$alt_file",
882 $alt_width,
883 $alt_height,
884 0);
885 my $str = "q\n";
887 $str .= "$width 0 0 $height 10 10 cm\n";
888 $str .= "/$intName Do\n";
889 $str .= "Q\n";
890 prAdd($str);
891 prEnd();
892 prJpeg - import a jpeg-image
894 prJpeg ( $imageData, $width, $height, $format )
895 $imageData contains 1 single jpeg-image. $width and $height also have
897 to be specified. $format indicates the format the image data takes: 0
898 for file, 1 for binary string. Returns the $internalName
899 use PDF::Reuse;
901 use Image::Info qw(image_info dim);
902 use strict;
903 my $file = 'myImage.jpg';
905 my $info = image_info($file);
906 my ($width, $height) = dim($info); # Get the dimensions
907 prFile('myFile.pdf');
909 my $intName = prJpeg("$file", # Define the image
910 $width, # in the document
911 $height,
912 0);
913 my $str = "q\n";
915 $str .= "$width 0 0 $height 10 10 cm\n";
916 $str .= "/$intName Do\n";
917 $str .= "Q\n";
918 prAdd($str);
919 prEnd();
920 This is a little like an extra or reserve routine to add images to the
922 document. The most simple way is to use prImage()
923 prJs - add JavaScript
925 prJs ( $string|$fileName )
926 To add JavaScript to your new document. $string has to consist only of
928 JavaScript functions: function a (..){ ... } function b (..) { ...} and
929 so on If $string doesn't contain '{', $string is interpreted as a
930 filename. In that case the file has to consist only of JavaScript
931 functions.
932 See "Remarks about JavaScript"
934 prLink - add a hyper link
936 prLink( { page => $pageNo, # Starting with 1 !
937 x => $x,
938 y => $y,
939 width => $width,
940 height => $height,
941 URI => $URI } );
942 You can also call prLink like this:
944 prLink($page, $x, $y, $width, $height, $URI);
946 You have to put prLink after prFile and before the sentences where its'
948 page is created. The links are created at the page-breaks. If the page
949 is already created, no new link will be inserted.
950 Here is an example where the links of a 4 page document are preserved,
952 and a link is added at the end of the document. We assume that there is
953 some suitable text at that place (x = 400, y = 350):
954 use strict;
956 use PDF::Reuse;
957 prFile('test.pdf');
959 prLink( {page => 4,
961 x => 400,
962 y => 350,
963 width => 105,
964 height => 15,
965 URI => 'http://www.purelyInvented.com/info.html' } );
966 prDoc('fourPages.pdf');
968 prEnd();
970 ( If you are creating each page of a document separately, you can also
972 use 'hyperLink' from PDF::Reuse::Util. Then you get an external text in
973 Helvetica-Oblique, underlined and in blue.
974 use strict;
976 use PDF::Reuse;
977 use PDF::Reuse::Util;
978 prFile('test.pdf');
980 prForm('template.pdf', 5);
981 my ($from, $pos) = prText(25, 700, 'To get more information ');
982 $pos = hyperLink( $pos, 700, 'Press this link',
984 'http://www.purelyInvented.com/info.html' );
985 ($from, $pos) = prText( $pos, 700, ' And get connected');
986 prEnd();
987 'hyperLink' has a few parameters: $x, $y, $textToBeShown, $hyperLink
989 and $fontSize (not shown in the example). It returns current
990 x-position. )
991 prLog - add a string to the log
993 prLog ( $string )
994 Adds whatever you want to the current log (a reference No, a
996 commentary, a tag ?) A log has to be active see prLogDir()
997 Look at "Using the template" and "Restoring the document from the log"
999 in the tutorial for an example.
1000 prLogDir - set directory for the log
1002 prLogDir ( $directory )
1003 Sets a directory for the logs and activates the logging. A little log
1005 file is created for each PDF-file. Normally it should be much, much
1006 more compact then the PDF-file, and it should be possible to restore or
1007 verify a document with the help of it. (Of course you could compress or
1008 store the logs in a database to save even more space.)
1009 use PDF::Reuse;
1011 use strict;
1012 prDocDir('C:/temp/doc');
1014 prLogDir('C:/run');
1015 prFile('myFile.pdf');
1017 prForm('best.pdf');
1018 prText(25, 790, 'Dear Mr. Anders Persson');
1019 # ...
1020 prEnd();
1021 In this example a log file with the name 'myFile.pdf.dat' is created in
1023 the directory 'C:\run'. If that directory doesn't exist, the system
1024 tries to create it. (But, just as mkdir does, it only creates the last
1025 level in a directory tree.)
1026 prMbox - define the format (MediaBox) for a new page.
1028 prMbox ( $lowerLeftX, $lowerLeftY, $upperRightX, $upperRightY )
1029 If the function or the parameters are missing, they are set to 0, 0,
1031 595, 842 points respectively. Only for new pages. Pages created with
1032 prDoc and prSinglePage keep their media boxes unchanged.
1033 See prForm() for an example.
1035 prPage - create/insert a page
1037 prPage ($noLog)
1038 Don't use the optional parameter, it is only used internally, not to
1040 clutter the log, when automatic page breaks are made.
1041 See prForm() for an example.
1043 prSinglePage - take single pages, one by one, from an old document
1045 prSinglePage($file, $pageNumber)
1046 $pageNumber is optional. If not given, next page is assumed Returns
1048 number of remaining pages. This function is a variant of prDoc for
1049 single pages, with the addition that it has a counter of last page
1050 read, and total number of pages of the old document, so it can be used
1051 to loop through a document.
1052 To add a form, image and page number to each page of a document (The
1054 document Battery.pdf is cropped so each page is fairly small) You
1055 could also have used prDoc, but only if you knew in advance the number
1056 of pages of the old document
1057 use PDF::Reuse;
1059 use PDF::Reuse::Util;
1060 use strict;
1061 prFile('test.pdf');
1063 my $pageNumber = 0;
1065 my $left = 1; # Every valid PDF-document has at least 1 page,
1066 # so that can be assumed
1067 while ($left)
1069 { $pageNumber++;
1070 prForm( { file =>'Words.pdf',
1071 page => 5,
1072 x => 150,
1073 y => 150} );
1074 prImage( { file =>'Media.pdf',
1076 page => 6,
1077 imageNo => 1,
1078 x => 450,
1079 y => 450 } );
1080 blackText();
1081 prText( 360, 250, $pageNumber);
1082 $left = prSinglePage('Battery.pdf');
1083 }
1084 prEnd;
1086 prSinglePage creates a new page from an old document and adds new
1088 content (to the array of streams of that page). Most often you can add
1089 new contents to the page like the example above, and it works fine, but
1090 sometimes you get surprises. There can e.g. be instructions in the
1091 earlier contents to make filling color white, and then you will
1092 probably not see added new text. That is why
1093 PDF::Reuse::Util::blackText() is used in the example. There can be
1094 other instructions like moving or rotating the user space. Also new
1095 contents can end up outside the crop-box. Of course all new programs
1096 should be tested. If prSinglePage can't be used, try to use prForm
1097 followed by prPage instead.
1098 prStrWidth - calculate the string width
1100 prStrWidth($string, $font, $fontSize)
1101 Returns string width in points. Should be used in conjunction with one
1103 of these predefined fonts of Acrobat/Reader: Times-Roman, Times-Bold,
1104 Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique,
1105 Courier-BoldOblique, Helvetica, Helvetica-Bold, Helvetica-Oblique,
1106 Helvetica-BoldOblique or with a TrueType font embedded with prTTFont.
1107 If some other font is given, Helvetica is used, and the returned value
1108 will at the best be approximate.
1109 prText - add a text-string
1111 prText ( $x, $y, $string, $align, $rotation )
1112 Puts $string at position $x, $y Returns 1 in scalar context. Returns
1114 ($xFrom, $xTo) in list context. $xTo will not be defined together with
1115 a rotation. prStrWidth() is used to calculate the length of the
1116 strings, so only the predefined fonts together with Acrobat/Reader, or
1117 embedded TrueType fonts will give reliable values for $xTo.
1118 $align can be 'left' (= default), 'center' or 'right'. The parameter is
1120 optional.
1121 $rotation can be a degree 0 - 360, 'q1', 'q2' or 'q3'. Also optional.
1123 Current font and font size are used. (If you use prAdd() before this
1125 function, many other things could also influence the text.)
1126 use strict;
1128 use PDF::Reuse;
1129 prFile('test.pdf');
1131 #####################################
1133 # Use a "curser" ($pos) along a line
1134 #####################################
1135 my ($from, $pos) = prText(25, 800, 'First write this. ');
1137 ($from, $pos) = prText($pos, 800, 'Then write this. ');
1138 prText($pos, 800, 'Finally write this.');
1139 #####################################
1141 # Right adjust and center sentences
1142 #####################################
1143 prText( 200, 750, 'A short sentence', 'right');
1145 prText( 200, 735, 'This is a longer sentence', 'right');
1146 prText( 200, 720, 'A word', 'right');
1147 prText( 200, 705, 'Centered around a point 200 points from the left', 'center');
1149 prText( 200, 690, 'The same center', 'center');
1150 prText( 200, 675, '->.<-', 'center');
1151 ############
1153 # Rotation
1154 ############
1155 prText( 200, 550, ' Rotate 0 degrees','', 0);
1157 prText( 200, 550, ' Rotate 60 degrees','', 60);
1158 prText( 200, 550, ' Rotate 120 degrees','', 120);
1159 prText( 200, 550, ' Rotate 180 degrees','', 180);
1160 prText( 200, 550, ' Rotate 240 degrees','', 240);
1161 prText( 200, 550, ' Rotate 300 degrees','', 300);
1162 prText( 400, 430, 'Rotate 90 degrees clock-wise','','q1');
1164 prText( 400, 430, 'Rotate 180 degrees clock-wise','', 'q2');
1165 prText( 400, 430, 'Rotate 270 degrees clock-wise','', 'q3');
1166 ##########################
1168 # Rotate and right adjust
1169 ##########################
1170 prText( 200, 230, 'Rotate 90 degrees clock-wise ra->','right','q1');
1172 prText( 200, 230, 'Rotate 180 degrees clock-wise ra->','right', 'q2');
1173 prText( 200, 230, 'Rotate 270 degrees clock-wise ra->','right', 'q3');
1174 prEnd();
1176 prTTFont - select and embed a TrueType font
1178 prTTFont ( "/path/to/font/file.ttf" )
1179 This function is equivalent to "prFont" except that rather than
1181 restricting you to the list of core built-in fonts, it allows you to
1182 select an external TrueType font file and have it embedded in your PDF
1183 document. Using TrueType fonts also enables the "prText" function to
1184 accept UTF-8 strings, which allows you to use characters outside the
1185 Mac-Roman/Win-ANSI character sets used by the built-in fonts.
1186 You can specify the same font path multiple times in one document and
1188 only one copy will be embedded. Alternatively, "prTTFont" returns an
1189 identifier which can be used to select the same font again:
1190 my $arial = prTTFont('/path/to/Arial.ttf');
1192 prFontSize(20);
1193 prText(20, 700, 'Some text in Arial');
1194 #
1195 # ... later ...
1196 #
1197 prPage();
1198 prTTFont($arial);
1199 prFontSize(12);
1200 prText(20, 700, 'Some more text in Arial');
1201 #
1202 # to pass a UTF8 string to prText
1203 #
1204 prText(20, 675, "T\x{113}n\x{101} koutou"); # T?n? Koutou
1205 In list context this function returns $internalName, $externalName,
1207 $oldInternalName, $oldExternalname. The first two variables refer to
1208 the current font, the last two refer to the font before the change. In
1209 scalar context only $internalName is returned.
1210 Note: To use this function, you must have the Font::TTF and Text::PDF
1212 modules installed.
1213
1215 prBar - define and paint bars for bar fonts
1216 prBar ($x, $y, $string)
1217 Prints a bar font pattern at the current page. Returns $internalName
1219 for the font. $x and $y are coordinates in points and $string should
1220 consist of the characters '0', '1' and '2' (or 'G'). '0' is a white
1221 bar, '1' is a dark bar. '2' and 'G' are dark, slightly longer bars,
1222 guard bars. You can use e.g. GD::Barcode or one module in that group
1223 to calculate the bar code pattern. prBar "translates" the pattern to
1224 white and black bars.
1225 use PDF::Reuse;
1227 use GD::Barcode::Code39;
1228 use strict;
1229 prFile('myFile.pdf');
1231 my $oGdB = GD::Barcode::Code39->new('JOHN DOE');
1232 my $sPtn = $oGdB->barcode();
1233 prBar(100, 600, $sPtn);
1234 prEnd();
1235 Internally the module uses a font for the bars, so you might want to
1237 change the font size before calling this function. In that case, use
1238 prFontSize() . If you call this function without arguments it
1239 defines the bar font but does not write anything to the current page.
1240 An easier and often better way to produce bar codes is to use
1242 PDF::Reuse::Barcode. Look at that module!
1243 prCid - define time stamp/check id
1245 prCid ( $timeStamp )
1246 An internal function. Don't bother about it. It is used in automatic
1248 routines when you want to restore a document. It gives modification
1249 time of the next PDF-file or JavaScript. See "Restoring a document
1250 from the log" in the tutorial for more about the time stamp
1251 prId - define id-string of a PDF document
1253 prId ( $string )
1254 An internal function. Don't bother about it. It is used e.g. when a
1256 document is restored and an id has to be set, not calculated.
1257 prIdType - define id-type
1259 prIdType ( $string )
1260 An internal function. Avoid using it. $string could be "Rep" for
1262 replace or "None" to avoid calculating an id.
1263 Normally you don't use this function. Then an id is calculated with
1265 the help of Digest::MD5::md5_hex and some data from the run.
1266 prTouchUp - make changes and reuse more difficult
1268 prTouchUp (1);
1269 By default and after you have issued prTouchUp(1), you can change the
1271 document with the TouchUp tool from within Acrobat. If you want to
1272 switch off this possibility, you use prTouchUp() without any
1273 parameter. Then the user shouldn't be able to change anything
1274 graphic by mistake. He has to do something premeditated and perhaps
1275 with a little effort. He could still save it as Postscript and
1276 redistill, or he could remove or add single pages. (Here is a strong
1277 reason why the log files, and perhaps also check sums, are needed.
1278 It would be very difficult to forge a document unless the forger also
1279 has access to your computer and knows how the check sums are
1280 calculated.)
1281 Avoid to switch off the TouchUp tool for your templates. It creates
1283 an extra level within the PDF-documents . Use this function for your
1284 final documents.
1285 See "Using the template" in the tutorial for an example.
1287 This function works for pages created with prPage, but mot with prDoc
1289 and prSinglePage, So it is more or less deprecated as these function
1290 have developed.
1291 (To encrypt your documents: use the batch utility within Acrobat)
1293 prVers - check version of log and program
1295 prVers ( $versionNo )
1296 To check version of this module in case a document has to be
1298 restored.
1299
1301 PDF::Reuse::Tutorial
1302 PDF::Reuse::Barcode
1303 PDF::Reuse::OverlayChart
1304 To program with PDF-operators, look at "The PDF-reference Manual" which
1306 probably is possible to download from
1307 http://partners.adobe.com/asn/tech/pdf/specifications.jsp Look
1308 especially at chapter 4 and 5, Graphics and Text, and the Operator
1309 summary.
1310 Technical Note # 5186 contains the "Acrobat JavaScript Object
1312 Specification". I downloaded it from
1313 http://partners.adobe.com/asn/developer/technotes/acrobatpdf.html
1314 If you are serious about producing PDF-files, you probably need Adobe
1316 Acrobat sooner or later. It has a price tag. Other good programs are
1317 GhostScript and GSview. I got them via
1318 http://www.cs.wisc.edu/~ghost/index.html Sometimes they can replace
1319 Acrobat. A nice little detail is e.g. that GSview shows the x- and
1320 y-coordinates better then Acrobat. If you need to convert HTML-files to
1321 PDF, HTMLDOC is a possible tool. Download it from http://www.easysw.com
1322 . A simple tool for vector graphics is Mayura Draw 2.04, download it
1323 from http://www.mayura.com. It is free. I have used it to produce the
1324 graphic OO-code in the tutorial. It produces postscript which the
1325 Acrobat Distiller (you get it together with Acrobat) or Ghostscript can
1326 convert to PDF.(The commercial product, Mayura Draw 4.01 or something
1327 higher can produce PDF-files straight away)
1328 If you want to import jpeg-images, you might need
1330 Image::Info
1332 To get definitions for e.g. colors, take them from
1334 PDF::API2::Util
1336
1338 Meta data, info and many other features of the PDF-format have not been
1339 implemented in this module.
1340 Many things can be added afterwards, after creating the files. If you
1342 e.g. need files to be encrypted, you can use a standard batch routine
1343 within Adobe Acrobat.
1344
1346 Martin Langhoff, Matisse Enzer, Yunliang Yu and others who have
1347 contributed with code, suggestions and error reports.
1348 Grant McLean has implemented font embedding by grafting Font::TTF and
1350 Text::PDF::TTFont0 onto the PDF::Reuse API. He has written the embedded
1351 packages PDF::Reuse::DocProxy and PDF::Reuse::TTFont.
1352 The functionality of prDoc and prSinglePage to include new contents was
1354 developed for a specific task with support from the Electoral Enrolment
1355 Centre, Wellington, New Zealand
1356
1358 http://groups.google.com/group/PDF-Reuse
1359
1361 Lars Lundberg larslund@cpan.org Chris Nighswonger cnighs@cpan.org
1362
1364 Copyright (C) 2003 - 2004 Lars Lundberg, Solidez HB. Copyright (C)
1365 2005 Karin Lundberg. Copyright (C) 2006 - 2010 Lars Lundberg, Solidez
1366 HB. Copyright (C) 2010 - 2014 Chris Nighswonger This program is free
1367 software; you can redistribute it and/or modify it under the same terms
1368 as Perl itself.
1369
1371 You get this module free as it is, but nothing is guaranteed to work,
1372 whatever implicitly or explicitly stated in this document, and
1373 everything you do, you do at your own risk - I will not take
1374 responsibility for any damage, loss of money and/or health that may
1375 arise from the use of this module.
1376perl v5.36.0 2023-01-20 PDF::Reuse(3)