modules/override/PDF/Table.pm

   1 #!/usr/bin/env perl
   2 # vim: softtabstop=4 tabstop=4 shiftwidth=4 ft=perl expandtab smarttab
   3
   4 use 5.006;
   5 use strict;
   6 use warnings;
   7
   8 package PDF::Table;
   9
  10 use Carp;
  11 use List::Util qw(sum);
  12
  13 our $VERSION = '0.10.1';
  14
  15 print __PACKAGE__.' is version: '.$VERSION.$/ if($ENV{'PDF_TABLE_DEBUG'});
  16
  17 ############################################################
  18 #
  19 # new - Constructor
  20 #
  21 # Parameters are meta information about the PDF
  22 #
  23 # $pdf = PDF::Table->new();
  24 #
  25 ############################################################
  26
  27 sub new
  28 {
  29     my $type = shift(@_);
  30     my $class = ref($type) || $type;
  31     my $self  = {};
  32     bless ($self, $class);
  33
  34     # Pass all the rest to init for validation and initialisation
  35     $self->_init(@_);
  36
  37     return $self;
  38 }
  39
  40 sub _init
  41 {
  42     my ($self, $pdf, $page, $data, %options ) = @_;
  43
  44     # Check and set default values
  45     $self->set_defaults();
  46
  47     # Check and set mandatory params
  48     $self->set_pdf($pdf);
  49     $self->set_page($page);
  50     $self->set_data($data);
  51     $self->set_options(\%options);
  52
  53     return;
  54 }
  55
  56 sub set_defaults{
  57     my $self = shift;
  58
  59     $self->{'font_size'} = 12;
  60 }
  61
  62 sub set_pdf{
  63     my ($self, $pdf) = @_;
  64     $self->{'pdf'} = $pdf;
  65 }
  66
  67 sub set_page{
  68     my ($self, $page) = @_;
  69     if ( defined($page) && ref($page) ne 'PDF::API2::Page' ){
  70
  71         if( ref($self->{'pdf'}) eq 'PDF::API2' ){
  72             $self->{'page'} = $self->{'pdf'}->page();
  73         } else {
  74             carp 'Warning: Page must be a PDF::API2::Page object but it seems to be: '.ref($page).$/;
  75             carp 'Error: Cannot set page from passed PDF object either as it is invalid!'.$/;
  76         }
  77         return;
  78     }
  79     $self->{'page'} = $page;
  80
  81 }
  82
  83 sub set_data{
  84     my ($self, $data) = @_;
  85     #TODO: implement
  86 }
  87
  88 sub set_options{
  89     my ($self, $options) = @_;
  90     #TODO: implement
  91 }
  92
  93 ############################################################
  94 #
  95 # text_block - utility method to build multi-paragraph blocks of text
  96 #
  97 ############################################################
  98
  99 sub text_block
 100 {
 101     my $self        = shift;
 102     my $text_object = shift;
 103     my $text        = shift;    # The text to be displayed
 104     my %arg         = @_;       # Additional Arguments
 105
 106     my  ( $align, $xpos, $ypos, $xbase, $ybase, $line_width, $wordspace, $endw , $width, $height) =
 107         ( undef , undef, undef, undef , undef , undef      , undef     , undef , undef , undef  );
 108     my @line        = ();       # Temp data array with words on one line
 109     my %width       = ();       # The width of every unique word in the givven text
 110
 111     # Try to provide backward compatibility
 112     foreach my $key (keys %arg)
 113     {
 114         my $newkey = $key;
 115         if($newkey =~ s#^-##)
 116         {
 117             $arg{$newkey} = $arg{$key};
 118             delete $arg{$key};
 119         }
 120     }
 121     #####
 122
 123     #---
 124     # Lets check mandatory parameters with no default values
 125     #---
 126     $xbase  = $arg{'x'} || -1;
 127     $ybase  = $arg{'y'} || -1;
 128     $width  = $arg{'w'} || -1;
 129     $height = $arg{'h'} || -1;
 130     unless( $xbase  > 0 ){ carp "Error: Left Edge of Block is NOT defined!\n";  return; }
 131     unless( $ybase  > 0 ){ carp "Error: Base Line of Block is NOT defined!\n"; return; }
 132     unless( $width  > 0 ){ carp "Error: Width of Block is NOT defined!\n";  return; }
 133     unless( $height > 0 ){ carp "Error: Height of Block is NOT defined!\n"; return; }
 134     # Check if any text to display
 135     unless( defined( $text) and length($text) > 0 )
 136     {
 137         carp "Warning: No input text found. Trying to add dummy '-' and not to break everything.\n";
 138         $text = '-';
 139     }
 140
 141     # Strip any <CR> and Split the text into paragraphs
 142     $text =~ s/\r//g;
 143     my @paragraphs  = split(/\n/, $text);
 144
 145     # Width between lines in pixels
 146     my $line_space = defined $arg{'lead'} && $arg{'lead'} > 0 ? $arg{'lead'} : 12;
 147
 148     # Calculate width of all words
 149     my $space_width = $text_object->advancewidth("\x20");
 150     my @words = split(/\s+/, $text);
 151     foreach (@words)
 152     {
 153         next if exists $width{$_};
 154         $width{$_} = $text_object->advancewidth($_);
 155     }
 156
 157     my @paragraph = split(' ', shift(@paragraphs));
 158     my $first_line = 1;
 159     my $first_paragraph = 1;
 160
 161     # Little Init
 162     $xpos = $xbase;
 163     $ypos = $ybase;
 164     $ypos = $ybase + $line_space;
 165     my $bottom_border = $ypos - $height;
 166     # While we can add another line
 167     while ( $ypos >= $bottom_border + $line_space )
 168     {
 169         # Is there any text to render ?
 170         unless (@paragraph)
 171         {
 172             # Finish if nothing left
 173             last unless scalar @paragraphs;
 174             # Else take one line from the text
 175             @paragraph = split(' ', shift( @paragraphs ) );
 176
 177             $ypos -= $arg{'parspace'} if $arg{'parspace'};
 178             last unless $ypos >= $bottom_border;
 179         }
 180         $ypos -= $line_space;
 181         $xpos = $xbase;
 182
 183         # While there's room on the line, add another word
 184         @line = ();
 185         $line_width = 0;
 186         if( $first_line && exists $arg{'hang'} )
 187         {
 188             my $hang_width = $text_object->advancewidth($arg{'hang'});
 189
 190             $text_object->translate( $xpos, $ypos );
 191             $text_object->text( $arg{'hang'} );
 192
 193             $xpos         += $hang_width;
 194             $line_width   += $hang_width;
 195             $arg{'indent'} += $hang_width if $first_paragraph;
 196         }
 197         elsif( $first_line && exists $arg{'flindent'} && $arg{'flindent'} > 0 )
 198         {
 199             $xpos += $arg{'flindent'};
 200             $line_width += $arg{'flindent'};
 201         }
 202         elsif( $first_paragraph && exists $arg{'fpindent'} && $arg{'fpindent'} > 0 )
 203         {
 204             $xpos += $arg{'fpindent'};
 205             $line_width += $arg{'fpindent'};
 206         }
 207         elsif (exists $arg{'indent'} && $arg{'indent'} > 0 )
 208         {
 209             $xpos += $arg{'indent'};
 210             $line_width += $arg{'indent'};
 211         }
 212
 213         # Lets take from paragraph as many words as we can put into $width - $indent;
 214         # Always take at least one word; otherwise we'd end up in an infinite loop.
 215         while ( !scalar(@line) || (
 216           @paragraph && (
 217             $text_object->advancewidth( join("\x20", @line)."\x20" . $paragraph[0]) + $line_width < $width
 218           )
 219         ))
 220         {
 221             push(@line, shift(@paragraph));
 222         }
 223         $line_width += $text_object->advancewidth(join('', @line));
 224
 225         # calculate the space width
 226         if( $arg{'align'} eq 'fulljustify' or ($arg{'align'} eq 'justify' and @paragraph))
 227         {
 228             @line = split(//,$line[0]) if (scalar(@line) == 1) ;
 229             $wordspace = ($width - $line_width) / (scalar(@line) - 1);
 230             $align='justify';
 231         }
 232         else
 233         {
 234             $align=($arg{'align'} eq 'justify') ? 'left' : $arg{'align'};
 235             $wordspace = $space_width;
 236         }
 237         $line_width += $wordspace * (scalar(@line) - 1);
 238
 239         if( $align eq 'justify')
 240         {
 241             foreach my $word (@line)
 242             {
 243                 $text_object->translate( $xpos, $ypos );
 244                 $text_object->text( $word );
 245                 $xpos += ($width{$word} + $wordspace) if (@line);
 246             }
 247             $endw = $width;
 248         }
 249         else
 250         {
 251             # calculate the left hand position of the line
 252             if( $align eq 'right' )
 253             {
 254                 $xpos += $width - $line_width;
 255             }
 256             elsif( $align eq 'center' )
 257             {
 258                 $xpos += ( $width / 2 ) - ( $line_width / 2 );
 259             }
 260
 261             # render the line
 262             $text_object->translate( $xpos, $ypos );
 263             $endw = $text_object->text( join("\x20", @line));
 264         }
 265         $first_line = 0;
 266     }#End of while(
 267     unshift(@paragraphs, join(' ',@paragraph)) if scalar(@paragraph);
 268     return ($endw, $ypos, join("\n", @paragraphs))
 269 }
 270
 271
 272 ################################################################
 273 # table - utility method to build multi-row, multicolumn tables
 274 ################################################################
 275 sub table
 276 {
 277     my $self    = shift;
 278     my $pdf     = shift;
 279     my $page    = shift;
 280     my $data    = shift;
 281     my %arg     = @_;
 282
 283     #=====================================
 284     # Mandatory Arguments Section
 285     #=====================================
 286     unless($pdf and $page and $data)
 287     {
 288         carp "Error: Mandatory parameter is missing pdf/page/data object!\n";
 289         return;
 290     }
 291
 292     # Validate mandatory argument data type
 293     croak "Error: Invalid pdf object received."  unless (ref($pdf) eq 'PDF::API2');
 294     croak "Error: Invalid page object received." unless (ref($page) eq 'PDF::API2::Page');
 295     croak "Error: Invalid data received."        unless ((ref($data) eq 'ARRAY') && scalar(@$data));
 296     croak "Error: Missing required settings."    unless (scalar(keys %arg));
 297
 298     # Validate settings key
 299     my %valid_settings_key = (
 300         x                     => 1,
 301         w                     => 1,
 302         start_y               => 1,
 303         start_h               => 1,
 304         next_y                => 1,
 305         next_h                => 1,
 306         lead                  => 1,
 307         padding               => 1,
 308         padding_right         => 1,
 309         padding_left          => 1,
 310         padding_top           => 1,
 311         padding_bottom        => 1,
 312         background_color      => 1,
 313         background_color_odd  => 1,
 314         background_color_even => 1,
 315         border                => 1,
 316         border_color          => 1,
 317         horizontal_borders    => 1,
 318         vertical_borders      => 1,
 319         font                  => 1,
 320         font_size             => 1,
 321         font_underline        => 1,
 322         font_color            => 1,
 323         font_color_even       => 1,
 324         font_color_odd        => 1,
 325         background_color_odd  => 1,
 326         background_color_even => 1,
 327         row_height            => 1,
 328         new_page_func         => 1,
 329         header_props          => 1,
 330         column_props          => 1,
 331         cell_props            => 1,
 332         max_word_length       => 1,
 333         cell_render_hook      => 1,
 334         default_text          => 1,
 335         num_header_rows       => 1,
 336     );
 337     foreach my $key (keys %arg)
 338     {
 339         # Provide backward compatibility
 340         $arg{$key} = delete $arg{"-$key"} if $key =~ s/^-//;
 341
 342         croak "Error: Invalid setting key '$key' received."
 343             unless exists $valid_settings_key{$key};
 344     }
 345
 346
 347     ######
 348     #TODO: Add code for header props compatibility and col_props comp....
 349     ######
 350     my ( $xbase, $ybase, $width, $height ) = ( undef, undef, undef, undef );
 351     # Could be 'int' or 'real' values
 352     $xbase  = $arg{'x'      } || -1;
 353     $ybase  = $arg{'start_y'} || -1;
 354     $width  = $arg{'w'      } || -1;
 355     $height = $arg{'start_h'} || -1;
 356
 357     # Global geometry parameters are also mandatory.
 358     unless( $xbase  > 0 ){ carp "Error: Left Edge of Table is NOT defined!\n";  return; }
 359     unless( $ybase  > 0 ){ carp "Error: Base Line of Table is NOT defined!\n"; return; }
 360     unless( $width  > 0 ){ carp "Error: Width of Table is NOT defined!\n";  return; }
 361     unless( $height > 0 ){ carp "Error: Height of Table is NOT defined!\n"; return; }
 362
 363     # Ensure default values for -next_y and -next_h
 364     my $next_y  = $arg{'next_y'} || $arg{'start_y'} || 0;
 365     my $next_h  = $arg{'next_h'} || $arg{'start_h'} || 0;
 366
 367     # Create Text Object
 368     my $txt     = $page->text;
 369
 370     # Set Default Properties
 371     my $fnt_name       = $arg{'font'            } || $pdf->corefont('Times',-encode => 'utf8');
 372     my $fnt_size       = $arg{'font_size'       } || 12;
 373     my $fnt_underline  = $arg{'font_underline'  } || undef; # merely stating undef is the intended default
 374     my $max_word_len   = $arg{'max_word_length' } || 20;
 375
 376     #=====================================
 377     # Table Header Section
 378     #=====================================
 379     # Disable header row into the table
 380     my $header_props = undef;
 381     my (@header_rows, @header_row_cell_props);
 382     # Check if the user enabled it ?
 383     if(defined $arg{'header_props'} and ref( $arg{'header_props'}) eq 'HASH')
 384     {
 385         # Transfer the reference to local variable
 386         $header_props = $arg{'header_props'};
 387
 388         # Check other params and put defaults if needed
 389         $header_props->{'repeat'        } = $header_props->{'repeat'        } || 0;
 390         $header_props->{'font'          } = $header_props->{'font'          } || $fnt_name;
 391         $header_props->{'font_color'    } = $header_props->{'font_color'    } || '#000066';
 392         $header_props->{'font_size'     } = $header_props->{'font_size'     } || $fnt_size + 2;
 393         $header_props->{'font_underline'} = $header_props->{'font_underline'} || $fnt_underline;
 394         $header_props->{'bg_color'      } = $header_props->{'bg_color'      } || '#FFFFAA';
 395         $header_props->{'justify'       } = $header_props->{'justify'       };
 396         $header_props->{num_header_rows } = $arg{num_header_rows } || 1;
 397     }
 398     #=====================================
 399     # Other Parameters check
 400     #=====================================
 401     my $lead          = $arg{'lead'          } || $fnt_size;
 402     my $pad_left      = $arg{'padding_left'  } || $arg{'padding'} || 0;
 403     my $pad_right     = $arg{'padding_right' } || $arg{'padding'} || 0;
 404     my $pad_top       = $arg{'padding_top'   } || $arg{'padding'} || 0;
 405     my $pad_bot       = $arg{'padding_bottom'} || $arg{'padding'} || 0;
 406     my $default_text  = $arg{'default_text'  } // '-';
 407     my $line_w        = defined $arg{'border'} ? $arg{'border'} : 1 ;
 408     my $horiz_borders = defined $arg{'horizontal_borders'}
 409         ? $arg{'horizontal_borders'}
 410         : $line_w;
 411     my $vert_borders  = defined $arg{'vertical_borders'}
 412         ? $arg{'vertical_borders'}
 413         : $line_w;
 414
 415     my $background_color_even   = $arg{'background_color_even'  } || $arg{'background_color'} || undef;
 416     my $background_color_odd    = $arg{'background_color_odd'   } || $arg{'background_color'} || undef;
 417     my $font_color_even         = $arg{'font_color_even'        } || $arg{'font_color'      } || 'black';
 418     my $font_color_odd          = $arg{'font_color_odd'         } || $arg{'font_color'      } || 'black';
 419     my $border_color            = $arg{'border_color'           } || 'black';
 420
 421     my $min_row_h   = $fnt_size + $pad_top + $pad_bot;
 422     my $row_h       = defined ($arg{'row_height'})
 423                                 &&
 424                     ($arg{'row_height'} > $min_row_h)
 425                                 ?
 426                      $arg{'row_height'} : $min_row_h;
 427
 428     my $pg_cnt      = 1;
 429     my $cur_y       = $ybase;
 430     my $cell_props  = $arg{cell_props} || [];   # per cell properties
 431
 432     #If there is no valid data array reference warn and return!
 433     if(ref $data ne 'ARRAY')
 434     {
 435         carp "Passed table data is not an ARRAY reference. It's actually a ref to ".ref($data);
 436         return ($page,0,$cur_y);
 437     }
 438
 439     # Copy the header row if header is enabled
 440     if (defined $header_props) {
 441       map { push @header_rows,           $$data[$_]       } (0..$header_props->{num_header_rows} - 1);
 442       map { push @header_row_cell_props, $$cell_props[$_] } (0..$header_props->{num_header_rows} - 1);
 443     }
 444     # Determine column widths based on content
 445
 446     #  an arrayref whose values are a hashref holding
 447     #  the minimum and maximum width of that column
 448     my $col_props =  $arg{'column_props'} || [];
 449
 450     # An array ref of arrayrefs whose values are
 451     #  the actual widths of the column/row intersection
 452     my $row_col_widths = [];
 453     # An array ref with the widths of the header row
 454     my @header_row_widths;
 455
 456     # Scalars that hold sum of the maximum and minimum widths of all columns
 457     my ( $max_col_w  , $min_col_w   ) = ( 0,0 );
 458     my ( $row, $col_name, $col_fnt_size, $col_fnt_underline, $space_w );
 459
 460     my $word_widths  = {};
 461     my $rows_height  = [];
 462     my $first_row    = 1;
 463
 464     for( my $row_idx = 0; $row_idx < scalar(@$data) ; $row_idx++ )
 465     {
 466         push @header_row_widths, [] if $row_idx < $header_props->{num_header_rows};
 467
 468         my $column_widths = []; #holds the width of each column
 469         # Init the height for this row
 470         $rows_height->[$row_idx] = 0;
 471
 472         for( my $column_idx = 0; $column_idx < scalar(@{$data->[$row_idx]}) ; $column_idx++ )
 473         {
 474             # look for font information for this column
 475             my ($cell_font, $cell_font_size, $cell_font_underline);
 476
 477             if( !$row_idx and ref $header_props )
 478             {
 479                 $cell_font           = $header_props->{'font'};
 480                 $cell_font_size      = $header_props->{'font_size'};
 481                 $cell_font_underline = $header_props->{'font_underline'};
 482             }
 483
 484             # Get the most specific value if none was already set from header_props
 485             $cell_font      ||= $cell_props->[$row_idx][$column_idx]->{'font'}
 486                             ||  $col_props->[$column_idx]->{'font'}
 487                             ||  $fnt_name;
 488
 489             $cell_font_size ||= $cell_props->[$row_idx][$column_idx]->{'font_size'}
 490                             ||  $col_props->[$column_idx]->{'font_size'}
 491                             ||  $fnt_size;
 492
 493             $cell_font_underline ||= $cell_props->[$row_idx][$column_idx]->{'font_underline'}
 494                                  ||  $col_props->[$column_idx]->{'font_underline'}
 495                                  ||  $fnt_underline;
 496
 497             # Set Font
 498
 499             # Set Font
 500             $txt->font( $cell_font, $cell_font_size );
 501
 502             # Set row height to biggest font size from row's cells
 503             if( $cell_font_size  > $rows_height->[$row_idx] )
 504             {
 505                 $rows_height->[$row_idx] = $cell_font_size;
 506             }
 507
 508             # This should fix a bug with very long words like serial numbers etc.
 509             if( $max_word_len > 0 )
 510             {
 511                 $data->[$row_idx][$column_idx] =~ s#(\S{$max_word_len})(?=\S)#$1 #g;
 512             }
 513
 514             # Init cell size limits
 515             $space_w                      = $txt->advancewidth( "\x20" );
 516             $column_widths->[$column_idx] = 0;
 517             $max_col_w                    = 0;
 518             $min_col_w                    = 0;
 519
 520             my @words = split( /\s+/, $data->[$row_idx][$column_idx] );
 521
 522             foreach( @words )
 523             {
 524                 unless( exists $word_widths->{$_} )
 525                 {   # Calculate the width of every word and add the space width to it
 526                     $word_widths->{$_} = $txt->advancewidth( $_ ) + $space_w;
 527                 }
 528
 529                 $column_widths->[$column_idx] += $word_widths->{$_};
 530                 $min_col_w                     = $word_widths->{$_} if( $word_widths->{$_} > $min_col_w );
 531                 $max_col_w                    += $word_widths->{$_};
 532             }
 533
 534             $min_col_w                    += $pad_left + $pad_right;
 535             $max_col_w                    += $pad_left + $pad_right;
 536             $column_widths->[$column_idx] += $pad_left + $pad_right;
 537
 538             # Keep a running total of the overall min and max widths
 539             $col_props->[$column_idx]->{'min_w'} ||= 0;
 540             $col_props->[$column_idx]->{'max_w'} ||= 0;
 541
 542             if( $min_col_w > $col_props->[$column_idx]->{'min_w'} )
 543             {   # Calculated Minimum Column Width is more than user-defined
 544                 $col_props->[$column_idx]->{'min_w'} = $min_col_w ;
 545             }
 546
 547             if( $max_col_w > $col_props->[$column_idx]->{'max_w'} )
 548             {   # Calculated Maximum Column Width is more than user-defined
 549                 $col_props->[$column_idx]->{'max_w'} = $max_col_w ;
 550             }
 551         }#End of for(my $column_idx....
 552
 553         $row_col_widths->[$row_idx] = $column_widths;
 554
 555         # Copy the calculated row properties of header row.
 556         if (ref $header_props && $row_idx < $header_props->{num_header_rows}) {
 557           push @header_row_widths, [ @{ $column_widths } ];
 558         }
 559     }
 560
 561     # Calc real column widths and expand table width if needed.
 562     my $calc_column_widths;
 563     ($calc_column_widths, $width) = CalcColumnWidths( $col_props, $width );
 564     my $num_cols = scalar @{ $calc_column_widths };
 565
 566     # Lets draw what we have!
 567     my $row_index    = 0;
 568     # Store header row height for later use if headers have to be repeated
 569     my @header_row_heights = @$rows_height[0 .. $header_props->{num_header_rows}-1];
 570
 571     my ( $gfx, $gfx_bg, $background_color, $font_color, $bot_marg, $table_top_y, $text_start);
 572
 573     my $remaining_header_rows = $header_props ? $header_props->{num_header_rows} : 0;
 574
 575     # Each iteration adds a new page as neccessary
 576     while(scalar(@{$data}))
 577     {
 578         my ($page_header);
 579         my $columns_number = 0;
 580
 581         if($pg_cnt == 1)
 582         {
 583             $table_top_y = $ybase;
 584             $bot_marg = $table_top_y - $height;
 585
 586             # Check for safety reasons
 587             if( $bot_marg < 0 )
 588             {   # This warning should remain i think
 589                 #carp "!!! Warning: !!! Incorrect Table Geometry! start_h (${height}) is above start_y (${table_top_y}). Setting bottom margin to end of sheet!\n";
 590                 $bot_marg = 0;
 591             }
 592
 593         }
 594         else
 595         {
 596             if(ref $arg{'new_page_func'})
 597             {
 598                 $page = &{$arg{'new_page_func'}};
 599             }
 600             else
 601             {
 602                 $page = $pdf->page;
 603             }
 604
 605             $table_top_y = $next_y;
 606             $bot_marg = $table_top_y - $next_h;
 607
 608             # Check for safety reasons
 609             if( $bot_marg < 0 )
 610             {   # This warning should remain i think
 611                 #carp "!!! Warning: !!! Incorrect Table Geometry! next_y or start_y (${next_y}) is above next_h or start_h (${next_h}). Setting bottom margin to end of sheet!\n";
 612                 $bot_marg = 0;
 613             }
 614
 615             if( ref $header_props and $header_props->{'repeat'})
 616             {
 617                 unshift @$data,           @header_rows;
 618                 unshift @$row_col_widths, @header_row_widths;
 619                 unshift @$rows_height,    @header_row_heights;
 620                 $remaining_header_rows = $header_props->{num_header_rows};
 621                 $first_row = 1;
 622             }
 623         }
 624
 625         $gfx_bg = $page->gfx;
 626         $txt = $page->text;
 627         $txt->font($fnt_name, $fnt_size);
 628
 629         $cur_y = $table_top_y;
 630
 631         if ($line_w)
 632         {
 633             $gfx = $page->gfx;
 634             $gfx->strokecolor($border_color);
 635             $gfx->linewidth($line_w);
 636
 637             # Draw the top line
 638             if ($horiz_borders)
 639             {
 640                 $gfx->move( $xbase , $cur_y );
 641                 $gfx->hline($xbase + $width );
 642             }
 643         }
 644         else
 645         {
 646             $gfx = undef;
 647         }
 648
 649         # Each iteration adds a row to the current page until the page is full
 650         #  or there are no more rows to add
 651         # Row_Loop
 652         while(scalar(@{$data}) and $cur_y-$row_h > $bot_marg)
 653         {
 654             # Remove the next item from $data
 655             my $record = shift @{$data};
 656
 657             # Get max columns number to know later how many vertical lines to draw
 658             $columns_number = scalar(@$record)
 659                 if scalar(@$record) > $columns_number;
 660
 661             # Get the next set of row related settings
 662             # Row Height
 663             my $pre_calculated_row_height = shift @$rows_height;
 664
 665             # Row cell widths
 666             my $record_widths = shift @$row_col_widths;
 667
 668             # Row coloumn props - TODO in another commit
 669
 670             # Row cell props - TODO in another commit
 671
 672
 673             # Choose colors for this row
 674             $background_color = ($row_index - $header_props->{num_header_rows}) % 2 ? $background_color_even  : $background_color_odd;
 675             $font_color       = ($row_index - $header_props->{num_header_rows}) % 2 ? $font_color_even        : $font_color_odd;
 676
 677             #Determine current row height
 678             my $current_row_height = $pad_top + $pre_calculated_row_height + $pad_bot;
 679
 680             # $row_h is the calculated global user requested row height.
 681             # It will be honored, only if it has bigger value than the calculated one.
 682             # TODO: It's questionable if padding should be inclided in this calculation or not
 683             if($current_row_height < $row_h){
 684                 $current_row_height = $row_h;
 685             }
 686
 687             # Define the font y base position for this line.
 688             $text_start      = $cur_y - ($current_row_height - $pad_bot);
 689
 690             my $cur_x        = $xbase;
 691             my $leftovers    = undef;   # Reference to text that is returned from textblock()
 692             my $do_leftovers = 0;
 693             my ($colspan, @vertical_lines);
 694
 695             # Process every cell(column) from current row
 696             for( my $column_idx = 0; $column_idx < scalar( @$record); $column_idx++ )
 697             {
 698                 next unless $col_props->[$column_idx]->{'max_w'};
 699                 next unless $col_props->[$column_idx]->{'min_w'};
 700                 $leftovers->[$column_idx] = undef;
 701
 702                 # look for font information for this cell
 703                 my ($cell_font, $cell_font_size, $cell_font_color, $cell_font_underline, $justify);
 704
 705                 if( $remaining_header_rows and ref $header_props)
 706                 {
 707                     $cell_font           = $header_props->{'font'};
 708                     $cell_font_size      = $header_props->{'font_size'};
 709                     $cell_font_color     = $header_props->{'font_color'};
 710                     $cell_font_underline = $header_props->{'font_underline'};
 711                     $justify             = $header_props->{'justify'};
 712                 }
 713
 714                 # Get the most specific value if none was already set from header_props
 715                 $cell_font       ||= $cell_props->[$row_index][$column_idx]->{'font'}
 716                                  ||  $col_props->[$column_idx]->{'font'}
 717                                  ||  $fnt_name;
 718
 719                 $cell_font_size  ||= $cell_props->[$row_index][$column_idx]->{'font_size'}
 720                                  ||  $col_props->[$column_idx]->{'font_size'}
 721                                  ||  $fnt_size;
 722
 723                 $cell_font_color ||= $cell_props->[$row_index][$column_idx]->{'font_color'}
 724                                  ||  $col_props->[$column_idx]->{'font_color'}
 725                                  ||  $font_color;
 726
 727                 $cell_font_underline ||= $cell_props->[$row_index][$column_idx]->{'font_underline'}
 728                                      ||  $col_props->[$column_idx]->{'font_underline'}
 729                                      ||  $fnt_underline;
 730
 731
 732                 $justify         ||= $cell_props->[$row_index][$column_idx]->{'justify'}
 733                                  ||  $col_props->[$column_idx]->{'justify'}
 734                                  ||  $arg{'justify'}
 735                                  ||  'left';
 736
 737                 # Init cell font object
 738                 $txt->font( $cell_font, $cell_font_size );
 739                 $txt->fillcolor($cell_font_color);
 740
 741                 # Added to resolve infite loop bug with returned undef values
 742                 $record->[$column_idx] //= $cell_props->[$row_index][$column_idx]->{'default_text'}
 743                                        //  $col_props->[$column_idx]->{'default_text'}
 744                                        //  $default_text;
 745
 746                 my $this_width;
 747                 if (!$remaining_header_rows && $cell_props->[$row_index + $header_props->{num_header_rows}][$column_idx]->{colspan}) {
 748                     $colspan = $cell_props->[$row_index + $header_props->{num_header_rows}][$column_idx]->{colspan};
 749                 } elsif ($remaining_header_rows && ($header_row_cell_props[$header_props->{num_header_rows} - $remaining_header_rows][$column_idx]->{colspan})) {
 750                     $colspan = $header_row_cell_props[$header_props->{num_header_rows} - $remaining_header_rows][$column_idx]->{colspan};
 751                 }
 752
 753                 if ($colspan) {
 754                     $colspan     = $num_cols - $column_idx if (-1 == $colspan);
 755                     my $last_idx = $column_idx + $colspan - 1;
 756                     $this_width  = sum @{ $calc_column_widths }[$column_idx..$last_idx];
 757                 } else {
 758                     $this_width = $calc_column_widths->[$column_idx];
 759                 }
 760
 761                 # If the content is wider than the specified width, we need to add the text as a text block
 762                 if( $record->[$column_idx] !~ m/(.\n.)/ and
 763                     $record_widths->[$column_idx] and
 764                     $record_widths->[$column_idx] <= $this_width
 765                 ){
 766                     my $space = $pad_left;
 767                     if ($justify eq 'right')
 768                     {
 769                         $space = $this_width -($txt->advancewidth($record->[$column_idx]) + $pad_right);
 770                     }
 771                     elsif ($justify eq 'center')
 772                     {
 773                         $space = ($this_width - $txt->advancewidth($record->[$column_idx])) / 2;
 774                     }
 775                     $txt->translate( $cur_x + $space, $text_start );
 776                     my %text_options;
 777                     $text_options{'-underline'} = $cell_font_underline if $cell_font_underline;
 778                     $txt->text( $record->[$column_idx], %text_options );
 779                 }
 780                 # Otherwise just use the $page->text() method
 781                 else
 782                 {
 783                     my ($width_of_last_line, $ypos_of_last_line, $left_over_text) = $self->text_block(
 784                         $txt,
 785                         $record->[$column_idx],
 786                         x        => $cur_x + $pad_left,
 787                         y        => $text_start,
 788                         w        => $this_width - $pad_left - $pad_right,
 789                         h        => $cur_y - $bot_marg - $pad_top - $pad_bot,
 790                         align    => $justify,
 791                         lead     => $lead
 792                     );
 793                     # Desi - Removed $lead because of fixed incorrect ypos bug in text_block
 794                     my  $current_cell_height = $cur_y - $ypos_of_last_line + $pad_bot;
 795                     if( $current_cell_height > $current_row_height )
 796                     {
 797                         $current_row_height = $current_cell_height;
 798                     }
 799
 800                     if( $left_over_text )
 801                     {
 802                         $leftovers->[$column_idx] = $left_over_text;
 803                         $do_leftovers = 1;
 804                     }
 805                 }
 806
 807                 # Hook to pass coordinates back - http://www.perlmonks.org/?node_id=754777
 808                 if (ref $arg{cell_render_hook} eq 'CODE') {
 809                    $arg{cell_render_hook}->(
 810                                             $page,
 811                                             $first_row,
 812                                             $row_index,
 813                                             $column_idx,
 814                                             $cur_x,
 815                                             $cur_y-$row_h,
 816                                             $calc_column_widths->[$column_idx],
 817                                             $row_h
 818                                            );
 819                 }
 820
 821                 $cur_x += $calc_column_widths->[$column_idx];
 822
 823                 push @vertical_lines, (!$colspan || (1 >= $colspan)) ? 1 : 0;
 824                 $colspan-- if $colspan;
 825             }
 826             if( $do_leftovers )
 827             {
 828                 unshift @$data, $leftovers;
 829                 unshift @$row_col_widths, $record_widths;
 830                 unshift @$rows_height, $pre_calculated_row_height;
 831             }
 832
 833             # Draw cell bgcolor
 834             # This has to be separately from the text loop
 835             #  because we do not know the final height of the cell until all text has been drawn
 836             $cur_x = $xbase;
 837             for(my $column_idx = 0 ; $column_idx < scalar(@$record) ; $column_idx++)
 838             {
 839                 my $cell_bg_color;
 840
 841                 if( $remaining_header_rows and ref $header_props)
 842                 {                                  #Compatibility                 Consistency with other props
 843                     $cell_bg_color = $header_props->{'bg_color'} || $header_props->{'background_color'};
 844                 }
 845
 846                 # Get the most specific value if none was already set from header_props
 847                 $cell_bg_color ||= $cell_props->[$row_index + $header_props->{num_header_rows}][$column_idx]->{'background_color'}
 848                                ||  $col_props->[$column_idx]->{'background_color'}
 849                                ||  $background_color;
 850
 851                 if ($cell_bg_color)
 852                 {
 853                     $gfx_bg->rect( $cur_x, $cur_y-$current_row_height, $calc_column_widths->[$column_idx], $current_row_height);
 854                     $gfx_bg->fillcolor($cell_bg_color);
 855                     $gfx_bg->fill();
 856                 }
 857                 $cur_x += $calc_column_widths->[$column_idx];
 858
 859                 if ($line_w && $vertical_lines[$column_idx] && ($column_idx != (scalar(@{ $record }) - 1))) {
 860                     $gfx->move($cur_x, $cur_y);
 861                     $gfx->vline($cur_y - $current_row_height);
 862                     $gfx->fillcolor($border_color);
 863                 }
 864             }#End of for(my $column_idx....
 865
 866             $cur_y -= $current_row_height;
 867             if ($gfx && $horiz_borders)
 868             {
 869                 $gfx->move(  $xbase , $cur_y );
 870                 $gfx->hline( $xbase + $width );
 871             }
 872
 873             $first_row = 0;
 874             if ($remaining_header_rows) {
 875               $remaining_header_rows--;
 876             } else {
 877               $row_index++ unless $do_leftovers;
 878             }
 879         }# End of Row_Loop
 880
 881         if ($gfx)
 882         {
 883             # Draw vertical lines
 884             if ($vert_borders)
 885             {
 886                 $gfx->move(  $xbase, $table_top_y);
 887                 $gfx->vline( $cur_y );
 888                 $gfx->move($xbase + sum(@{ $calc_column_widths }[0..$num_cols - 1]), $table_top_y);
 889                 $gfx->vline( $cur_y );
 890             }
 891
 892             # ACTUALLY draw all the lines
 893             $gfx->fillcolor( $border_color);
 894             $gfx->stroke;
 895         }
 896         $pg_cnt++;
 897     }# End of while(scalar(@{$data}))
 898
 899     return ($page,--$pg_cnt,$cur_y);
 900 }
 901
 902
 903 # calculate the column widths
 904 sub CalcColumnWidths
 905 {
 906     my $col_props   = shift;
 907     my $avail_width = shift;
 908     my $min_width   = 0;
 909
 910     my $calc_widths ;
 911
 912     for(my $j = 0; $j < scalar( @$col_props); $j++)
 913     {
 914         $min_width += $col_props->[$j]->{min_w} || 0;
 915     }
 916
 917     # I think this is the optimal variant when good view can be guaranateed
 918     if($avail_width < $min_width)
 919     {
 920         carp "!!! Warning !!!\n Calculated Mininal width($min_width) > Table width($avail_width).\n",
 921             ' Expanding table width to:',int($min_width)+1,' but this could lead to unexpected results.',"\n",
 922             ' Possible solutions:',"\n",
 923             '  0)Increase table width.',"\n",
 924             '  1)Decrease font size.',"\n",
 925             '  2)Choose a more narrow font.',"\n",
 926             '  3)Decrease "max_word_length" parameter.',"\n",
 927             '  4)Rotate page to landscape(if it is portrait).',"\n",
 928             '  5)Use larger paper size.',"\n",
 929             '!!! --------- !!!',"\n";
 930         $avail_width = int( $min_width) + 1;
 931
 932     }
 933
 934     # Calculate how much can be added to every column to fit the available width.
 935     for(my $j = 0; $j < scalar(@$col_props); $j++ )
 936     {
 937         $calc_widths->[$j] = $col_props->[$j]->{min_w} || 0;;
 938     }
 939
 940     my $span = 0;
 941     # Calculate how much can be added to every column to fit the available width
 942     $span = ($avail_width - $min_width) / scalar( @$col_props);
 943     for (my $j = 0; $j < scalar(@$col_props); $j++ ) {
 944       $calc_widths->[$j] = $col_props->[$j]->{min_w} + $span;
 945     }
 946
 947     return ($calc_widths,$avail_width);
 948 }
 949 1;
 950
 951 __END__
 952
 953 =pod
 954
 955 =head1 NAME
 956
 957 PDF::Table - A utility class for building table layouts in a PDF::API2 object.
 958
 959 =head1 SYNOPSIS
 960
 961  use PDF::API2;
 962  use PDF::Table;
 963
 964  my $pdftable = new PDF::Table;
 965  my $pdf = new PDF::API2(-file => "table_of_lorem.pdf");
 966  my $page = $pdf->page;
 967
 968  # some data to layout
 969  my $some_data =[
 970     ["1 Lorem ipsum dolor",
 971     "Donec odio neque, faucibus vel",
 972     "consequat quis, tincidunt vel, felis."],
 973     ["Nulla euismod sem eget neque.",
 974     "Donec odio neque",
 975     "Sed eu velit."],
 976     #... and so on
 977  ];
 978
 979  $left_edge_of_table = 50;
 980  # build the table layout
 981  $pdftable->table(
 982      # required params
 983      $pdf,
 984      $page,
 985      $some_data,
 986      x => $left_edge_of_table,
 987      w => 495,
 988      start_y => 500,
 989      start_h => 300,
 990      # some optional params
 991      next_y  => 750,
 992      next_h  => 500,
 993      padding => 5,
 994      padding_right => 10,
 995      background_color_odd  => "gray",
 996      background_color_even => "lightblue", #cell background color for even rows
 997   );
 998
 999  # do other stuff with $pdf
1000  $pdf->saveas();
1001 ...
1002
1003 =head1 EXAMPLE
1004
1005 For a complete working example or initial script look into distribution`s 'examples' folder.
1006
1007
1008 =head1 DESCRIPTION
1009
1010 This class is a utility for use with the PDF::API2 module from CPAN.
1011 It can be used to display text data in a table layout within a PDF.
1012 The text data must be in a 2D array (such as returned by a DBI statement handle fetchall_arrayref() call).
1013 The PDF::Table will automatically add as many new pages as necessary to display all of the data.
1014 Various layout properties, such as font, font size, and cell padding and background color can be specified for each column and/or for even/odd rows.
1015 Also a (non)repeated header row with different layout properties can be specified.
1016
1017 See the L</METHODS> section for complete documentation of every parameter.
1018
1019 =head1 METHODS
1020
1021 =head2 new()
1022
1023     my $pdf_table = new PDF::Table;
1024
1025 =over
1026
1027 =item Description
1028
1029 Creates a new instance of the class. (to be improved)
1030
1031 =item Parameters
1032
1033 There are no parameters.
1034
1035 =item Returns
1036
1037 Reference to the new instance
1038
1039 =back
1040
1041 =head2 table()
1042
1043     my ($final_page, $number_of_pages, $final_y) = table($pdf, $page, $data, %settings)
1044
1045 =over
1046
1047 =item Description
1048
1049 Generates a multi-row, multi-column table into an existing PDF document based on provided data set and settings.
1050
1051 =item Parameters
1052
1053     $pdf      - a PDF::API2 instance representing the document being created
1054     $page     - a PDF::API2::Page instance representing the current page of the document
1055     $data     - an ARRAY reference to a 2D data structure that will be used to build the table
1056     %settings - HASH with geometry and formatting parameters.
1057
1058 For full %settings description see section L</Table settings> below.
1059
1060 This method will add more pages to the pdf instance as required based on the formatting options and the amount of data.
1061
1062 =item Returns
1063
1064 The return value is a 3 items list where
1065
1066     $final_page - The first item is a PDF::API2::Page instance that the table ends on
1067     $number_of_pages - The second item is the count of pages that the table spans on
1068     $final_y - The third item is the Y coordinate of the table bottom so that additional content can be added in the same document.
1069
1070 =item Example
1071
1072     my $pdf  = new PDF::API2;
1073     my $page = $pdf->page();
1074     my $data = [
1075         ['foo1','bar1','baz1'],
1076         ['foo2','bar2','baz2']
1077     ];
1078     my %settings = (
1079         x       => 10,
1080         w       => 570,
1081         start_y => 220,
1082         start_h => 180,
1083     );
1084
1085     my ($final_page, $number_of_pages, $final_y) = $pdftable->table( $pdf, $page, $data, %options );
1086
1087 =back
1088
1089 =head3 Table settings
1090
1091 =head4 Mandatory
1092
1093 There are some mandatory parameteres for setting table geometry and position across page(s)
1094
1095 =over
1096
1097 =item B<x> - X coordinate of upper left corner of the table. Left edge of the sheet is 0.
1098
1099 B<Value:> can be any whole number satisfying 0 =< X < PageWidth
1100 B<Default:> No default value
1101
1102     x => 10
1103
1104 =item B<start_y> - Y coordinate of upper left corner of the table at the initial page.
1105
1106 B<Value:> can be any whole number satisfying 0 < start_y < PageHeight (depending on space availability when embedding a table)
1107 B<Default:> No default value
1108
1109     start_y => 327
1110
1111 =item B<w> - width of the table starting from X.
1112
1113 B<Value:> can be any whole number satisfying 0 < w < PageWidth - x
1114 B<Default:> No default value
1115
1116     w  => 570
1117
1118 =item B<start_h> - Height of the table on the initial page
1119
1120 B<Value:> can be any whole number satisfying 0 < start_h < PageHeight - Current Y position
1121 B<Default:> No default value
1122
1123     start_h => 250
1124
1125 =back
1126
1127 =head4 Optional
1128
1129 =over
1130
1131 =item B<next_h> - Height of the table on any additional page
1132
1133 B<Value:> can be any whole number satisfying 0 < next_h < PageHeight
1134 B<Default:> Value of param B<'start_h'>
1135
1136     next_h  => 700
1137
1138 =item B<next_y> - Y coordinate of upper left corner of the table at any additional page.
1139
1140 B<Value:> can be any whole number satisfying 0 < next_y < PageHeight
1141 B<Default:> Value of param B<'start_y'>
1142
1143     next_y  => 750
1144
1145 =item B<max_word_length> - Breaks long words (like serial numbers hashes etc.) by adding a space after every Nth symbol
1146
1147 B<Value:> can be any whole positive number
1148 B<Default:> 20
1149
1150     max_word_length => 20    # Will add a space after every 20 symbols
1151
1152 =item B<padding> - Padding applied to every cell
1153
1154 =item B<padding_top>    - top cell padding, overrides 'padding'
1155
1156 =item B<padding_right>  - right cell padding, overrides 'padding'
1157
1158 =item B<padding_left>   - left cell padding, overrides 'padding'
1159
1160 =item B<padding_bottom> - bottom padding, overrides 'padding'
1161
1162 B<Value:> can be any whole positive number
1163
1164 B<Default padding:> 0
1165
1166 B<Default padding_*> $padding
1167
1168     padding        => 5      # all sides cell padding
1169     padding_top    => 8,     # top cell padding, overrides 'padding'
1170     padding_right  => 6,     # right cell padding, overrides 'padding'
1171     padding_left   => 2,     # left cell padding, overrides 'padding'
1172     padding_bottom => undef  # bottom padding will be 5 as it will fallback to 'padding'
1173
1174 =item B<border> - Width of table border lines.
1175
1176 =item B<horizontal_borders> - Width of horizontal border lines. Overrides 'border' value.
1177
1178 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1179
1180 B<Value:> can be any whole positive number. When set to 0 will disable border lines.
1181 B<Default:> 1
1182
1183     border             => 3     # border width is 3
1184     horizontal_borders => 1     # horizontal borders will be 1 overriding 3
1185     vertical_borders   => undef # vertical borders will be 3 as it will fallback to 'border'
1186
1187 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1188
1189 B<Value:> Color specifier as 'name' or 'HEX'
1190 B<Default:> 'black'
1191
1192     border_color => 'red'
1193
1194 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the table
1195
1196 B<Value:> can be any PDF::API2::Resource::* type of font
1197 B<Default:> 'Times' with UTF8 encoding
1198
1199     font => $pdf->corefont("Helvetica", -encoding => "utf8")
1200
1201 =item B<font_size> - Default size of the font that will be used across the table
1202
1203 B<Value:> can be any positive number
1204 B<Default:> 12
1205
1206     font_size => 16
1207
1208 =item B<font_color> - Font color for all rows
1209
1210 =item B<font_color_odd> - Font color for odd rows
1211
1212 =item B<font_color_even> - Font color for even rows
1213
1214 =item B<font_underline> - Font underline of the header row
1215
1216 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1217 B<Default:> none
1218
1219 =item B<background_color_odd> - Background color for odd rows
1220
1221 =item B<background_color_even> - Background color for even rows
1222
1223 B<Value:> Color specifier as 'name' or 'HEX'
1224 B<Default:> 'black' font on 'white' background
1225
1226     font_color            => '#333333'
1227     font_color_odd        => 'purple'
1228     font_color_even       => '#00FF00'
1229     background_color_odd  => 'gray'
1230     background_color_even => 'lightblue'
1231
1232 =item B<row_height> - Desired row height but it will be honored only if row_height > font_size + padding_top + padding_bottom
1233
1234 B<Value:> can be any whole positive number
1235 B<Default:> font_size + padding_top + padding_bottom
1236
1237     row_height => 24
1238
1239 =item B<new_page_func> - CODE reference to a function that returns a PDF::API2::Page instance.
1240
1241 If used the parameter 'new_page_func' must be a function reference which when executed will create a new page and will return the object back to the module.
1242 For example you can use it to put Page Title, Page Frame, Page Numbers and other staff that you need.
1243 Also if you need some different type of paper size and orientation than the default A4-Portrait for example B2-Landscape you can use this function ref to set it up for you. For more info about creating pages refer to PDF::API2 PAGE METHODS Section.
1244 Don't forget that your function must return a page object created with PDF::API2 page() method.
1245
1246     new_page_func  => $code_ref
1247
1248 =item B<header_props> - HASH reference to specific settings for the Header row of the table. See section L</Header Row Properties> below
1249
1250     header_props => $hdr_props
1251
1252 =item B<column_props> - HASH reference to specific settings for each column of the table. See section L</Column Properties> below
1253
1254     column_props => $col_props
1255
1256 =item B<cell_props> - HASH reference to specific settings for each column of the table. See section L</Cell Properties> below
1257
1258     cell_props => $cel_props
1259
1260 =item B<cell_render_hook> - CODE reference to a function called with the current cell coordinates.  If used the parameter 'cell_render_hook' must be a function reference. It is most useful for creating a url link inside of a cell. The following example adds a link in the first column of each non-header row:
1261
1262     cell_render_hook  => sub {
1263         my ($page, $first_row, $row, $col, $x, $y, $w, $h) = @_;
1264
1265         # Do nothing except for first column (and not a header row)
1266         return unless ($col == 0);
1267         return if ($first_row);
1268
1269         # Create link
1270         my $value = $list_of_vals[$row-1];
1271         my $url = "https://${hostname}/app/${value}";
1272
1273         my $annot = $page->annotation();
1274         $annot->url( $url, -rect => [$x, $y, $x+$w, $y+$h] );
1275     },
1276
1277 =back
1278
1279 =head4 Header Row Properties
1280
1281 If the 'header_props' parameter is used, it should be a hashref. Passing an empty HASH will trigger a header row initialised with Default values.
1282 There is no 'data' variable for the content, because the module asumes that first table row will become the header row. It will copy this row and put it on every new page if 'repeat' param is set.
1283
1284 =over
1285
1286 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the header row
1287
1288 B<Value:> can be any PDF::API2::Resource::* type of font
1289 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1290
1291 =item B<font_size> - Font size of the header row
1292
1293 B<Value:> can be any positive number
1294 B<Default:> 'font_size' of the table + 2
1295
1296 =item B<font_color> - Font color of the header row
1297
1298 B<Value:> Color specifier as 'name' or 'HEX'
1299 B<Default:> '#000066'
1300
1301 =item B<font_underline> - Font underline of the header row
1302
1303 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1304 B<Default:> none
1305
1306 =item B<bg_color> - Background color of the header row
1307
1308 B<Value:> Color specifier as 'name' or 'HEX'
1309 B<Default:> #FFFFAA
1310
1311 =item B<repeat> - Flag showing if header row should be repeated on every new page
1312
1313 B<Value:> 0,1   1-Yes/True, 0-No/False
1314 B<Default:> 0
1315
1316 =item B<justify> - Alignment of text in the header row.
1317
1318 B<Value:> One of 'left', 'right', 'center'
1319 B<Default:> Same as column alignment (or 'left' if undefined)
1320
1321     my $hdr_props =
1322     {
1323         font       => $pdf->corefont("Helvetica", -encoding => "utf8"),
1324         font_size  => 18,
1325         font_color => '#004444',
1326         bg_color   => 'yellow',
1327         repeat     => 1,
1328         justify    => 'center'
1329     };
1330
1331 =back
1332
1333 =head4 Column Properties
1334
1335 If the 'column_props' parameter is used, it should be an arrayref of hashrefs,
1336 with one hashref for each column of the table. The columns are counted from left to right so the hash reference at $col_props[0] will hold properties for the first column from left to right.
1337 If you DO NOT want to give properties for a column but to give for another just insert and empty hash reference into the array for the column that you want to skip. This will cause the counting to proceed as expected and the properties to be applyed at the right columns.
1338
1339 Each hashref can contain any of the keys shown below:
1340
1341 =over
1342
1343 =item B<min_w> - Minimum width of this column. Auto calculation will try its best to honour this param but aplying it is NOT guaranteed.
1344
1345 B<Value:> can be any whole number satisfying 0 < min_w < w
1346 B<Default:> Auto calculated
1347
1348 =item B<max_w> - Maximum width of this column. Auto calculation will try its best to honour this param but aplying it is NOT guaranteed.
1349
1350 B<Value:> can be any whole number satisfying 0 < max_w < w
1351 B<Default:> Auto calculated
1352
1353 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this column
1354
1355 B<Value:> can be any PDF::API2::Resource::* type of font
1356 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1357
1358 =item B<font_size> - Font size of this column
1359
1360 B<Value:> can be any positive number
1361 B<Default:> 'font_size' of the table.
1362
1363 =item B<font_color> - Font color of this column
1364
1365 B<Value:> Color specifier as 'name' or 'HEX'
1366 B<Default:> 'font_color' of the table.
1367
1368 =item B<font_underline> - Font underline of this cell
1369
1370 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1371 B<Default:> none
1372
1373 =item B<background_color> - Background color of this column
1374
1375 B<Value:> Color specifier as 'name' or 'HEX'
1376 B<Default:> undef
1377
1378 =item B<justify> - Alignment of text in this column
1379
1380 B<Value:> One of 'left', 'right', 'center'
1381 B<Default:> 'left'
1382
1383 Example:
1384
1385     my $col_props = [
1386         {},# This is an empty hash so the next one will hold the properties for the second column from left to right.
1387         {
1388             min_w => 100,       # Minimum column width of 100.
1389             max_w => 150,       # Maximum column width of 150 .
1390             justify => 'right', # Right text alignment
1391             font => $pdf->corefont("Helvetica", -encoding => "latin1"),
1392             font_size => 10,
1393             font_color=> 'blue',
1394             background_color => '#FFFF00',
1395         },
1396         # etc.
1397     ];
1398
1399 =back
1400
1401 NOTE: If 'min_w' and/or 'max_w' parameter is used in 'col_props', have in mind that it may be overridden by the calculated minimum/maximum cell witdh so that table can be created.
1402 When this happens a warning will be issued with some advises what can be done.
1403 In cases of a conflict between column formatting and odd/even row formatting, 'col_props' will override odd/even.
1404
1405 =head4 Cell Properties
1406
1407 If the 'cell_props' parameter is used, it should be an arrayref with arrays of hashrefs
1408 (of the same dimension as the data array) with one hashref for each cell of the table.
1409
1410 Each hashref can contain any of the keys shown below:
1411
1412 =over
1413
1414 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this cell
1415
1416 B<Value:> can be any PDF::API2::Resource::* type of font
1417 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1418
1419 =item B<font_size> - Font size of this cell
1420
1421 B<Value:> can be any positive number
1422 B<Default:> 'font_size' of the table.
1423
1424 =item B<font_color> - Font color of this cell
1425
1426 B<Value:> Color specifier as 'name' or 'HEX'
1427 B<Default:> 'font_color' of the table.
1428
1429 =item B<font_underline> - Font underline of this cell
1430
1431 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1432 B<Default:> none
1433
1434 =item B<background_color> - Background color of this cell
1435
1436 B<Value:> Color specifier as 'name' or 'HEX'
1437 B<Default:> undef
1438
1439 =item B<justify> - Alignment of text in this cell
1440
1441 B<Value:> One of 'left', 'right', 'center'
1442 B<Default:> 'left'
1443
1444 Example:
1445
1446     my $cell_props = [
1447         [ #This array is for the first row. If header_props is defined it will overwrite these settings.
1448             {    #Row 1 cell 1
1449                 background_color => '#AAAA00',
1450                 font_color       => 'yellow',
1451                 font_underline   => [ 2, 2 ],
1452             },
1453
1454             # etc.
1455         ],
1456         [#Row 2
1457             {    #Row 2 cell 1
1458                 background_color => '#CCCC00',
1459                 font_color       => 'blue',
1460             },
1461             {    #Row 2 cell 2
1462                 background_color => '#BBBB00',
1463                 font_color       => 'red',
1464             },
1465             # etc.
1466         ],
1467         # etc.
1468     ];
1469
1470     OR
1471
1472     my $cell_props = [];
1473     $cell_props->[1][0] = {
1474         #Row 2 cell 1
1475         background_color => '#CCCC00',
1476         font_color       => 'blue',
1477     };
1478
1479 =back
1480
1481 NOTE: In case of a conflict between column, odd/even and cell formatting, cell formatting will overwrite the other two.
1482 In case of a conflict between header row and cell formatting, header formatting will override cell.
1483
1484 =head2 text_block()
1485
1486     my ($width_of_last_line, $ypos_of_last_line, $left_over_text) = text_block( $txt, $data, %settings)
1487
1488 =over
1489
1490 =item Description
1491
1492 Utility method to create a block of text. The block may contain multiple paragraphs.
1493 It is mainly used internaly but you can use it from outside for placing formatted text anywhere on the sheet.
1494
1495 NOTE: This method will NOT add more pages to the pdf instance if the space is not enough to place the string inside the block.
1496 Leftover text will be returned and has to be handled by the caller - i.e. add a new page and a new block with the leftover.
1497
1498 =item Parameters
1499
1500     $txt  - a PDF::API2::Page::Text instance representing the text tool
1501     $data - a string that will be placed inside the block
1502     %settings - HASH with geometry and formatting parameters.
1503
1504 =item Reuturns
1505
1506 The return value is a 3 items list where
1507
1508     $width_of_last_line - Width of last line in the block
1509     $final_y - The Y coordinate of the block bottom so that additional content can be added after it
1510     $left_over_text - Text that was did not fit in the provided box geometry.
1511
1512 =item Example
1513
1514     # PDF::API2 objects
1515     my $page = $pdf->page;
1516     my $txt  = $page->text;
1517
1518     my %settings = (
1519         x => 10,
1520         y => 570,
1521         w => 220,
1522         h => 180
1523
1524         #OPTIONAL PARAMS
1525         lead     => $font_size | $distance_between_lines,
1526         align    => "left|right|center|justify|fulljustify",
1527         hang     => $optional_hanging_indent,
1528         Only one of the subsequent 3params can be given.
1529         They override each other.-parspace is the weightest
1530         parspace => $optional_vertical_space_before_first_paragraph,
1531         flindent => $optional_indent_of_first_line,
1532         fpindent => $optional_indent_of_first_paragraph,
1533         indent   => $optional_indent_of_text_to_every_non_first_line,
1534     );
1535
1536     my ( $width_of_last_line, $final_y, $left_over_text ) = $pdftable->text_block( $txt, $data, %settings );
1537
1538 =back
1539
1540 =head1 VERSION
1541
1542 0.9.7
1543
1544 =head1 AUTHOR
1545
1546 Daemmon Hughes
1547
1548 =head1 DEVELOPMENT
1549
1550 Further development since Ver: 0.02 - Desislav Kamenov
1551
1552 =head1 COPYRIGHT AND LICENSE
1553
1554 Copyright (C) 2006 by Daemmon Hughes, portions Copyright 2004 Stone
1555 Environmental Inc. (www.stone-env.com) All Rights Reserved.
1556
1557 This library is free software; you can redistribute it and/or modify
1558 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1559 at your option, any later version of Perl 5 you may have available.
1560
1561 =head1 PLUGS
1562
1563 =over
1564
1565 =item by Daemmon Hughes
1566
1567 Much of the work on this module was sponsered by
1568 Stone Environmental Inc. (www.stone-env.com).
1569
1570 The text_block() method is a slightly modified copy of the one from
1571 Rick Measham's PDF::API2 tutorial at
1572 http://pdfapi2.sourceforge.net/cgi-bin/view/Main/YourFirstDocument
1573
1574 =item by Desislav Kamenov (@deskata on Twitter)
1575
1576 The development of this module was supported by SEEBURGER AG (www.seeburger.com) till year 2007
1577
1578 Thanks to my friends Krasimir Berov and Alex Kantchev for helpful tips and QA during development of versions 0.9.0 to 0.9.5
1579
1580 Thanks to all GitHub contributors!
1581
1582 =back
1583
1584 =head1 CONTRIBUTION
1585
1586 Hey PDF::Table is on GitHub. You are more than welcome to contribute!
1587
1588 https://github.com/kamenov/PDF-Table
1589
1590 =head1 SEE ALSO
1591
1592 L<PDF::API2>
1593
1594 =cut
1595