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                 for my $idx (0 .. $header_props->{num_header_rows} - 1) {
 618                   unshift @$data,           [ @{ $header_rows[$idx]      } ];
 619                   unshift @$row_col_widths, [ @{ $header_row_widths[$idx] } ];
 620                   unshift @$rows_height,    $header_row_heights[$idx];
 621                 }
 622                 $remaining_header_rows = $header_props->{num_header_rows};
 623                 $first_row = 1;
 624             }
 625         }
 626
 627         $gfx_bg = $page->gfx;
 628         $txt = $page->text;
 629         $txt->font($fnt_name, $fnt_size);
 630
 631         $cur_y = $table_top_y;
 632
 633         if ($line_w)
 634         {
 635             $gfx = $page->gfx;
 636             $gfx->strokecolor($border_color);
 637             $gfx->linewidth($line_w);
 638
 639             # Draw the top line
 640             if ($horiz_borders)
 641             {
 642                 $gfx->move( $xbase , $cur_y );
 643                 $gfx->hline($xbase + $width );
 644             }
 645         }
 646         else
 647         {
 648             $gfx = undef;
 649         }
 650
 651         # Each iteration adds a row to the current page until the page is full
 652         #  or there are no more rows to add
 653         # Row_Loop
 654         while(scalar(@{$data}) and $cur_y-$row_h > $bot_marg)
 655         {
 656             # Remove the next item from $data
 657             my $record = shift @{$data};
 658
 659             # Get max columns number to know later how many vertical lines to draw
 660             $columns_number = scalar(@$record)
 661                 if scalar(@$record) > $columns_number;
 662
 663             # Get the next set of row related settings
 664             # Row Height
 665             my $pre_calculated_row_height = shift @$rows_height;
 666
 667             # Row cell widths
 668             my $record_widths = shift @$row_col_widths;
 669
 670             # Row coloumn props - TODO in another commit
 671
 672             # Row cell props - TODO in another commit
 673
 674
 675             # Choose colors for this row
 676             $background_color = $row_index % 2 ? $background_color_even  : $background_color_odd;
 677             $font_color       = $row_index % 2 ? $font_color_even        : $font_color_odd;
 678
 679             #Determine current row height
 680             my $current_row_height = $pad_top + $pre_calculated_row_height + $pad_bot;
 681
 682             # $row_h is the calculated global user requested row height.
 683             # It will be honored, only if it has bigger value than the calculated one.
 684             # TODO: It's questionable if padding should be inclided in this calculation or not
 685             if($current_row_height < $row_h){
 686                 $current_row_height = $row_h;
 687             }
 688
 689             # Define the font y base position for this line.
 690             $text_start      = $cur_y - ($current_row_height - $pad_bot);
 691
 692             my $cur_x        = $xbase;
 693             my $leftovers    = undef;   # Reference to text that is returned from textblock()
 694             my $do_leftovers = 0;
 695             my ($colspan, @vertical_lines);
 696
 697             # Process every cell(column) from current row
 698             for( my $column_idx = 0; $column_idx < scalar( @$record); $column_idx++ )
 699             {
 700                 next unless $col_props->[$column_idx]->{'max_w'};
 701                 next unless $col_props->[$column_idx]->{'min_w'};
 702                 $leftovers->[$column_idx] = undef;
 703
 704                 # look for font information for this cell
 705                 my ($cell_font, $cell_font_size, $cell_font_color, $cell_font_underline, $justify);
 706
 707                 if( $remaining_header_rows and ref $header_props)
 708                 {
 709                     $cell_font           = $header_props->{'font'};
 710                     $cell_font_size      = $header_props->{'font_size'};
 711                     $cell_font_color     = $header_props->{'font_color'};
 712                     $cell_font_underline = $header_props->{'font_underline'};
 713                     $justify             = $header_props->{'justify'};
 714                 }
 715
 716                 # Get the most specific value if none was already set from header_props
 717                 $cell_font       ||= $cell_props->[$row_index][$column_idx]->{'font'}
 718                                  ||  $col_props->[$column_idx]->{'font'}
 719                                  ||  $fnt_name;
 720
 721                 $cell_font_size  ||= $cell_props->[$row_index][$column_idx]->{'font_size'}
 722                                  ||  $col_props->[$column_idx]->{'font_size'}
 723                                  ||  $fnt_size;
 724
 725                 $cell_font_color ||= $cell_props->[$row_index][$column_idx]->{'font_color'}
 726                                  ||  $col_props->[$column_idx]->{'font_color'}
 727                                  ||  $font_color;
 728
 729                 $cell_font_underline ||= $cell_props->[$row_index][$column_idx]->{'font_underline'}
 730                                      ||  $col_props->[$column_idx]->{'font_underline'}
 731                                      ||  $fnt_underline;
 732
 733
 734                 $justify         ||= $cell_props->[$row_index][$column_idx]->{'justify'}
 735                                  ||  $col_props->[$column_idx]->{'justify'}
 736                                  ||  $arg{'justify'}
 737                                  ||  'left';
 738
 739                 # Init cell font object
 740                 $txt->font( $cell_font, $cell_font_size );
 741                 $txt->fillcolor($cell_font_color);
 742
 743                 # Added to resolve infite loop bug with returned undef values
 744                 $record->[$column_idx] //= $cell_props->[$row_index][$column_idx]->{'default_text'}
 745                                        //  $col_props->[$column_idx]->{'default_text'}
 746                                        //  $default_text;
 747
 748                 my $this_width;
 749                 if (!$remaining_header_rows && $cell_props->[$row_index][$column_idx]->{colspan}) {
 750                     $colspan = $cell_props->[$row_index][$column_idx]->{colspan};
 751                 } elsif ($remaining_header_rows && $header_row_cell_props[$header_props->{num_header_rows} - $remaining_header_rows][$column_idx]->{colspan}) {
 752                     $colspan = $header_row_cell_props[$header_props->{num_header_rows} - $remaining_header_rows][$column_idx]->{colspan};
 753                 }
 754
 755                 if ($colspan) {
 756                     $colspan     = $num_cols - $column_idx if (-1 == $colspan);
 757                     my $last_idx = $column_idx + $colspan - 1;
 758                     $this_width  = sum @{ $calc_column_widths }[$column_idx..$last_idx];
 759                 } else {
 760                     $this_width = $calc_column_widths->[$column_idx];
 761                 }
 762
 763                 # If the content is wider than the specified width, we need to add the text as a text block
 764                 if( $record->[$column_idx] !~ m/(.\n.)/ and
 765                     $record_widths->[$column_idx] and
 766                     $record_widths->[$column_idx] <= $this_width
 767                 ){
 768                     my $space = $pad_left;
 769                     if ($justify eq 'right')
 770                     {
 771                         $space = $this_width -($txt->advancewidth($record->[$column_idx]) + $pad_right);
 772                     }
 773                     elsif ($justify eq 'center')
 774                     {
 775                         $space = ($this_width - $txt->advancewidth($record->[$column_idx])) / 2;
 776                     }
 777                     $txt->translate( $cur_x + $space, $text_start );
 778                     my %text_options;
 779                     $text_options{'-underline'} = $cell_font_underline if $cell_font_underline;
 780                     $txt->text( $record->[$column_idx], %text_options );
 781                 }
 782                 # Otherwise just use the $page->text() method
 783                 else
 784                 {
 785                     my ($width_of_last_line, $ypos_of_last_line, $left_over_text) = $self->text_block(
 786                         $txt,
 787                         $record->[$column_idx],
 788                         x        => $cur_x + $pad_left,
 789                         y        => $text_start,
 790                         w        => $this_width - $pad_left - $pad_right,
 791                         h        => $cur_y - $bot_marg - $pad_top - $pad_bot,
 792                         align    => $justify,
 793                         lead     => $lead
 794                     );
 795                     # Desi - Removed $lead because of fixed incorrect ypos bug in text_block
 796                     my  $current_cell_height = $cur_y - $ypos_of_last_line + $pad_bot;
 797                     if( $current_cell_height > $current_row_height )
 798                     {
 799                         $current_row_height = $current_cell_height;
 800                     }
 801
 802                     if( $left_over_text )
 803                     {
 804                         $leftovers->[$column_idx] = $left_over_text;
 805                         $do_leftovers = 1;
 806                     }
 807                 }
 808
 809                 # Hook to pass coordinates back - http://www.perlmonks.org/?node_id=754777
 810                 if (ref $arg{cell_render_hook} eq 'CODE') {
 811                    $arg{cell_render_hook}->(
 812                                             $page,
 813                                             $first_row,
 814                                             $row_index,
 815                                             $column_idx,
 816                                             $cur_x,
 817                                             $cur_y-$row_h,
 818                                             $calc_column_widths->[$column_idx],
 819                                             $row_h
 820                                            );
 821                 }
 822
 823                 $cur_x += $calc_column_widths->[$column_idx];
 824
 825                 push @vertical_lines, (!$colspan || (1 >= $colspan)) ? 1 : 0;
 826                 $colspan-- if $colspan;
 827             }
 828             if( $do_leftovers )
 829             {
 830                 unshift @$data, $leftovers;
 831                 unshift @$row_col_widths, $record_widths;
 832                 unshift @$rows_height, $pre_calculated_row_height;
 833             }
 834
 835             # Draw cell bgcolor
 836             # This has to be separately from the text loop
 837             #  because we do not know the final height of the cell until all text has been drawn
 838             $cur_x = $xbase;
 839             for(my $column_idx = 0 ; $column_idx < scalar(@$record) ; $column_idx++)
 840             {
 841                 my $cell_bg_color;
 842
 843                 if( $remaining_header_rows and ref $header_props)
 844                 {                                  #Compatibility                 Consistency with other props
 845                     $cell_bg_color = $header_props->{'bg_color'} || $header_props->{'background_color'};
 846                 }
 847
 848                 # Get the most specific value if none was already set from header_props
 849                 $cell_bg_color ||= $cell_props->[$row_index][$column_idx]->{'background_color'}
 850                                ||  $col_props->[$column_idx]->{'background_color'}
 851                                ||  $background_color;
 852
 853                 if ($cell_bg_color)
 854                 {
 855                     $gfx_bg->rect( $cur_x, $cur_y-$current_row_height, $calc_column_widths->[$column_idx], $current_row_height);
 856                     $gfx_bg->fillcolor($cell_bg_color);
 857                     $gfx_bg->fill();
 858                 }
 859                 $cur_x += $calc_column_widths->[$column_idx];
 860
 861                 if ($line_w && $vertical_lines[$column_idx] && ($column_idx != (scalar(@{ $record }) - 1))) {
 862                     $gfx->move($cur_x, $cur_y);
 863                     $gfx->vline($cur_y - $row_h);
 864                     $gfx->fillcolor($border_color);
 865                 }
 866             }#End of for(my $column_idx....
 867
 868             $cur_y -= $current_row_height;
 869             if ($gfx && $horiz_borders)
 870             {
 871                 $gfx->move(  $xbase , $cur_y );
 872                 $gfx->hline( $xbase + $width );
 873             }
 874
 875             $first_row = 0;
 876             if ($remaining_header_rows) {
 877               $remaining_header_rows--;
 878             } else {
 879               $row_index++ unless $do_leftovers;
 880             }
 881         }# End of Row_Loop
 882
 883         if ($gfx)
 884         {
 885             # Draw vertical lines
 886             if ($vert_borders)
 887             {
 888                 $gfx->move(  $xbase, $table_top_y);
 889                 $gfx->vline( $cur_y );
 890                 $gfx->move($xbase + sum(@{ $calc_column_widths }[0..$num_cols - 1]), $table_top_y);
 891                 $gfx->vline( $cur_y );
 892             }
 893
 894             # ACTUALLY draw all the lines
 895             $gfx->fillcolor( $border_color);
 896             $gfx->stroke;
 897         }
 898         $pg_cnt++;
 899     }# End of while(scalar(@{$data}))
 900
 901     return ($page,--$pg_cnt,$cur_y);
 902 }
 903
 904
 905 # calculate the column widths
 906 sub CalcColumnWidths
 907 {
 908     my $col_props   = shift;
 909     my $avail_width = shift;
 910     my $min_width   = 0;
 911
 912     my $calc_widths ;
 913
 914     for(my $j = 0; $j < scalar( @$col_props); $j++)
 915     {
 916         $min_width += $col_props->[$j]->{min_w} || 0;
 917     }
 918
 919     # I think this is the optimal variant when good view can be guaranateed
 920     if($avail_width < $min_width)
 921     {
 922         carp "!!! Warning !!!\n Calculated Mininal width($min_width) > Table width($avail_width).\n",
 923             ' Expanding table width to:',int($min_width)+1,' but this could lead to unexpected results.',"\n",
 924             ' Possible solutions:',"\n",
 925             '  0)Increase table width.',"\n",
 926             '  1)Decrease font size.',"\n",
 927             '  2)Choose a more narrow font.',"\n",
 928             '  3)Decrease "max_word_length" parameter.',"\n",
 929             '  4)Rotate page to landscape(if it is portrait).',"\n",
 930             '  5)Use larger paper size.',"\n",
 931             '!!! --------- !!!',"\n";
 932         $avail_width = int( $min_width) + 1;
 933
 934     }
 935
 936     # Calculate how much can be added to every column to fit the available width.
 937     for(my $j = 0; $j < scalar(@$col_props); $j++ )
 938     {
 939         $calc_widths->[$j] = $col_props->[$j]->{min_w} || 0;;
 940     }
 941
 942     # Allow columns to expand to max_w before applying extra space equally.
 943     my $is_last_iter;
 944     for (;;)
 945     {
 946         my $span = ($avail_width - $min_width) / scalar( @$col_props);
 947         last if $span <= 0;
 948
 949         $min_width = 0;
 950         my $next_will_be_last_iter = 1;
 951         for(my $j = 0; $j < scalar(@$col_props); $j++ )
 952         {
 953             my $new_w = $calc_widths->[$j] + $span;
 954
 955             if (!$is_last_iter && $new_w > $col_props->[$j]->{max_w})
 956             {
 957                 $new_w = $col_props->[$j]->{max_w}
 958             }
 959             if ($calc_widths->[$j] != $new_w )
 960             {
 961                 $calc_widths->[$j] = $new_w;
 962                 $next_will_be_last_iter = 0;
 963             }
 964             $min_width += $new_w;
 965         }
 966         last if $is_last_iter;
 967         $is_last_iter = $next_will_be_last_iter;
 968     }
 969
 970     return ($calc_widths,$avail_width);
 971 }
 972 1;
 973
 974 __END__
 975
 976 =pod
 977
 978 =head1 NAME
 979
 980 PDF::Table - A utility class for building table layouts in a PDF::API2 object.
 981
 982 =head1 SYNOPSIS
 983
 984  use PDF::API2;
 985  use PDF::Table;
 986
 987  my $pdftable = new PDF::Table;
 988  my $pdf = new PDF::API2(-file => "table_of_lorem.pdf");
 989  my $page = $pdf->page;
 990
 991  # some data to layout
 992  my $some_data =[
 993     ["1 Lorem ipsum dolor",
 994     "Donec odio neque, faucibus vel",
 995     "consequat quis, tincidunt vel, felis."],
 996     ["Nulla euismod sem eget neque.",
 997     "Donec odio neque",
 998     "Sed eu velit."],
 999     #... and so on
1000  ];
1001
1002  $left_edge_of_table = 50;
1003  # build the table layout
1004  $pdftable->table(
1005      # required params
1006      $pdf,
1007      $page,
1008      $some_data,
1009      x => $left_edge_of_table,
1010      w => 495,
1011      start_y => 500,
1012      start_h => 300,
1013      # some optional params
1014      next_y  => 750,
1015      next_h  => 500,
1016      padding => 5,
1017      padding_right => 10,
1018      background_color_odd  => "gray",
1019      background_color_even => "lightblue", #cell background color for even rows
1020   );
1021
1022  # do other stuff with $pdf
1023  $pdf->saveas();
1024 ...
1025
1026 =head1 EXAMPLE
1027
1028 For a complete working example or initial script look into distribution`s 'examples' folder.
1029
1030
1031 =head1 DESCRIPTION
1032
1033 This class is a utility for use with the PDF::API2 module from CPAN.
1034 It can be used to display text data in a table layout within a PDF.
1035 The text data must be in a 2D array (such as returned by a DBI statement handle fetchall_arrayref() call).
1036 The PDF::Table will automatically add as many new pages as necessary to display all of the data.
1037 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.
1038 Also a (non)repeated header row with different layout properties can be specified.
1039
1040 See the L</METHODS> section for complete documentation of every parameter.
1041
1042 =head1 METHODS
1043
1044 =head2 new()
1045
1046     my $pdf_table = new PDF::Table;
1047
1048 =over
1049
1050 =item Description
1051
1052 Creates a new instance of the class. (to be improved)
1053
1054 =item Parameters
1055
1056 There are no parameters.
1057
1058 =item Returns
1059
1060 Reference to the new instance
1061
1062 =back
1063
1064 =head2 table()
1065
1066     my ($final_page, $number_of_pages, $final_y) = table($pdf, $page, $data, %settings)
1067
1068 =over
1069
1070 =item Description
1071
1072 Generates a multi-row, multi-column table into an existing PDF document based on provided data set and settings.
1073
1074 =item Parameters
1075
1076     $pdf      - a PDF::API2 instance representing the document being created
1077     $page     - a PDF::API2::Page instance representing the current page of the document
1078     $data     - an ARRAY reference to a 2D data structure that will be used to build the table
1079     %settings - HASH with geometry and formatting parameters.
1080
1081 For full %settings description see section L</Table settings> below.
1082
1083 This method will add more pages to the pdf instance as required based on the formatting options and the amount of data.
1084
1085 =item Returns
1086
1087 The return value is a 3 items list where
1088
1089     $final_page - The first item is a PDF::API2::Page instance that the table ends on
1090     $number_of_pages - The second item is the count of pages that the table spans on
1091     $final_y - The third item is the Y coordinate of the table bottom so that additional content can be added in the same document.
1092
1093 =item Example
1094
1095     my $pdf  = new PDF::API2;
1096     my $page = $pdf->page();
1097     my $data = [
1098         ['foo1','bar1','baz1'],
1099         ['foo2','bar2','baz2']
1100     ];
1101     my %settings = (
1102         x       => 10,
1103         w       => 570,
1104         start_y => 220,
1105         start_h => 180,
1106     );
1107
1108     my ($final_page, $number_of_pages, $final_y) = $pdftable->table( $pdf, $page, $data, %options );
1109
1110 =back
1111
1112 =head3 Table settings
1113
1114 =head4 Mandatory
1115
1116 There are some mandatory parameteres for setting table geometry and position across page(s)
1117
1118 =over
1119
1120 =item B<x> - X coordinate of upper left corner of the table. Left edge of the sheet is 0.
1121
1122 B<Value:> can be any whole number satisfying 0 =< X < PageWidth
1123 B<Default:> No default value
1124
1125     x => 10
1126
1127 =item B<start_y> - Y coordinate of upper left corner of the table at the initial page.
1128
1129 B<Value:> can be any whole number satisfying 0 < start_y < PageHeight (depending on space availability when embedding a table)
1130 B<Default:> No default value
1131
1132     start_y => 327
1133
1134 =item B<w> - width of the table starting from X.
1135
1136 B<Value:> can be any whole number satisfying 0 < w < PageWidth - x
1137 B<Default:> No default value
1138
1139     w  => 570
1140
1141 =item B<start_h> - Height of the table on the initial page
1142
1143 B<Value:> can be any whole number satisfying 0 < start_h < PageHeight - Current Y position
1144 B<Default:> No default value
1145
1146     start_h => 250
1147
1148 =back
1149
1150 =head4 Optional
1151
1152 =over
1153
1154 =item B<next_h> - Height of the table on any additional page
1155
1156 B<Value:> can be any whole number satisfying 0 < next_h < PageHeight
1157 B<Default:> Value of param B<'start_h'>
1158
1159     next_h  => 700
1160
1161 =item B<next_y> - Y coordinate of upper left corner of the table at any additional page.
1162
1163 B<Value:> can be any whole number satisfying 0 < next_y < PageHeight
1164 B<Default:> Value of param B<'start_y'>
1165
1166     next_y  => 750
1167
1168 =item B<max_word_length> - Breaks long words (like serial numbers hashes etc.) by adding a space after every Nth symbol
1169
1170 B<Value:> can be any whole positive number
1171 B<Default:> 20
1172
1173     max_word_length => 20    # Will add a space after every 20 symbols
1174
1175 =item B<padding> - Padding applied to every cell
1176
1177 =item B<padding_top>    - top cell padding, overrides 'padding'
1178
1179 =item B<padding_right>  - right cell padding, overrides 'padding'
1180
1181 =item B<padding_left>   - left cell padding, overrides 'padding'
1182
1183 =item B<padding_bottom> - bottom padding, overrides 'padding'
1184
1185 B<Value:> can be any whole positive number
1186
1187 B<Default padding:> 0
1188
1189 B<Default padding_*> $padding
1190
1191     padding        => 5      # all sides cell padding
1192     padding_top    => 8,     # top cell padding, overrides 'padding'
1193     padding_right  => 6,     # right cell padding, overrides 'padding'
1194     padding_left   => 2,     # left cell padding, overrides 'padding'
1195     padding_bottom => undef  # bottom padding will be 5 as it will fallback to 'padding'
1196
1197 =item B<border> - Width of table border lines.
1198
1199 =item B<horizontal_borders> - Width of horizontal border lines. Overrides 'border' value.
1200
1201 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1202
1203 B<Value:> can be any whole positive number. When set to 0 will disable border lines.
1204 B<Default:> 1
1205
1206     border             => 3     # border width is 3
1207     horizontal_borders => 1     # horizontal borders will be 1 overriding 3
1208     vertical_borders   => undef # vertical borders will be 3 as it will fallback to 'border'
1209
1210 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1211
1212 B<Value:> Color specifier as 'name' or 'HEX'
1213 B<Default:> 'black'
1214
1215     border_color => 'red'
1216
1217 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the table
1218
1219 B<Value:> can be any PDF::API2::Resource::* type of font
1220 B<Default:> 'Times' with UTF8 encoding
1221
1222     font => $pdf->corefont("Helvetica", -encoding => "utf8")
1223
1224 =item B<font_size> - Default size of the font that will be used across the table
1225
1226 B<Value:> can be any positive number
1227 B<Default:> 12
1228
1229     font_size => 16
1230
1231 =item B<font_color> - Font color for all rows
1232
1233 =item B<font_color_odd> - Font color for odd rows
1234
1235 =item B<font_color_even> - Font color for even rows
1236
1237 =item B<font_underline> - Font underline of the header row
1238
1239 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1240 B<Default:> none
1241
1242 =item B<background_color_odd> - Background color for odd rows
1243
1244 =item B<background_color_even> - Background color for even rows
1245
1246 B<Value:> Color specifier as 'name' or 'HEX'
1247 B<Default:> 'black' font on 'white' background
1248
1249     font_color            => '#333333'
1250     font_color_odd        => 'purple'
1251     font_color_even       => '#00FF00'
1252     background_color_odd  => 'gray'
1253     background_color_even => 'lightblue'
1254
1255 =item B<row_height> - Desired row height but it will be honored only if row_height > font_size + padding_top + padding_bottom
1256
1257 B<Value:> can be any whole positive number
1258 B<Default:> font_size + padding_top + padding_bottom
1259
1260     row_height => 24
1261
1262 =item B<new_page_func> - CODE reference to a function that returns a PDF::API2::Page instance.
1263
1264 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.
1265 For example you can use it to put Page Title, Page Frame, Page Numbers and other staff that you need.
1266 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.
1267 Don't forget that your function must return a page object created with PDF::API2 page() method.
1268
1269     new_page_func  => $code_ref
1270
1271 =item B<header_props> - HASH reference to specific settings for the Header row of the table. See section L</Header Row Properties> below
1272
1273     header_props => $hdr_props
1274
1275 =item B<column_props> - HASH reference to specific settings for each column of the table. See section L</Column Properties> below
1276
1277     column_props => $col_props
1278
1279 =item B<cell_props> - HASH reference to specific settings for each column of the table. See section L</Cell Properties> below
1280
1281     cell_props => $cel_props
1282
1283 =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:
1284
1285     cell_render_hook  => sub {
1286         my ($page, $first_row, $row, $col, $x, $y, $w, $h) = @_;
1287
1288         # Do nothing except for first column (and not a header row)
1289         return unless ($col == 0);
1290         return if ($first_row);
1291
1292         # Create link
1293         my $value = $list_of_vals[$row-1];
1294         my $url = "https://${hostname}/app/${value}";
1295
1296         my $annot = $page->annotation();
1297         $annot->url( $url, -rect => [$x, $y, $x+$w, $y+$h] );
1298     },
1299
1300 =back
1301
1302 =head4 Header Row Properties
1303
1304 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.
1305 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.
1306
1307 =over
1308
1309 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the header row
1310
1311 B<Value:> can be any PDF::API2::Resource::* type of font
1312 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1313
1314 =item B<font_size> - Font size of the header row
1315
1316 B<Value:> can be any positive number
1317 B<Default:> 'font_size' of the table + 2
1318
1319 =item B<font_color> - Font color of the header row
1320
1321 B<Value:> Color specifier as 'name' or 'HEX'
1322 B<Default:> '#000066'
1323
1324 =item B<font_underline> - Font underline of the header row
1325
1326 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1327 B<Default:> none
1328
1329 =item B<bg_color> - Background color of the header row
1330
1331 B<Value:> Color specifier as 'name' or 'HEX'
1332 B<Default:> #FFFFAA
1333
1334 =item B<repeat> - Flag showing if header row should be repeated on every new page
1335
1336 B<Value:> 0,1   1-Yes/True, 0-No/False
1337 B<Default:> 0
1338
1339 =item B<justify> - Alignment of text in the header row.
1340
1341 B<Value:> One of 'left', 'right', 'center'
1342 B<Default:> Same as column alignment (or 'left' if undefined)
1343
1344     my $hdr_props =
1345     {
1346         font       => $pdf->corefont("Helvetica", -encoding => "utf8"),
1347         font_size  => 18,
1348         font_color => '#004444',
1349         bg_color   => 'yellow',
1350         repeat     => 1,
1351         justify    => 'center'
1352     };
1353
1354 =back
1355
1356 =head4 Column Properties
1357
1358 If the 'column_props' parameter is used, it should be an arrayref of hashrefs,
1359 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.
1360 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.
1361
1362 Each hashref can contain any of the keys shown below:
1363
1364 =over
1365
1366 =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.
1367
1368 B<Value:> can be any whole number satisfying 0 < min_w < w
1369 B<Default:> Auto calculated
1370
1371 =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.
1372
1373 B<Value:> can be any whole number satisfying 0 < max_w < w
1374 B<Default:> Auto calculated
1375
1376 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this column
1377
1378 B<Value:> can be any PDF::API2::Resource::* type of font
1379 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1380
1381 =item B<font_size> - Font size of this column
1382
1383 B<Value:> can be any positive number
1384 B<Default:> 'font_size' of the table.
1385
1386 =item B<font_color> - Font color of this column
1387
1388 B<Value:> Color specifier as 'name' or 'HEX'
1389 B<Default:> 'font_color' of the table.
1390
1391 =item B<font_underline> - Font underline of this cell
1392
1393 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1394 B<Default:> none
1395
1396 =item B<background_color> - Background color of this column
1397
1398 B<Value:> Color specifier as 'name' or 'HEX'
1399 B<Default:> undef
1400
1401 =item B<justify> - Alignment of text in this column
1402
1403 B<Value:> One of 'left', 'right', 'center'
1404 B<Default:> 'left'
1405
1406 Example:
1407
1408     my $col_props = [
1409         {},# This is an empty hash so the next one will hold the properties for the second column from left to right.
1410         {
1411             min_w => 100,       # Minimum column width of 100.
1412             max_w => 150,       # Maximum column width of 150 .
1413             justify => 'right', # Right text alignment
1414             font => $pdf->corefont("Helvetica", -encoding => "latin1"),
1415             font_size => 10,
1416             font_color=> 'blue',
1417             background_color => '#FFFF00',
1418         },
1419         # etc.
1420     ];
1421
1422 =back
1423
1424 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.
1425 When this happens a warning will be issued with some advises what can be done.
1426 In cases of a conflict between column formatting and odd/even row formatting, 'col_props' will override odd/even.
1427
1428 =head4 Cell Properties
1429
1430 If the 'cell_props' parameter is used, it should be an arrayref with arrays of hashrefs
1431 (of the same dimension as the data array) with one hashref for each cell of the table.
1432
1433 Each hashref can contain any of the keys shown below:
1434
1435 =over
1436
1437 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this cell
1438
1439 B<Value:> can be any PDF::API2::Resource::* type of font
1440 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1441
1442 =item B<font_size> - Font size of this cell
1443
1444 B<Value:> can be any positive number
1445 B<Default:> 'font_size' of the table.
1446
1447 =item B<font_color> - Font color of this cell
1448
1449 B<Value:> Color specifier as 'name' or 'HEX'
1450 B<Default:> 'font_color' of the table.
1451
1452 =item B<font_underline> - Font underline of this cell
1453
1454 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1455 B<Default:> none
1456
1457 =item B<background_color> - Background color of this cell
1458
1459 B<Value:> Color specifier as 'name' or 'HEX'
1460 B<Default:> undef
1461
1462 =item B<justify> - Alignment of text in this cell
1463
1464 B<Value:> One of 'left', 'right', 'center'
1465 B<Default:> 'left'
1466
1467 Example:
1468
1469     my $cell_props = [
1470         [ #This array is for the first row. If header_props is defined it will overwrite these settings.
1471             {    #Row 1 cell 1
1472                 background_color => '#AAAA00',
1473                 font_color       => 'yellow',
1474                 font_underline   => [ 2, 2 ],
1475             },
1476
1477             # etc.
1478         ],
1479         [#Row 2
1480             {    #Row 2 cell 1
1481                 background_color => '#CCCC00',
1482                 font_color       => 'blue',
1483             },
1484             {    #Row 2 cell 2
1485                 background_color => '#BBBB00',
1486                 font_color       => 'red',
1487             },
1488             # etc.
1489         ],
1490         # etc.
1491     ];
1492
1493     OR
1494
1495     my $cell_props = [];
1496     $cell_props->[1][0] = {
1497         #Row 2 cell 1
1498         background_color => '#CCCC00',
1499         font_color       => 'blue',
1500     };
1501
1502 =back
1503
1504 NOTE: In case of a conflict between column, odd/even and cell formatting, cell formatting will overwrite the other two.
1505 In case of a conflict between header row and cell formatting, header formatting will override cell.
1506
1507 =head2 text_block()
1508
1509     my ($width_of_last_line, $ypos_of_last_line, $left_over_text) = text_block( $txt, $data, %settings)
1510
1511 =over
1512
1513 =item Description
1514
1515 Utility method to create a block of text. The block may contain multiple paragraphs.
1516 It is mainly used internaly but you can use it from outside for placing formatted text anywhere on the sheet.
1517
1518 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.
1519 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.
1520
1521 =item Parameters
1522
1523     $txt  - a PDF::API2::Page::Text instance representing the text tool
1524     $data - a string that will be placed inside the block
1525     %settings - HASH with geometry and formatting parameters.
1526
1527 =item Reuturns
1528
1529 The return value is a 3 items list where
1530
1531     $width_of_last_line - Width of last line in the block
1532     $final_y - The Y coordinate of the block bottom so that additional content can be added after it
1533     $left_over_text - Text that was did not fit in the provided box geometry.
1534
1535 =item Example
1536
1537     # PDF::API2 objects
1538     my $page = $pdf->page;
1539     my $txt  = $page->text;
1540
1541     my %settings = (
1542         x => 10,
1543         y => 570,
1544         w => 220,
1545         h => 180
1546
1547         #OPTIONAL PARAMS
1548         lead     => $font_size | $distance_between_lines,
1549         align    => "left|right|center|justify|fulljustify",
1550         hang     => $optional_hanging_indent,
1551         Only one of the subsequent 3params can be given.
1552         They override each other.-parspace is the weightest
1553         parspace => $optional_vertical_space_before_first_paragraph,
1554         flindent => $optional_indent_of_first_line,
1555         fpindent => $optional_indent_of_first_paragraph,
1556         indent   => $optional_indent_of_text_to_every_non_first_line,
1557     );
1558
1559     my ( $width_of_last_line, $final_y, $left_over_text ) = $pdftable->text_block( $txt, $data, %settings );
1560
1561 =back
1562
1563 =head1 VERSION
1564
1565 0.9.7
1566
1567 =head1 AUTHOR
1568
1569 Daemmon Hughes
1570
1571 =head1 DEVELOPMENT
1572
1573 Further development since Ver: 0.02 - Desislav Kamenov
1574
1575 =head1 COPYRIGHT AND LICENSE
1576
1577 Copyright (C) 2006 by Daemmon Hughes, portions Copyright 2004 Stone
1578 Environmental Inc. (www.stone-env.com) All Rights Reserved.
1579
1580 This library is free software; you can redistribute it and/or modify
1581 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1582 at your option, any later version of Perl 5 you may have available.
1583
1584 =head1 PLUGS
1585
1586 =over
1587
1588 =item by Daemmon Hughes
1589
1590 Much of the work on this module was sponsered by
1591 Stone Environmental Inc. (www.stone-env.com).
1592
1593 The text_block() method is a slightly modified copy of the one from
1594 Rick Measham's PDF::API2 tutorial at
1595 http://pdfapi2.sourceforge.net/cgi-bin/view/Main/YourFirstDocument
1596
1597 =item by Desislav Kamenov (@deskata on Twitter)
1598
1599 The development of this module was supported by SEEBURGER AG (www.seeburger.com) till year 2007
1600
1601 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
1602
1603 Thanks to all GitHub contributors!
1604
1605 =back
1606
1607 =head1 CONTRIBUTION
1608
1609 Hey PDF::Table is on GitHub. You are more than welcome to contribute!
1610
1611 https://github.com/kamenov/PDF-Table
1612
1613 =head1 SEE ALSO
1614
1615 L<PDF::API2>
1616
1617 =cut
1618