Mxpress::PDF - PDF
Version 0.12
This is experimental and may yet still change.
use Mxpress::PDF; my @data = qw/ Brian Dougal Dylan Ermintrude Florence Zebedee /; my $gen_text = sub { join( ' ', map { $data[int(rand(scalar @data))] } 0 .. int(rand(shift))) }; my $pdf = Mxpress::PDF->new_pdf('test', page => { background => '#000', padding => 15, columns => 3, }, cover => { columns => 1 }, toc => { font => { colour => '#00f' }, }, title => { font => { colour => '#f00', }, margin_bottom => 3, }, subtitle => { font => { colour => '#0ff', }, margin_bottom => 3 }, subsubtitle => { font => { colour => '#f0f', }, margin_bottom => 3 }, text => { font => { colour => '#fff' }, margin_bottom => 3, align => 'justify' }, ); $pdf->cover->add->title->add( 'Add a cover page' )->image->add( 't/hand-cross.png' )->cover->add( cb => ['text', 'add', q|you're welcome|] ); $pdf->title->add( 'Table Of Contents' )->toc->placeholder; $pdf->page->header->add( show_page_num => 'right', page_num_text => "page {num}", cb => ['text', 'add', 'Header of the page', align => 'center', font => Mxpress::PDF->font($pdf, colour => '#f00') ], h => $pdf->mmp(10), padding => 5 ); $pdf->page->footer->add( show_page_num => 'left', cb => ['text', 'add', 'Footer of the page', align => 'center', font => Mxpress::PDF->font($pdf, colour => '#f00') ], h => $pdf->mmp(10), padding => 5 ); for (0 .. 100) { $pdf->toc->add( [qw/title subtitle subsubtitle/]->[int(rand(3))] => $gen_text->(4) )->text->add( $gen_text->(1000) ); } $pdf->save();
This module currently allows you to easily create a PDF. Why? For fun.
Mxpress::PDF is a factory package and the entry point for Mxpress::PDF::* objects.
Returns a new Mxpress::PDF::File object. This is the MAIN object for working on the PDF file.
my $file = Mxpress::PDF->new_pdf($filename, %page_args);
Returns a new Mxpress::PDF::Page Object. This object is for managing an individual PDF page.
my $page = Mxpress::PDF->page(%page_args);
Returns a new Mxpress::PDF::Page::Component::Cover Object. This object is for managing the PDF cover page.
my $cover = Mxpress::PDF->cover(%cover_args);
Returns a new Mxpress::PDF::Page::Component::Header Object. This object is for managing an individual PDF page header.
my $header = Mxpress::PDF->header(%header_args);
Returns a new Mxpress::PDF::Page::Component::Footer Object. This object is for managing an individual PDF page footer.
my $footer = Mxpress::PDF->footer(%footer_args);
Returns a new Mxpress::PDF::Plugin::Font Object. This object is for loading a PDFs text font.
my $font = Mxpress::PDF->font($file, %font_args);
Returns a new Mxpress::PDF::Plugin::Shape::Line Object. This object is for drawing lines.
my $line = Mxpress::PDF->line($file, %line_args);
Returns a new Mxpress::PDF::Plugin::Shape::Box Object. This object is for drawing box shapes.
my $box = Mxpress::PDF->box($file, %box_args);
Returns a new Mxpress::PDF::Plugin::Shape::Circle Object. This object is for drawing circle shapes.
my $box = Mxpress::PDF->box($file, %circle_args);
Returns a new Mxpress::PDF::Plugin::Shape::Pie Object. This object is for drawing pie shapes.
my $pie = Mxpress::PDF->pie($file, %pie_args);
Returns a new Mxpress::PDF::Plugin::Shape::Ellipse Object. This object is for drawing ellipse shapes.
my $ellipse = Mxpress::PDF->ellipse($file, %ellise_args);
Returns a new Mxpress::PDF::Plugin::Text Object. This object aids with writing text to a pdf page.
my $text = Mxpress::PDF->text($file, %text_args);
Returns a new Mxpress::PDF::Plugin::Text::Title Object. This object aids with writing 'title' text to a pdf page.
my $title = Mxpress::PDF->title($file, %title_args);
Returns a new Mxpress::PDF::Plugin::Text::Title Object. This object aids with writing 'subtitle' text to a pdf page.
my $subtitle = Mxpress::PDF->subtitle($file, %subtitle_args);
Returns a new Mxpress::PDF::Plugin::Text::Subsubtitle Object. This object aids with writing 'subsubtitle' text to a pdf page.
my $subsubtitle = Mxpress::PDF->subsubtitle($file, %subsubtitle_args);
Returns a new Mxpress::PDF::Plugin::TOC Object. This object is for managing a table of contents.
my $toc = Mxpress::PDF->toc($file, %toc_args);
Returns a new Mxpress::PDF::Plugin::TOC::Outline Object. This object is for managing an indivual outline for the table of contents.
my $outline = Mxpress::PDF->add_outline($file, %ouline_args);
Returns a new Mxpress::PDF::Plugin::Image Object. This object aids with adding images to a pdf page.
my $image = Mxpress::PDF->image($file, %image_args);
Returns a new Mxpress::PDF::Plugin::Annotation Object. This object aids with adding annotations to a pdf page.
my $annotation = Mxpress::PDF->annotation($file, %image_args);
Mxpress::PDF::File is the main object that you will use when creating a pdf using this library. To instantiate call add_file with a file name and any plugin attributes.
my $file = Mxpress::PDF->add_file($filename, page => {}, toc => {}, title => {}, subtitle => {}, subsubtitle => {}, text => {}, toc => {}, box => {}, line => {}, circle => {}, pie => {}, ellipse => {} );
The following attributes can be configured for a Mxpress::PDF::File, they are all optional.
$file->$attr
The file name of the pdf
$file->file_name;
A PDF::API2 Object.
$file->pdf;
A list of Mxpress::PDF::Page objects.
$file->pages;
An open Mxpress::PDF::Page object.
$file->page;
An array of arrays that define cbs, triggered when $file->save() is called.
[ [$plugin, $method_name, @%args] ]
A Mxpress:PDF::Plugin::Font Object.
$file->font->load;
A Mxpress::PDF::Plugin::Shape::Line Object.
$file->line->add;
A Mxpress::PDF::Plugin::Shape::Box Object.
$file->box->add;
A Mxpress::PDF::Plugin::Shape::Circle Object.
$file->circle->add;
A Mxpress::PDF::Plugin::Shape::Pie Object.
$file->pie->add;
A Mxpress::PDF::Plugin::Shape::Ellipse Object.
$file->ellipse->add;
A Mxpress::PDF::Plugin::TOC Object.
$file->toc->placeholder->toc->add( title => 'A title' );
A Mxpress::PDF::Plugin::Title Object.
$file->title->add;
A Mxpress::PDF::Plugin::Subtitle Object.
A Mxpress::PDF::Plugin::Subsubtitle Object
$file->subsubtitle->add;
A Mxpress::PDF::Plugin::Text Object
$file->text->add;
The following methods can be called from a Mxpress::PDF::File Object.
This will add a new Mxpress::PDF::Page to the file. You can pass any page attributes defined in the documentation below.
$file->add_page(%page_attrs)
This will save the pdf file. Note call only once you are finished generating the pdf file.
$file->save();
Add a onsave callback to the file. The callbacks will be triggered when you call $file->save();.
$file->onsave($plugin, $cb, \%plugin_args);
Convert mm to pt.
my $pt = $file->mmp(10);
An open Mxpress::PDF::Page object. Mxpress::PDF::Page is for managing an individual PDF page. To access the current open page call the attribute on the file object.
my $page = $file->page;
To add a new page to the pdf call add_page on the file object.
my $new_page = $file->add_page(%page_attributes)->page;
$page->$attr
The page size of the pdf, default is A4.
$page->page_size('A4');
The background colour of the page.
$page->background('#000');
The page number.
$page->num;
The current PDF::API2::Page Object.
$page->current;
The number of columns configured for the page, default is 1.
$page->columns(5);
The current column that is being generated, default is 1.
$page->column(2);
The number of rows configured for the page, default is 1.
$page->rows(5);
$page->row(2);
Is the page rotated (portrait/landscape).
$page->is_rotated;
The current x coordinate.
$page->x($x);
The current y coordinate.
$page->y($y);
The available page width.
$page->w($w);
The available page height.
$page->h($h);
Disable any column/row configuration and render full width/height.
$page->full(\1);
Add padding to the page (mm).
$page->padding($mm);
Add margin to the top of the page (mm).
$page->margin_top($mm);
Add margin to the bottom of the page (mm).
$page->margin_bottom($mm);
Callbacks that will be triggered when $file->save is called.
$page->onsave_cbs([ [$plugin, $method_name, @%args] ]);
A Mxpress::PDF::Page::Component::Header Object.
$page->header;
A Mxpress::PDF::Page::Component::Footer Object.
$page->footer;
The following methods can be called from a Mxpress::PDF::Page Object.
Rotate the current page.
$page->rotate();
Find the next column of the page.
$page->next_column();
Find the next row of the page.
$page->next_row();
Add a onsave callback to the page. The callbacks will be triggered when you call $file->save();.
$page->onsave($plugin, $cb, @%plugin_args);
Return attributes for the page.
my $attrs = $page->attrs(@attrs);
Mxpress::PDF::Page::Component::Cover extends Mxpress::PDF::Page::Component and is for managing an the PDF cover page.
You can pass default attributes when instantiating the page object.
$file->add_page( cover => { %cover_atts } );
or when calling the objects add method.
$page->cover->add( %cover_attrs );
The following additional attributes can be configured for a Mxpress::PDF::Page::Component::Cover, they are all optional.
$page->cover->$attr
Alignment for the page number
show_page_num => 'right'
Text to display around the page number.
page_num_text => 'Page {num}'
Control whether to display the cover, default is false however it is set to true if ->cover->add() is called.
active => true
The following methods can be called from a Mxpress::PDF::Page::Component Object.
Add content to the cover. You can pass any attribute for the header along with a cb function which will be added to the onsave_cbs.
$page->coverr->add( cb => [...], %cover_atts );
Set the position of the header.
$page->header->position($x, $y, $w, $h);
Process the page_num_text into printable form.
$self->header->processs_page_num_text();
Activate the header.
$page->activate()
Move to page 2.
$page->end;
Mxpress::PDF::Page::Component::Header extends Mxpress::PDF::Page::Component and is for managing an individual PDF page header.
$file->add_page( header => { %header_atts } );
$page->header->add( %header_attrs );
The following additional attributes can be configured for a Mxpress::PDF::Page::Component::Header, they are all optional.
$page->header->$attr
Control whether to display the header, default is false however it is set to true if ->header->add() is called.
The following methods can be called from a Mxpress::PDF::Page::Header Object.
Add content to the header. You can pass any attribute for the header along with a cb function which will be added to the onsave_cbs.
$page->header->add( cb => [...], %header_atts );
Mxpress::PDF::Page::Component::Footer extends Mxpress::PDF::Page and is for managing an individual PDF page footer.
$file->add_page( footer => { %footer_atts } );
$page->footer->add( %footer_attrs );
The following additional attributes can be configured for a Mxpress::PDF::Page::Component::Footer, they are all optional.
$page->footer->$attr
Control whether to display the header, default is false however it is set to true if ->footer->add() is called.
The following methods can be called from a Mxpress::PDF::Page::Footer Object.
Add content to the footer. You can pass any attribute for the footer along with a cb function which will be added to the onsave_cbs.
$page->footer->add( cb => [...], %footer_atts );
Set the position of the footer.
$page->footer->position($x, $y, $w, $h);
Mxpress::PDF::Plugin is a base class for plugins, it includes Mxpress::PDF::Utils.
Mxpress::PDF::Plugin::Font extends Mxpress::PDF::Plugin and is for managing pdf fonts.
You can pass default attributes when instantiating the file object.
Mxpress::PDF->add_file($filename, font => { %font_atts }, text => { font => { %font_attrs } } );
or when calling some objects add methods like Mxpress::PDF::Plugin::Text->add.
$file->text->add( font => { %font_attrs }, );
The following attributes can be configured for a Mxpress::PDF::Plugin::Font object, they are all optional.
$font->$attr();
The font colour.
The font size.
The font family.
Loaded hashref of PDF::API2 fonts.
Line height of the font.
The following methods can be called from a Mxpress::PDF::Plugin::Font Object.
Load the PDF::API2 font object.
$font->load()
Find a PDF::API2 font object.
$font->find($famild, $enc?)
Mxpress::PDF::Plugin::Shape extends Mxpress::PDF::Plugin and is the base class for all shape plugins.
Mxpress::PDF::Plugin::Shape::Line extends Mxpress::PDF::Plugin::Shape and is for aiding with drawing lines on a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, line => { %line_attrs }, );
$file->line->add( %line_attrs );
The following attributes can be configured for a Mxpress::PDF::Plugin::Line object, they are all optional.
$line->$attr();
The colour of the line.
$line->fill_colour('#000');
The position of the line
$line->position([$x, $y]);
$line->end_position([$x, $y]);
The following methods can be called from a Mxpress::PDF::Plugin::Shape::Line Object.
Add a new line to the current Mxpress::PDF::Page.
$line->add(%line_args);
Mxpress::PDF::Plugin::Shape::Box extends Mxpress::PDF::Plugin::Shape and is for aiding with drawing boxes on a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, box => { %box_attrs }, );
$file->box->add( %box_attrs ); my $box = $file->box;
The following attributes can be configured for a Mxpress::PDF::Plugin::Box object, they are all optional.
$box->$attr();
The background colour of the box.
$box->fill('#000');
The position of the box.
$box->position([$x, $y, $w, $h]);
The following methods can be called from a Mxpress::PDF::Plugin::Shape::Box Object.
Add a new box to the current Mxpress::PDF::Page.
$box->add(%box_attrs);
Mxpress::PDF::Plugin::Shape::Circle extends Mxpress::PDF::Plugin::Shape and is for aiding with drawing circles on a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, circle => { %circle_attrs }, );
$file->box->add( %circle_attrs ); my $circle = $file->circle;
The following attributes can be configured for a Mxpress::PDF::Plugin::Shape::Circle object, they are all optional.
$circle->$attr();
The background colour of the circle.
$circle->fill_colour('#000');
The radius of the circle. (mm)
$circle->radius($num);
The position of the circle. (pt)
$circle->position([$x, $y, $w, $h]);
The following methods can be called from a Mxpress::PDF::Plugin::Shape::Circle Object.
Add a new circle shape to the current Mxpress::PDF::Page.
$circle->add(%line_args);
Mxpress::PDF::Plugin::Shape::Pie extends Mxpress::PDF::Plugin::Shape and is for aiding with drawing pies on a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, pie => { %pie_attrs }, );
$file->pie->add( %pie_attrs ); my $pie = $file->pie;
The following attributes can be configured for a Mxpress::PDF::Plugin::Shape::Pie object, they are all optional.
$pie->$attr();
The background colour of the pie.
$pie->fill_colour('#000');
The radius of the pie.
$pie->radius($num);
Start percent of the pie.
$pie->start(180)
End percent of the pie.
$pie->end(90);
The position of the pie (pt)
$pie->position([$x, $y, $w, $h]);
The following methods can be called from a Mxpress::PDF::Plugin::Shape::Pie Object.
Add a new pie shape to the current Mxpress::PDF::Page.
$pie->add(%pie_attrs);
Mxpress::PDF::Plugin::Shape::Ellipse extends Mxpress::PDF::Plugin::Shape and is for aiding with drawing ellipses on a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, ellipse => { %ellise_attrs }, );
$file->ellipse->add( %pie_attrs ); my $pie = $file->ellipse;
The following attributes can be configured for a Mxpress::PDF::Plugin::Shape::Ellipse object, they are all optional.
$ellipse->$attr();
The background colour of the ellipse.
$ellipse->fill_colour('#000');
The radius of the ellispe.
$ellispse->radius($r);
Start percent of the ellipse
$ellipse->start($p)
End percent of the ellipse.
$ellipse->end($p);
The position of the ellipse (pt)
The following methods can be called from a Mxpress::PDF::Plugin::Shape::Ellipse Object.
Add a new ellipse shape to the current Mxpress::PDF::Page.
$ellipse->add(%ellipse_attrs);
Mxpress::PDF::Plugin::Text extends Mxpress::PDF::Plugin and is for aiding with writing text to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, text => { %text_attrs }, );
$file->text->add( %text_attrs ); my $text = $file->text;
The following attributes can be configured for a Mxpress::PDF::Plugin::Text object, they are all optional.
$text->$attrs();
An Mxpress::PDF::Plugin::Font object.
$text->font(Mxpress::PDF->font($file, %font_args));
Configure the spacing between paragraphs.
$text->paragraph_space($mm);
If true then paragraphs within the passed text string will be split into individual columns.
$text->paragraphs_to_columns(\1);
Indent the first line when rendering given text.
$text->first_line_indent($mm);
$text->first_paragraph_indent($mm);
Align the text on each line. (left|justify|center|right)
$text->align('justify');
Set a bottom margin to be added after text has been rendered.
$text->margin($mm);
Set an indent for the block of text.
$text->indent($mm);
Pad the passed text to fit the available space, default is undefined.
$text->pad('.');
Append a string to the padded text.
$text->pad_end('!');
The following methods can be called from a Mxpress::PDF::Plugin::Text Object.
Add a text to the current Mxpress::PDF::Page.
$text->add($string_of_text, %text_args);
Mxpress::PDF::Plugin::Title extends Mxpress::PDF::Plugin::Text and is for aiding with adding titles to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, title => { %title_attrs }, );
$file->title->add( %title_attrs );
Mxpress::PDF::Plugin::Subtitle extends Mxpress::PDF::Plugin::Text and is for aiding with adding subtitles to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, subtitle => { %subtitle_attrs }, );
$file->subtitle->add( %subtitle_attrs );
Mxpress::PDF::Plugin::Subsubtitle extends Mxpress::PDF::Plugin::Text and is for aiding with adding subsubtitles to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, subsubtitle => { %subsubtitle_attrs }, );
$file->subsubtitle->add( %subsubtitle_attrs );
Mxpress::PDF::Plugin::TOC extends Mxpress::PDF::Plugin and is for managing a table of contents.
Mxpress::PDF->add_file($filename, toc => { %toc_attrs }, );
$file->toc->add( %toc_attrs ); my $toc = $file->toc;
The following attributes can be configured for a Mxpress::PDF::Plugin::TOC object, they are all optional.
$toc->$attr();
The current count of toc links
$file->toc->count;
The indent used for each level, default is 5.
$file->toc->indent(0);
The levels that can be used for TOC. For now we just have title|subtitle|subsubtitle but this is where you could extend.
$file->toc->levels;
The line height offset when rendering the table of contents.
$file->toc_line_offset($mm);
Attributes to be used for building the font class for TOC outlines
$toc->font(\%font_attrs);
The following methods can be called from a Mxpress::PDF::Plugin::TOC Object.
The placeholder position where the table of contents will be rendered.
$toc->placeholder(%placeholder_attrs);
Add to the table of contents
$toc->add( title => $title, %toc_attrs ) $toc->add( subtitle => [$subtitle, %subtitle_attrs] );
Mxpress::PDF::Plugin::TOC::Outline extends Mxpress::PDF::Plugin and is for managing a table of content outline.
my $outline = $file->FACTORY->add_outline()
The following attributes can be configured for a Mxpress::PDF::Plugin::TOC::Object object.
$outline->$attrs();
The PDF::API2 Outline object.
$outline->outline;
The x coordinates of the outline.
$outline->x($x);
The y coordinates of the outline.
$outline->y($y);
The title text used to render in the table of contents.
$outline->title($text);
The linked Mxpress::PDF::Page object.
$ouline->page();
The level of the outline.
$ouline->level(1);
An arrarref of linked Mxpress::PDF::Plugin::TOC::Outline objects.
$ouline->children
Mxpress::PDF::Plugin::Image extends Mxpress::PDF::Plugin and is for adding images to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, image => { %image_attrs }, );
$file->image->add( %image_attrs ); my $image = $file->image;
The following attributes can be configured for a Mxpress::PDF::Plugin::Image object, they are all optional.
$img->$attrs();
The width of the image.
$img->width($pt);
The height of the image.
$img->height($pt);
Align the image - left|center|right
$img->align('right');
The following methods can be called from a Mxpress::PDF::Plugin::Image Object.
Add an image to the current Mxpress::PDF::Page.
$img->add($image_fh, $type, %image_attrs)
or
$img->add($image_file_path, %image_attrs)
Mxpress::PDF::Plugin::Annotation extends Mxpress::PDF::Plugin and is for adding annotations to a Mxpress::PDF::Page.
Mxpress::PDF->add_file($filename, annotation => { %annotation_attrs }, );
$file->annotation->add( %annotation_attrs ); my $annotation = $annotation->annotation;
The following attributes can be configured for a Mxpress::PDF::Plugin::Annotation object, they are all optional.
$annotation->$attrs();
The type of annotation text|file|.
$annotation->type;
The width of the annotation.
$annotation->w;
The hieght of the annotation.
$annotation->h;
Toggle whether annotation is open.
$annotation->open;
The following methods can be called from a Mxpress::PDF::Plugin::Annotation Object.
Add an annotation to the current Mxpress::PDF::Page.
$annotation->add('add some text', %annotation_attrs)
LNATION, <thisusedtobeanemail at gmail.com>
<thisusedtobeanemail at gmail.com>
Please report any bugs or feature requests to bug-mxpress-pdf at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mxpress-PDF. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-mxpress-pdf at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Mxpress::PDF
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Mxpress-PDF
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Mxpress-PDF
CPAN Ratings
https://cpanratings.perl.org/d/Mxpress-PDF
Search CPAN
https://metacpan.org/release/Mxpress-PDF
This software is Copyright (c) 2020 by LNATION.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
To install Mxpress::PDF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mxpress::PDF
CPAN shell
perl -MCPAN -e shell install Mxpress::PDF
For more information on module installation, please visit the detailed CPAN module installation guide.