Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PDF::Create(3)	      User Contributed Perl Documentation	PDF::Create(3)

NAME
       PDF::Create - Create PDF	files.

VERSION
       Version 1.35

DESCRIPTION
       "PDF::Create" allows you	to create PDF document using a number of
       primitives.The result is	as a PDF file or stream. PDF stands for
       Portable	Document Format.

       Documents can have several pages, a  table of content, an information
       section and many	other PDF elements.

SYNOPSIS
       "PDF::Create" provides an easy module to	create PDF output from your
       perl script.  It	is designed to be easy to use and simple to install
       and maintain. It	provides a couple of subroutines to handle text,
       fonts, images and drawing primitives. Simple documents are easy to
       create with the supplied	routines.

       In addition to be reasonable simple "PDF::Create" is written in pure
       Perl and	has no external	 dependencies  (libraries,  other modules,
       etc.). It should	run on any platform where perl is available.

       For complex  stuff  some	understanding of the underlying	Postscript/PDF
       format is necessary. In this case it might be better go with the	more
       complete	PDF::API2 modules to gain more features	at the expense of a
       steeper learning	curve.

       Example PDF creation with "PDF::Create":

	   use strict; use warnings;
	   use PDF::Create;

	   my $pdf = PDF::Create->new(
	       'filename'     => 'sample.pdf',
	       'Author'	      => 'John Doe',
	       'Title'	      => 'Sample PDF',
	       'CreationDate' => [ localtime ]
	   );

	   # Add a A4 sized page
	   my $root = $pdf->new_page('MediaBox'	=> $pdf->get_page_size('A4'));

	   # Add a page	which inherits its attributes from $root
	   my $page1 = $root->new_page;

	   # Prepare a font
	   my $font = $pdf->font('BaseFont' => 'Helvetica');

	   # Prepare a Table of	Content
	   my $toc = $pdf->new_outline('Title' => 'Title Page',	'Destination' => $page1);

	   # Write some	text
	   $page1->stringc($font, 40, 306, 426,	'PDF::Create');
	   $page1->stringc($font, 20, 306, 396,	"version $PDF::Create::VERSION");
	   $page1->stringc($font, 20, 306, 300,	'by John Doe <john.doe@example.com>');

	   # Add another page
	   my $page2 = $root->new_page;

	   # Draw some lines
	   $page2->line(0, 0,	592, 840);
	   $page2->line(0, 840,	592, 0);

	   $toc->new_outline('Title' =>	'Second	Page', 'Destination' =>	$page2);

	   # Close the file and	write the PDF
	   $pdf->close;

CONSTRUCTOR
       The method "new(%params)" create	a new pdf structure for	your PDF. It
       returns an object handle	which can be used to add more stuff to the
       PDF. The	 parameter keys	to the constructor are detailed	as below:

	   +--------------+------------------------------------------------------------+
	   | Key	  | Description						       |
	   +--------------+------------------------------------------------------------+
	   |		  |							       |
	   | filename	  | Destination	file that will contain resulting PDF or	'-' for|
	   |		  | stdout.						       |
	   |		  |							       |
	   | fh		  | Already opened filehandle that will	contain	resulting PDF. |
	   |		  |							       |
	   | Version	  | PDF	Version	to claim, can be 1.0 to	1.3 (default: 1.       |
	   |		  |							       |
	   | PageMode	  | How	the document should appear when	opened.Possible	values |
	   |		  | UseNone (Default), UseOutlines, UseThumbs and FullScreen   |
	   |		  |							       |
	   | Author	  | The	name of	the person who created this document.	       |
	   |		  |							       |
	   | Creator	  | If the document was	converted into a PDF document from     |
	   |		  | another form, this is the name of the application that     |
	   |		  | created the	document.				       |
	   |		  |							       |
	   | Title	  | The	title of the document.				       |
	   |		  |							       |
	   | Subject	  | The	subject	of the document.			       |
	   |		  |							       |
	   | Keywords	  | Keywords associated	with the document.		       |
	   |		  |							       |
	   | CreationDate | The	date the document was created.This is passed as	an     |
	   |		  | anonymous array in the same	format as localtime returns.   |
	   |		  |							       |
	   | Debug	  | The	debug level, defaults to 0. It can be any positive     |
	   |		  | integers.						       |
	   |		  |							       |
	   +--------------+------------------------------------------------------------+

       Example:

	   my $pdf = PDF::Create->new(
	       'filename'     => 'sample.pdf',
	       'Version'      => 1.2,
	       'PageMode'     => 'UseOutlines',
	       'Author'	      => 'John Doe',
	       'Title'	      => 'My Title',
	       'CreationDate' => [ localtime ]
	   );

       If you are writing a CGI	you can	send your PDF on the fly to stdout /
       directly	to the browser using '-' as filename.

       CGI Example:

	 use CGI;
	 use PDF::Create;

	 print CGI::header(-type => 'application/x-pdf', -attachment =>	'sample.pdf');
	 my $pdf = PDF::Create->new(
	     'filename'	    => '-',
	     'Author'	    => 'John Doe',
	     'Title'	    => 'My title',
	     'CreationDate' => [ localtime ]
	 );

METHODS
   new_page(%params)
       Add a page to the document using	the given parameters. "new_page" must
       be called first to initialize a root page, used as model	for further
       pages.Returns a handle to the newly created page. Parameters can	be:

	   +-----------+---------------------------------------------------------------+
	   | Key       | Description						       |
	   +-----------+---------------------------------------------------------------+
	   |	       |							       |
	   | Parent    | The parent of this page in the	pages tree.This	is page	object.|
	   |	       |							       |
	   | Resources | Resources required by this page.			       |
	   |	       |							       |
	   | MediaBox  | Rectangle specifying the natural size of the page,for example |
	   |	       | the dimensions	of an A4 sheet of paper. The coordinates are   |
	   |	       | measured in default user space	units It must be the reference |
	   |	       | of 4 values array.You can use C<get_page_size>	to get to get  |
	   |	       | the size of standard paper sizes.C<get_page_size> knows about |
	   |	       | A0-A6,	A4L (landscape), Letter, Legal,	Broadsheet, Ledger,    |
	   |	       | Tabloid, Executive and	36x36.				       |
	   | CropBox   | Rectangle specifying the default clipping region for the page |
	   |	       | when displayed	or printed. The	default	is the value of	the    |
	   |	       | MediaBox.						       |
	   |	       |							       |
	   | ArtBox    | Rectangle specifying  an area	of the page to be used when    |
	   |	       | placing PDF content into another application. The default is  |
	   |	       | the value of the CropBox. [PDF	1.3]			       |
	   |	       |							       |
	   | TrimBox   | Rectangle specifying the  intended finished size of the page  |
	   |	       | (for example, the dimensions of an A4 sheet of	paper).In some |
	   |	       | cases,the MediaBox will be a larger rectangle,	which includes |
	   |	       | printing instructions,	cut marks or other content.The default |
	   |	       | is the	value of the CropBox. [PDF 1.3].		       |
	   |	       |							       |
	   | BleedBox  | Rectangle specifying the region to which all page content     |
	   |	       | should	be clipped if the page is being	output in a production |
	   |	       | environment. In such environments, a bleed area is desired,   |
	   |	       | to accommodate	physical limitations of	cutting, folding, and  |
	   |	       | trimming  equipment. The actual  printed page may  include    |
	   |	       | printer's marks that fall outside the bleed box. The default  |
	   |	       | is the	value of the CropBox.[PDF 1.3]			       |
	   |	       |							       |
	   | Rotate    | Specifies the number of degrees the page should be rotated    |
	   |	       | clockwise when	it is displayed	or printed. This value must be |
	   |	       | zero (the default) or a multiple of 90. The entire page,      |
	   |	       | including contents is rotated.				       |
	   |	       |							       |
	   +-----------+---------------------------------------------------------------+

       Example:

	   my $a4 = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );

	   my $page1 = $a4->new_page;
	   $page1->string($f1, 20, 306,	396, "some text	on page	1");

	   my $page2 = $a4->new_page;
	   $page2->string($f1, 20, 306,	396, "some text	on page	2");

   font(%params)
       Prepare a font using the	given arguments. This font will	be added to
       the document only if it is used at least	once before the	close method
       is called.Parameters are	listed below:

	   +----------+----------------------------------------------------------------+
	   | Key      |	Description						       |
	   +----------+----------------------------------------------------------------+
	   | Subtype  |	Type of	font. PDF defines some types of	fonts. It must be one  |
	   |	      |	of the predefined type Type1, Type3, TrueType or Type0.In this |
	   |	      |	version, only Type1 is supported. This is the default value.   |
	   |	      |								       |
	   | Encoding |	Specifies the  encoding	 from which the	new encoding differs.  |
	   |	      |	It must	be one of the predefined encodings MacRomanEncoding,   |
	   |	      |	MacExpertEncoding or WinAnsiEncoding. In this version, only    |
	   |	      |	WinAnsiEncoding	is supported. This is the default value.       |
	   |	      |								       |
	   | BaseFont |	The PostScript name of the font. It can	be one of the following|
	   |	      |	base fonts: Courier, Courier-Bold, Courier-BoldOblique,	       |
	   |	      |	Courier-Oblique, Helvetica, Helvetica-Bold,		       |
	   |	      |	Helvetica-BoldOblique, Helvetica-Oblique, Times-Roman,	       |
	   |	      |	Times-Bold, Times-Italic, Times-BoldItalic or Symbol.	       |
	   +----------+----------------------------------------------------------------+

       The ZapfDingbats	font is	not supported in this version.Default font is
       Helvetica.

	   my $f1 = $pdf->font('BaseFont' => 'Helvetica');

   new_outline(%params)
       Adds  an	 outline  to  the  document using the given parameters.	Return
       the newly created outline. Parameters can be:

	   +-------------+-------------------------------------------------------------+
	   | Key	 | Description						       |
	   +-------------+-------------------------------------------------------------+
	   |		 |							       |
	   | Title	 | The title of	the outline. Mandatory.			       |
	   |		 |							       |
	   | Destination | The Destination of this outline item. In this version,it is |
	   |		 | only	possible to give a page	as destination.	The default    |
	   |		 | destination is the current page.			       |
	   |		 |							       |
	   | Parent	 | The parent of this outline in the outlines tree. This is an |
	   |		 | outline object. This	way you	represent the tree of your     |
	   |		 | outlines.						       |
	   |		 |							       |
	   +-------------+-------------------------------------------------------------+

       Example:

	   my $outline = $pdf->new_outline('Title' => 'Item 1');
	   $pdf->new_outline('Title' =>	'Item 1.1', 'Parent' =>	$outline);
	   $pdf->new_outline('Title' =>	'Item 1.2', 'Parent' =>	$outline);
	   $pdf->new_outline('Title' =>	'Item 2');

   get_page_size($name)
       Returns the  size of standard paper used	for MediaBox-parameter	of
       "new_page".  "get_page_size" has	 one  optional parameter to specify
       the paper name. Possible	values are a0-a6,
       a4l,letter,broadsheet,ledger,tabloid,legal,executive and	36x36.
       Default is a4.

	   my $root = $pdf->new_page( 'MediaBox' => $pdf->get_page_size('A4') );

   version($number)
       Set and return version number. Valid version numbers are	1.0, 1.1, 1.2
       and 1.3.

   close(%params)
       Close does the work of creating the PDF data from the objects collected
       before.	You must call close() after you	have added all the contents as
       most of the real	work building the  PDF is performed there. If omit
       calling close you get no	PDF output.

   reserve($name, $type)
       Reserve the next	object number for the given object type.

   add_comment($message)
       Add comment to the document.The string will show	up in the PDF as
       postscript-style	comment:

	   % this is a postscript comment

   annotation(%params)
       Adds an annotation object, for the time being we	only do	the  'Link' -
       'URI' kind This is a  sensitive area in the PDF document	where text
       annotations are shown or	links launched.	"PDF::Create" only supports
       URI links at this time.

       URI links  have two components,the text or graphics object and the area
       where the mouseclick should occur.

       For the object  to be clicked  on you'll	use standard text of drawing
       methods.	To define the click-sensitive area and the destination URI.

       Example:

	   # Draw a string and undeline	it to show it is a link
	   $pdf->string($f1, 10, 450, 200, 'http://www.cpan.org');

	   my $line = $pdf->string_underline($f1, 10, 450, 200,	'http://www.cpan.org');

	   # Create the	hot area with the link to open on click
	   $pdf->annotation(
	       Subtype => 'Link',
	       URI     => 'http://www.cpan.org',
	       x       => 450,
	       y       => 200,
	       w       => $l,
	       h       => 15,
	       Border  => [0,0,0]
	   );

       The point (x, y)	is  the	 bottom	 left corner of	the rectangle
       containing hotspot rectangle, (w, h) are	 the  width and	height of the
       hotspot rectangle. The Border describes the thickness of	the border
       surrounding the rectangle hotspot.

       The function "string_undeline" returns the width	of the string, this
       can be used directly for	the width of the hotspot rectangle.

   image($filename)
       Prepare an XObject (image) using	the given arguments. This image	will
       be added	to the document	if it is referenced at least once before the
       close method is called.	In this	version	GIF,interlaced GIF and JPEG is
       supported.Usage of interlaced GIFs are slower because they are
       decompressed, modified and  compressed again. The gif support is
       limited to images with a	LZW minimum code size of 8. Small images with
       few colors can have a smaller minimum code size and will	not work.

   get_data()
       If you did not ask the $pdf object to write its output to a file, you
       can pick	up the	pdf  code  by calling this method. It returns a	big
       string. You need	to call	"close"	first.

LIMITATIONS
       "PDF::Create" comes with	a couple of limitations	or known caveats:

   PDF Size / Memory
       "PDF::Create" assembles the entire PDF in memory	if you create very
       large documents on a machine with a small amount	of memory your program
       can fail	because	it runs	out of memory.

   Small GIF images
       Some gif	images get created with	a minimal lzw code size	of less	than
       8. "PDF::Create"	can not	decode those and they must be converted.

SUPPORT
       I support "PDF::Create" in my spare time	between	work and  family, so
       the amount of work I put	in is limited.

       If you experience a problem make	sure you are at	the latest version
       first many of things have already been fixed.

       Please register	bug  at	the CPAN bug tracking system at
       <http://rt.cpan.org> or send email to "bug-PDF-Create [at] rt.cpan.org"

       Be sure to include the following	information:

       - PDF::Create Version you are running
       - Perl version (perl -v)
       - Operating System vendor and version
       - Details about your operating environment that might be	related	to the
       issue being described
       - Exact cut and pasted error or warning messages
       - The shortest, clearest	 code  you  can	manage to write	which
       reproduces the bug described.

       I  appreciate patches against the latest	released version of
       "PDF::Create" which fix the bug.

       Feature request can be submitted	like bugs. If you provide patch	for a
       feature which does not go against the "PDF::Create" philosophy (keep it
       simple) then you	have a good chance for it to be	accepted.

SEE ALSO
       Adobe PDF <http://www.adobe.com/devnet/pdf/pdf_reference.html>

       PDF::Labels Routines to produce formatted pages of mailing labels in
       PDF, uses PDF::Create internally.

       PDF::Haru Perl interface	to Haru	Free PDF Library.

       PDF::EasyPDF PDF	creation from a	one-file module, similar to
       PDF::Create.

       PDF::CreateSimple Yet another PDF creation module

       PDF::Report A wrapper written for PDF::API2.

AUTHORS
       Fabien Tassin

       GIF and JPEG-support: Michael Gross (info@mdgrosse.net)

       Maintenance since 2007: Markus Baertschi	(markus@markus.org)

       Currently maintained by Mohammad	S Anwar	(MANWAR) "<mohammad.anwar at
       yahoo.com>"

REPOSITORY
       <https://github.com/manwar/pdf-create>

COPYRIGHT
       Copyright 1999-2001,Fabien Tassin.All rights reserved.It	may be used
       and modified freely, but	I do  request that this	copyright notice
       remain attached to the file.  You may modify this module	as you
       wish,but	if you redistribute a modified version , please	attach a note
       listing the modifications you have made.

       Copyright 2007 Markus Baertschi

       Copyright 2010 Gary Lieberman

LICENSE
       This is free software; you can redistribute it and / or modify it under
       the same	terms as Perl 5.6.0.

perl v5.24.1			  2016-09-09			PDF::Create(3)

NAME | VERSION | DESCRIPTION | SYNOPSIS | CONSTRUCTOR | METHODS | LIMITATIONS | SUPPORT | SEE ALSO | AUTHORS | REPOSITORY | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDF::Create&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help