/ 
PDF-TextBlock-0.13
River stage zero No dependents
/ PDF::TextBlock

NAME

PDF::TextBlock - Easier creation of text blocks when using PDF::API2 or PDF::Builder

SYNOPSIS

use PDF::API2;   # PDF::Builder also works
use PDF::TextBlock;

my $pdf = PDF::API2->new( -file => "40-demo.pdf" );
my $tb  = PDF::TextBlock->new({
   pdf       => $pdf,
   fonts     => {
      b => PDF::TextBlock::Font->new({
         pdf  => $pdf,
         font => $pdf->corefont( 'Helvetica-Bold', -encoding => 'latin1' ),
      }),
   },
});
$tb->text(
   $tb->garbledy_gook .
   ' <b>This fairly lengthy</b>, rather verbose sentence <b>is tagged</b> to appear ' .
   'in a <b>different font, specifically the one we tagged b for "bold".</b> ' .
   $tb->garbledy_gook .
   ' <href="http://www.omnihotels.com">Click here to visit Omni Hotels.</href> ' .
   $tb->garbledy_gook . "\n\n" .
   "New paragraph.\n\n" .
   "Another paragraph."
);
$tb->apply;
$pdf->save;
$pdf->end;

DESCRIPTION

Neither Rick Measham's excellent PDF::API2 tutorial nor PDF::FromHTML are able to cope with wanting some words inside a text block to be bold. This module makes that task trivial.

Simply define whatever tags you want PDF::TextBlock to honor inside the fonts hashref, and then you are free to use HTML-like markup in the text attribute and we'll render those fonts for you.

We also honor the HTML-like tag <href>. This means that we add annotation to the PDF for you which makes the word(s) you wrap in <href> clickable, and we underline those words.

Note this markup syntax is very rudimentary. We do not support HTML. Tags cannot overlap each other. There is no way to escape tags inside text().

The tests in t/ generate .pdf files. You might find those examples helpful. Watch out for 20-demo.pdf. It spits. :)

METHODS

new

Our attributes are listed below. They can be set when you call new(), and/or added/changed individually at any time before you call apply().

pdf

A PDF::API2 or PDF::Builder object. You must provide this.

text

The text of your TextBlock. Defaults to garbledy_gook().

x

X position from the left of the document. Default is 20/mm.

y

Y position from the bottom of the document. Default is 238/mm.

w

Width of this text block. Default is 175/mm.

h

Height of this text block. Default is 220/mm.

align

Alignment of words in the text block. Default is 'justify'. Legal values:

justify

Spreads words out evenly in the text block so that each line ends in the same spot on the right side of the text block. The last line in a paragraph (too short to fill the entire line) will be set to 'left'.

fulljustify

Like justify, except that the last line is also spread across the page. The last line can look very odd with very large gaps.

left

Aligns each line to the left.

Aligns each line to the right.

page

A PDF::API2::Page or PDF::Builder::Page object. If you don't set this manually then we create a new page for you when you call apply().

If you want multiple PDF::TextBlock objects to all render onto the same page, you could create a PDF::API2 or PDF::Builder page yourself, and pass it in to each PDF::TextBlock object:

my $pdf = PDF::API2->new( -file => "mytest.pdf" );
my $page = $pdf->page();

my $tb  = PDF::TextBlock->new({
   pdf  => $pdf,
   page => $page,     # <---
   ...

Or after your first apply() you could grab $page off of $tb.

my $pdf = PDF::API2->new( -file => "mytest.pdf" );
my $tb  = PDF::TextBlock->new({
   pdf  => $pdf,
   ...
});
$tb->apply;
my $page = $tb->page;   # Use the same page

my $tb2 = PDF::TextBlock->new({
   pdf  => $pdf,
   page => $page,     # <---
   ...
fonts

A hashref of HTML-like markup tags and what font objects you want us to use when we see that tag in text().

my $tb  = PDF::TextBlock->new({
   pdf       => $pdf,
   fonts     => {
      # font is a PDF::API2::Resource::Font::CoreFont
      b => PDF::TextBlock::Font->new({
         pdf  => $pdf,
         font => $pdf->corefont( 'Helvetica-Bold', -encoding => 'latin1' ),
         fillcolor => '#ff0000',  # red
      }),
   },
});

The attributes below came from Rick's text_block(). They do things, but I don't really understand them. POD patches welcome. :)

http://rick.measham.id.au/pdf-api2/

lead

Leading distance (baseline to baseline spacing). Default is 15/pt.

parspace

Extra gap between paragraphs. Default is 0/pt.

hang
flindent
fpindent
indent

apply

This is where we do all the PDF::API2 or PDF::Builder heavy lifting for you.

Returns $endw, $ypos, $overflow.

I'm not sure what $endw is good for, it's straight from Ricks' code. :)

$ypos is useful when you have multiple TextBlock objects and you want to start the next one wherever the previous one left off.

my ($endw, $ypos) = $tb->apply();
$tb->y($ypos);
$tb->text("a bunch more text");
$tb->apply();

$overflow is whatever text() didn't fit inside your TextBlock. (Too much text? Your font was too big? You set w and h too small?)

The original version of this method was text_block(), which is (c) Rick Measham, 2004-2007. The latest version of text_block() can be found in the tutorial located at http://rick.measham.id.au/pdf-api2/. text_block() is released under the LGPL v2.1.

garbledy_gook

Returns a scalar containing a paragraph of jibberish. Used by test scripts for demonstrations.

my $jibberish = $tb->garbledy_gook(50);

The integer is the numer of jibberish words you want returned. Default is 100.

AUTHOR

Jay Hannah, <jay at jays.net>

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PDF::TextBlock

Source code and bug reports on github: http://github.com/jhannah/pdf-textblock

ACKNOWLEDGEMENTS

This module started from, and has grown on top of, Rick Measham's (aka Woosta) "Using PDF::API2" tutorial: http://rick.measham.id.au/pdf-api2/

COPYRIGHT & LICENSE

Copyright 2009-2021 Jay Hannah, all rights reserved.

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