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