++ed by:

2 PAUSE users
3 non-PAUSE users.

Author image Jay Hannah
and 1 contributors


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


  use PDF::API2;
  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->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."


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. :)



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().


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


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


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


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


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


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


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


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'.


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


Aligns each line to the left.

Aligns each line to the right.


A PDF::API2::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 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,
  my $page = $tb->page;   # Use the same page

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

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. :)



Default is 15/pt.


Default is 0/pt.



This is where we do all the PDF::API2 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->text("a bunch more text");

$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.


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.


Jay Hannah, <jay at jays.net>


align 'right' and 'center' with any markup tags is broken

This software can't currently handle those alignments with any markup tags. As written the software is in a loop calculating x position of each word, one word at a time from left to right. But in the case of aligns 'right' and 'center' we don't know the position of the first word until we know the x positions of ALL words. We need a smarter handler for this scenario. See t/30-demo.t. [BUG1]

Please report any bugs or feature requests to bug-pdf-textblock at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PDF-TextBlock. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc PDF::TextBlock

You can also look for information at:


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 2009-2013 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.