modules/override/PDF/Table.pm

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