1Reuse(3) User Contributed Perl Documentation 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. An other 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 prJpeg - import a jpeg-image
855 prJpeg ( $imageFile, $width, $height )
856 $imageFile contains 1 single jpeg-image. $width and $height also have
858 to be specified. Returns the $internalName
859 use PDF::Reuse;
861 use Image::Info qw(image_info dim);
862 use strict;
863 my $file = 'myImage.jpg';
865 my $info = image_info($file);
866 my ($width, $height) = dim($info); # Get the dimensions
867 prFile('myFile.pdf');
869 my $intName = prJpeg("$file", # Define the image
870 $width, # in the document
871 $height);
872 my $str = "q\n";
874 $str .= "$width 0 0 $height 10 10 cm\n";
875 $str .= "/$intName Do\n";
876 $str .= "Q\n";
877 prAdd($str);
878 prEnd();
879 This is a little like an extra or reserve routine to add images to the
881 document. The most simple way is to use prImage()
882 prJs - add JavaScript
884 prJs ( $string|$fileName )
885 To add JavaScript to your new document. $string has to consist only of
887 JavaScript functions: function a (..){ ... } function b (..) { ...} and
888 so on If $string doesn't contain '{', $string is interpreted as a
889 filename. In that case the file has to consist only of JavaScript
890 functions.
891 See "Remarks about JavaScript"
893 prLink - add a hyper link
895 prLink( { page => $pageNo, # Starting with 1 !
896 x => $x,
897 y => $y,
898 width => $width,
899 height => $height,
900 URI => $URI } );
901 You can also call prLink like this:
903 prLink($page, $x, $y, $width, $height, $URI);
905 You have to put prLink after prFile and before the sentences where its'
907 page is created. The links are created at the page-breaks. If the page
908 is already created, no new link will be inserted.
909 Here is an example where the links of a 4 page document are preserved,
911 and a link is added at the end of the document. We assume that there is
912 some suitable text at that place (x = 400, y = 350):
913 use strict;
915 use PDF::Reuse;
916 prFile('test.pdf');
918 prLink( {page => 4,
920 x => 400,
921 y => 350,
922 width => 105,
923 height => 15,
924 URI => 'http://www.purelyInvented.com/info.html' } );
925 prDoc('fourPages.pdf');
927 prEnd();
929 ( If you are creating each page of a document separately, you can also
931 use 'hyperLink' from PDF::Reuse::Util. Then you get an external text in
932 Helvetica-Oblique, underlined and in blue.
933 use strict;
935 use PDF::Reuse;
936 use PDF::Reuse::Util;
937 prFile('test.pdf');
939 prForm('template.pdf', 5);
940 my ($from, $pos) = prText(25, 700, 'To get more information ');
941 $pos = hyperLink( $pos, 700, 'Press this link',
943 'http://www.purelyInvented.com/info.html' );
944 ($from, $pos) = prText( $pos, 700, ' And get connected');
945 prEnd();
946 'hyperLink' has a few parameters: $x, $y, $textToBeShown, $hyperLink
948 and $fontSize (not shown in the example). It returns current
949 x-position. )
950 prLog - add a string to the log
952 prLog ( $string )
953 Adds whatever you want to the current log (a reference No, a
955 commentary, a tag ?) A log has to be active see prLogDir()
956 Look at "Using the template" and "Restoring the document from the log"
958 in the tutorial for an example.
959 prLogDir - set directory for the log
961 prLogDir ( $directory )
962 Sets a directory for the logs and activates the logging. A little log
964 file is created for each PDF-file. Normally it should be much, much
965 more compact then the PDF-file, and it should be possible to restore or
966 verify a document with the help of it. (Of course you could compress or
967 store the logs in a database to save even more space.)
968 use PDF::Reuse;
970 use strict;
971 prDocDir('C:/temp/doc');
973 prLogDir('C:/run');
974 prFile('myFile.pdf');
976 prForm('best.pdf');
977 prText(25, 790, 'Dear Mr. Anders Persson');
978 # ...
979 prEnd();
980 In this example a log file with the name 'myFile.pdf.dat' is created in
982 the directory 'C:\run'. If that directory doesn't exist, the system
983 tries to create it. (But, just as mkdir does, it only creates the last
984 level in a directory tree.)
985 prMbox - define the format (MediaBox) for a new page.
987 prMbox ( $lowerLeftX, $lowerLeftY, $upperRightX, $upperRightY )
988 If the function or the parameters are missing, they are set to 0, 0,
990 595, 842 points respectively. Only for new pages. Pages created with
991 prDoc and prSinglePage keep their media boxes unchanged.
992 See prForm() for an example.
994 prPage - create/insert a page
996 prPage ($noLog)
997 Don't use the optional parameter, it is only used internally, not to
999 clutter the log, when automatic page breaks are made.
1000 See prForm() for an example.
1002 prSinglePage - take single pages, one by one, from an old document
1004 prSinglePage($file, $pageNumber)
1005 $pageNumber is optional. If not given, next page is assumed Returns
1007 number of remaining pages. This function is a variant of prDoc for
1008 single pages, with the addition that it has a counter of last page
1009 read, and total number of pages of the old document, so it can be used
1010 to loop through a document.
1011 To add a form, image and page number to each page of a document (The
1013 document Battery.pdf is cropped so each page is fairly small) You
1014 could also have used prDoc, but only if you knew in advance the number
1015 of pages of the old document
1016 use PDF::Reuse;
1018 use PDF::Reuse::Util;
1019 use strict;
1020 prFile('test.pdf');
1022 my $pageNumber = 0;
1024 my $left = 1; # Every valid PDF-document has at least 1 page,
1025 # so that can be assumed
1026 while ($left)
1028 { $pageNumber++;
1029 prForm( { file =>'Words.pdf',
1030 page => 5,
1031 x => 150,
1032 y => 150} );
1033 prImage( { file =>'Media.pdf',
1035 page => 6,
1036 imageNo => 1,
1037 x => 450,
1038 y => 450 } );
1039 blackText();
1040 prText( 360, 250, $pageNumber);
1041 $left = prSinglePage('Battery.pdf');
1042 }
1043 prEnd;
1045 prSinglePage creates a new page from an old document and adds new
1047 content (to the array of streams of that page). Most often you can add
1048 new contents to the page like the example above, and it works fine, but
1049 sometimes you get surprises. There can e.g. be instructions in the
1050 earlier contents to make filling color white, and then you will
1051 probably not see added new text. That is why
1052 PDF::Reuse::Util::blackText() is used in the example. There can be
1053 other instructions like moving or rotating the user space. Also new
1054 contents can end up outside the crop-box. Of course all new programs
1055 should be tested. If prSinglePage can't be used, try to use prForm
1056 followed by prPage instead.
1057 prStrWidth - calculate the string width
1059 prStrWidth($string, $font, $fontSize)
1060 Returns string width in points. Should be used in conjunction with one
1062 of these predefined fonts of Acrobat/Reader: Times-Roman, Times-Bold,
1063 Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique,
1064 Courier-BoldOblique, Helvetica, Helvetica-Bold, Helvetica-Oblique,
1065 Helvetica-BoldOblique or with a TrueType font embedded with prTTFont.
1066 If some other font is given, Helvetica is used, and the returned value
1067 will at the best be approximate.
1068 prText - add a text-string
1070 prText ( $x, $y, $string, $align, $rotation )
1071 Puts $string at position $x, $y Returns 1 in scalar context. Returns
1073 ($xFrom, $xTo) in list context. $xTo will not be defined together with
1074 a rotation. prStrWidth() is used to calculate the length of the
1075 strings, so only the predefined fonts together with Acrobat/Reader, or
1076 embedded TrueType fonts will give reliable values for $xTo.
1077 $align can be 'left' (= default), 'center' or 'right'. The parameter is
1079 optional.
1080 $rotation can be a degree 0 - 360, 'q1', 'q2' or 'q3'. Also optional.
1082 Current font and font size are used. (If you use prAdd() before this
1084 function, many other things could also influence the text.)
1085 use strict;
1087 use PDF::Reuse;
1088 prFile('test.pdf');
1090 #####################################
1092 # Use a "curser" ($pos) along a line
1093 #####################################
1094 my ($from, $pos) = prText(25, 800, 'First write this. ');
1096 ($from, $pos) = prText($pos, 800, 'Then write this. ');
1097 prText($pos, 800, 'Finally write this.');
1098 #####################################
1100 # Right adjust and center sentences
1101 #####################################
1102 prText( 200, 750, 'A short sentence', 'right');
1104 prText( 200, 735, 'This is a longer sentence', 'right');
1105 prText( 200, 720, 'A word', 'right');
1106 prText( 200, 705, 'Centered around a point 200 points from the left', 'center');
1108 prText( 200, 690, 'The same center', 'center');
1109 prText( 200, 675, '->.<-', 'center');
1110 ############
1112 # Rotation
1113 ############
1114 prText( 200, 550, ' Rotate 0 degrees','', 0);
1116 prText( 200, 550, ' Rotate 60 degrees','', 60);
1117 prText( 200, 550, ' Rotate 120 degrees','', 120);
1118 prText( 200, 550, ' Rotate 180 degrees','', 180);
1119 prText( 200, 550, ' Rotate 240 degrees','', 240);
1120 prText( 200, 550, ' Rotate 300 degrees','', 300);
1121 prText( 400, 430, 'Rotate 90 degrees clock-wise','','q1');
1123 prText( 400, 430, 'Rotate 180 degrees clock-wise','', 'q2');
1124 prText( 400, 430, 'Rotate 270 degrees clock-wise','', 'q3');
1125 ##########################
1127 # Rotate and right adjust
1128 ##########################
1129 prText( 200, 230, 'Rotate 90 degrees clock-wise ra->','right','q1');
1131 prText( 200, 230, 'Rotate 180 degrees clock-wise ra->','right', 'q2');
1132 prText( 200, 230, 'Rotate 270 degrees clock-wise ra->','right', 'q3');
1133 prEnd();
1135 prTTFont - select and embed a TrueType font
1137 prTTFont ( "/path/to/font/file.ttf" )
1138 This function is equivalent to "prFont" except that rather than
1140 restricting you to the list of core built-in fonts, it allows you to
1141 select an external TrueType font file and have it embedded in your PDF
1142 document. Using TrueType fonts also enables the "prText" function to
1143 accept UTF-8 strings, which allows you to use characters outside the
1144 Mac-Roman/Win-ANSI character sets used by the built-in fonts.
1145 You can specify the same font path multiple times in one document and
1147 only one copy will be embedded. Alternatively, "prTTFont" returns an
1148 identifier which can be used to select the same font again:
1149 my $arial = prTTFont('/path/to/Arial.ttf');
1151 prFontSize(20);
1152 prText(20, 700, 'Some text in Arial');
1153 #
1154 # ... later ...
1155 #
1156 prPage();
1157 prTTFont($arial);
1158 prFontSize(12);
1159 prText(20, 700, 'Some more text in Arial');
1160 #
1161 # to pass a UTF8 string to prText
1162 #
1163 prText(20, 675, "T\x{113}n\x{101} koutou"); # T?n? Koutou
1164 In list context this function returns $internalName, $externalName,
1166 $oldInternalName, $oldExternalname. The first two variables refer to
1167 the current font, the last two refer to the font before the change. In
1168 scalar context only $internalName is returned.
1169 Note: To use this function, you must have the Font::TTF and Text::PDF
1171 modules installed.
1172
1174 prBar - define and paint bars for bar fonts
1175 prBar ($x, $y, $string)
1176 Prints a bar font pattern at the current page. Returns $internalName
1178 for the font. $x and $y are coordinates in points and $string should
1179 consist of the characters '0', '1' and '2' (or 'G'). '0' is a white
1180 bar, '1' is a dark bar. '2' and 'G' are dark, slightly longer bars,
1181 guard bars. You can use e.g. GD::Barcode or one module in that group
1182 to calculate the bar code pattern. prBar "translates" the pattern to
1183 white and black bars.
1184 use PDF::Reuse;
1186 use GD::Barcode::Code39;
1187 use strict;
1188 prFile('myFile.pdf');
1190 my $oGdB = GD::Barcode::Code39->new('JOHN DOE');
1191 my $sPtn = $oGdB->barcode();
1192 prBar(100, 600, $sPtn);
1193 prEnd();
1194 Internally the module uses a font for the bars, so you might want to
1196 change the font size before calling this function. In that case, use
1197 prFontSize() . If you call this function without arguments it
1198 defines the bar font but does not write anything to the current page.
1199 An easier and often better way to produce bar codes is to use
1201 PDF::Reuse::Barcode. Look at that module!
1202 prCid - define time stamp/check id
1204 prCid ( $timeStamp )
1205 An internal function. Don't bother about it. It is used in automatic
1207 routines when you want to restore a document. It gives modification
1208 time of the next PDF-file or JavaScript. See "Restoring a document
1209 from the log" in the tutorial for more about the time stamp
1210 prId - define id-string of a PDF document
1212 prId ( $string )
1213 An internal function. Don't bother about it. It is used e.g. when a
1215 document is restored and an id has to be set, not calculated.
1216 prIdType - define id-type
1218 prIdType ( $string )
1219 An internal function. Avoid using it. $string could be "Rep" for
1221 replace or "None" to avoid calculating an id.
1222 Normally you don't use this function. Then an id is calculated with
1224 the help of Digest::MD5::md5_hex and some data from the run.
1225 prTouchUp - make changes and reuse more difficult
1227 prTouchUp (1);
1228 By default and after you have issued prTouchUp(1), you can change the
1230 document with the TouchUp tool from within Acrobat. If you want to
1231 switch off this possibility, you use prTouchUp() without any
1232 parameter. Then the user shouldn't be able to change anything
1233 graphic by mistake. He has to do something premeditated and perhaps
1234 with a little effort. He could still save it as Postscript and
1235 redistill, or he could remove or add single pages. (Here is a strong
1236 reason why the log files, and perhaps also check sums, are needed.
1237 It would be very difficult to forge a document unless the forger also
1238 has access to your computer and knows how the check sums are
1239 calculated.)
1240 Avoid to switch off the TouchUp tool for your templates. It creates
1242 an extra level within the PDF-documents . Use this function for your
1243 final documents.
1244 See "Using the template" in the tutorial for an example.
1246 This function works for pages created with prPage, but mot with prDoc
1248 and prSinglePage, So it is more or less deprecated as these function
1249 have developed.
1250 (To encrypt your documents: use the batch utility within Acrobat)
1252 prVers - check version of log and program
1254 prVers ( $versionNo )
1255 To check version of this module in case a document has to be
1257 restored.
1258
1260 PDF::Reuse::Tutorial
1261 PDF::Reuse::Barcode
1262 PDF::Reuse::OverlayChart
1263 To program with PDF-operators, look at "The PDF-reference Manual" which
1265 probably is possible to download from
1266 http://partners.adobe.com/asn/tech/pdf/specifications.jsp Look
1267 especially at chapter 4 and 5, Graphics and Text, and the Operator
1268 summary.
1269 Technical Note # 5186 contains the "Acrobat JavaScript Object
1271 Specification". I downloaded it from
1272 http://partners.adobe.com/asn/developer/technotes/acrobatpdf.html
1273 If you are serious about producing PDF-files, you probably need Adobe
1275 Acrobat sooner or later. It has a price tag. Other good programs are
1276 GhostScript and GSview. I got them via
1277 http://www.cs.wisc.edu/~ghost/index.html Sometimes they can replace
1278 Acrobat. A nice little detail is e.g. that GSview shows the x- and
1279 y-coordinates better then Acrobat. If you need to convert HTML-files to
1280 PDF, HTMLDOC is a possible tool. Download it from http://www.easysw.com
1281 . A simple tool for vector graphics is Mayura Draw 2.04, download it
1282 from http://www.mayura.com. It is free. I have used it to produce the
1283 graphic OO-code in the tutorial. It produces postscript which the
1284 Acrobat Distiller (you get it together with Acrobat) or Ghostscript can
1285 convert to PDF.(The commercial product, Mayura Draw 4.01 or something
1286 higher can produce PDF-files straight away)
1287 If you want to import jpeg-images, you might need
1289 Image::Info
1291 To get definitions for e.g. colors, take them from
1293 PDF::API2::Util
1295
1297 Meta data, info and many other features of the PDF-format have not been
1298 implemented in this module.
1299 Many things can be added afterwards, after creating the files. If you
1301 e.g. need files to be encrypted, you can use a standard batch routine
1302 within Adobe Acrobat.
1303
1305 Martin Langhoff, Matisse Enzer, Yunliang Yu and others who have
1306 contributed with code, suggestions and error reports.
1307 Grant McLean has implemented font embedding by grafting Font::TTF and
1309 Text::PDF::TTFont0 onto the PDF::Reuse API. He has written the embedded
1310 packages PDF::Reuse::DocProxy and PDF::Reuse::TTFont.
1311 The functionality of prDoc and prSinglePage to include new contents was
1313 developed for a specific task with support from the Electoral Enrolment
1314 Centre, Wellington, New Zealand
1315
1317 http://groups.google.com/group/PDF-Reuse
1318
1320 Lars Lundberg larslund@cpan.org
1321
1323 Copyright (C) 2003 - 2004 Lars Lundberg, Solidez HB. Copyright (C)
1324 2005 Karin Lundberg. Copyright (C) 2006 - Lars Lundberg, Solidez HB.
1325 This program is free software; you can redistribute it and/or modify it
1326 under the same terms as Perl itself.
1327
1329 You get this module free as it is, but nothing is guaranteed to work,
1330 whatever implicitly or explicitly stated in this document, and
1331 everything you do, you do at your own risk - I will not take
1332 responsibility for any damage, loss of money and/or health that may
1333 arise from the use of this module.
1334perl v5.10.1 2010-11-12 Reuse(3)