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 - $header_props->{num_header_rows}) % 2 ? $background_color_even  : $background_color_odd;
 677             $font_color       = ($row_index - $header_props->{num_header_rows}) % 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 + $header_props->{num_header_rows}][$column_idx]->{colspan}) {
 750                     $colspan = $cell_props->[$row_index + $header_props->{num_header_rows}][$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 + $header_props->{num_header_rows}][$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 - $current_row_height);
 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     my $span = 0;
 943     # Calculate how much can be added to every column to fit the available width
 944     $span = ($avail_width - $min_width) / scalar( @$col_props);
 945     for (my $j = 0; $j < scalar(@$col_props); $j++ ) {
 946       $calc_widths->[$j] = $col_props->[$j]->{min_w} + $span;
 947     }
 948
 949     return ($calc_widths,$avail_width);
 950 }
 951 1;
 952
 953 __END__
 954
 955 =pod
 956
 957 =head1 NAME
 958
 959 PDF::Table - A utility class for building table layouts in a PDF::API2 object.
 960
 961 =head1 SYNOPSIS
 962
 963  use PDF::API2;
 964  use PDF::Table;
 965
 966  my $pdftable = new PDF::Table;
 967  my $pdf = new PDF::API2(-file => "table_of_lorem.pdf");
 968  my $page = $pdf->page;
 969
 970  # some data to layout
 971  my $some_data =[
 972     ["1 Lorem ipsum dolor",
 973     "Donec odio neque, faucibus vel",
 974     "consequat quis, tincidunt vel, felis."],
 975     ["Nulla euismod sem eget neque.",
 976     "Donec odio neque",
 977     "Sed eu velit."],
 978     #... and so on
 979  ];
 980
 981  $left_edge_of_table = 50;
 982  # build the table layout
 983  $pdftable->table(
 984      # required params
 985      $pdf,
 986      $page,
 987      $some_data,
 988      x => $left_edge_of_table,
 989      w => 495,
 990      start_y => 500,
 991      start_h => 300,
 992      # some optional params
 993      next_y  => 750,
 994      next_h  => 500,
 995      padding => 5,
 996      padding_right => 10,
 997      background_color_odd  => "gray",
 998      background_color_even => "lightblue", #cell background color for even rows
 999   );
1000
1001  # do other stuff with $pdf
1002  $pdf->saveas();
1003 ...
1004
1005 =head1 EXAMPLE
1006
1007 For a complete working example or initial script look into distribution`s 'examples' folder.
1008
1009
1010 =head1 DESCRIPTION
1011
1012 This class is a utility for use with the PDF::API2 module from CPAN.
1013 It can be used to display text data in a table layout within a PDF.
1014 The text data must be in a 2D array (such as returned by a DBI statement handle fetchall_arrayref() call).
1015 The PDF::Table will automatically add as many new pages as necessary to display all of the data.
1016 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.
1017 Also a (non)repeated header row with different layout properties can be specified.
1018
1019 See the L</METHODS> section for complete documentation of every parameter.
1020
1021 =head1 METHODS
1022
1023 =head2 new()
1024
1025     my $pdf_table = new PDF::Table;
1026
1027 =over
1028
1029 =item Description
1030
1031 Creates a new instance of the class. (to be improved)
1032
1033 =item Parameters
1034
1035 There are no parameters.
1036
1037 =item Returns
1038
1039 Reference to the new instance
1040
1041 =back
1042
1043 =head2 table()
1044
1045     my ($final_page, $number_of_pages, $final_y) = table($pdf, $page, $data, %settings)
1046
1047 =over
1048
1049 =item Description
1050
1051 Generates a multi-row, multi-column table into an existing PDF document based on provided data set and settings.
1052
1053 =item Parameters
1054
1055     $pdf      - a PDF::API2 instance representing the document being created
1056     $page     - a PDF::API2::Page instance representing the current page of the document
1057     $data     - an ARRAY reference to a 2D data structure that will be used to build the table
1058     %settings - HASH with geometry and formatting parameters.
1059
1060 For full %settings description see section L</Table settings> below.
1061
1062 This method will add more pages to the pdf instance as required based on the formatting options and the amount of data.
1063
1064 =item Returns
1065
1066 The return value is a 3 items list where
1067
1068     $final_page - The first item is a PDF::API2::Page instance that the table ends on
1069     $number_of_pages - The second item is the count of pages that the table spans on
1070     $final_y - The third item is the Y coordinate of the table bottom so that additional content can be added in the same document.
1071
1072 =item Example
1073
1074     my $pdf  = new PDF::API2;
1075     my $page = $pdf->page();
1076     my $data = [
1077         ['foo1','bar1','baz1'],
1078         ['foo2','bar2','baz2']
1079     ];
1080     my %settings = (
1081         x       => 10,
1082         w       => 570,
1083         start_y => 220,
1084         start_h => 180,
1085     );
1086
1087     my ($final_page, $number_of_pages, $final_y) = $pdftable->table( $pdf, $page, $data, %options );
1088
1089 =back
1090
1091 =head3 Table settings
1092
1093 =head4 Mandatory
1094
1095 There are some mandatory parameteres for setting table geometry and position across page(s)
1096
1097 =over
1098
1099 =item B<x> - X coordinate of upper left corner of the table. Left edge of the sheet is 0.
1100
1101 B<Value:> can be any whole number satisfying 0 =< X < PageWidth
1102 B<Default:> No default value
1103
1104     x => 10
1105
1106 =item B<start_y> - Y coordinate of upper left corner of the table at the initial page.
1107
1108 B<Value:> can be any whole number satisfying 0 < start_y < PageHeight (depending on space availability when embedding a table)
1109 B<Default:> No default value
1110
1111     start_y => 327
1112
1113 =item B<w> - width of the table starting from X.
1114
1115 B<Value:> can be any whole number satisfying 0 < w < PageWidth - x
1116 B<Default:> No default value
1117
1118     w  => 570
1119
1120 =item B<start_h> - Height of the table on the initial page
1121
1122 B<Value:> can be any whole number satisfying 0 < start_h < PageHeight - Current Y position
1123 B<Default:> No default value
1124
1125     start_h => 250
1126
1127 =back
1128
1129 =head4 Optional
1130
1131 =over
1132
1133 =item B<next_h> - Height of the table on any additional page
1134
1135 B<Value:> can be any whole number satisfying 0 < next_h < PageHeight
1136 B<Default:> Value of param B<'start_h'>
1137
1138     next_h  => 700
1139
1140 =item B<next_y> - Y coordinate of upper left corner of the table at any additional page.
1141
1142 B<Value:> can be any whole number satisfying 0 < next_y < PageHeight
1143 B<Default:> Value of param B<'start_y'>
1144
1145     next_y  => 750
1146
1147 =item B<max_word_length> - Breaks long words (like serial numbers hashes etc.) by adding a space after every Nth symbol
1148
1149 B<Value:> can be any whole positive number
1150 B<Default:> 20
1151
1152     max_word_length => 20    # Will add a space after every 20 symbols
1153
1154 =item B<padding> - Padding applied to every cell
1155
1156 =item B<padding_top>    - top cell padding, overrides 'padding'
1157
1158 =item B<padding_right>  - right cell padding, overrides 'padding'
1159
1160 =item B<padding_left>   - left cell padding, overrides 'padding'
1161
1162 =item B<padding_bottom> - bottom padding, overrides 'padding'
1163
1164 B<Value:> can be any whole positive number
1165
1166 B<Default padding:> 0
1167
1168 B<Default padding_*> $padding
1169
1170     padding        => 5      # all sides cell padding
1171     padding_top    => 8,     # top cell padding, overrides 'padding'
1172     padding_right  => 6,     # right cell padding, overrides 'padding'
1173     padding_left   => 2,     # left cell padding, overrides 'padding'
1174     padding_bottom => undef  # bottom padding will be 5 as it will fallback to 'padding'
1175
1176 =item B<border> - Width of table border lines.
1177
1178 =item B<horizontal_borders> - Width of horizontal border lines. Overrides 'border' value.
1179
1180 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1181
1182 B<Value:> can be any whole positive number. When set to 0 will disable border lines.
1183 B<Default:> 1
1184
1185     border             => 3     # border width is 3
1186     horizontal_borders => 1     # horizontal borders will be 1 overriding 3
1187     vertical_borders   => undef # vertical borders will be 3 as it will fallback to 'border'
1188
1189 =item B<vertical_borders> -  Width of vertical border lines. Overrides 'border' value.
1190
1191 B<Value:> Color specifier as 'name' or 'HEX'
1192 B<Default:> 'black'
1193
1194     border_color => 'red'
1195
1196 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the table
1197
1198 B<Value:> can be any PDF::API2::Resource::* type of font
1199 B<Default:> 'Times' with UTF8 encoding
1200
1201     font => $pdf->corefont("Helvetica", -encoding => "utf8")
1202
1203 =item B<font_size> - Default size of the font that will be used across the table
1204
1205 B<Value:> can be any positive number
1206 B<Default:> 12
1207
1208     font_size => 16
1209
1210 =item B<font_color> - Font color for all rows
1211
1212 =item B<font_color_odd> - Font color for odd rows
1213
1214 =item B<font_color_even> - Font color for even rows
1215
1216 =item B<font_underline> - Font underline of the header row
1217
1218 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1219 B<Default:> none
1220
1221 =item B<background_color_odd> - Background color for odd rows
1222
1223 =item B<background_color_even> - Background color for even rows
1224
1225 B<Value:> Color specifier as 'name' or 'HEX'
1226 B<Default:> 'black' font on 'white' background
1227
1228     font_color            => '#333333'
1229     font_color_odd        => 'purple'
1230     font_color_even       => '#00FF00'
1231     background_color_odd  => 'gray'
1232     background_color_even => 'lightblue'
1233
1234 =item B<row_height> - Desired row height but it will be honored only if row_height > font_size + padding_top + padding_bottom
1235
1236 B<Value:> can be any whole positive number
1237 B<Default:> font_size + padding_top + padding_bottom
1238
1239     row_height => 24
1240
1241 =item B<new_page_func> - CODE reference to a function that returns a PDF::API2::Page instance.
1242
1243 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.
1244 For example you can use it to put Page Title, Page Frame, Page Numbers and other staff that you need.
1245 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.
1246 Don't forget that your function must return a page object created with PDF::API2 page() method.
1247
1248     new_page_func  => $code_ref
1249
1250 =item B<header_props> - HASH reference to specific settings for the Header row of the table. See section L</Header Row Properties> below
1251
1252     header_props => $hdr_props
1253
1254 =item B<column_props> - HASH reference to specific settings for each column of the table. See section L</Column Properties> below
1255
1256     column_props => $col_props
1257
1258 =item B<cell_props> - HASH reference to specific settings for each column of the table. See section L</Cell Properties> below
1259
1260     cell_props => $cel_props
1261
1262 =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:
1263
1264     cell_render_hook  => sub {
1265         my ($page, $first_row, $row, $col, $x, $y, $w, $h) = @_;
1266
1267         # Do nothing except for first column (and not a header row)
1268         return unless ($col == 0);
1269         return if ($first_row);
1270
1271         # Create link
1272         my $value = $list_of_vals[$row-1];
1273         my $url = "https://${hostname}/app/${value}";
1274
1275         my $annot = $page->annotation();
1276         $annot->url( $url, -rect => [$x, $y, $x+$w, $y+$h] );
1277     },
1278
1279 =back
1280
1281 =head4 Header Row Properties
1282
1283 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.
1284 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.
1285
1286 =over
1287
1288 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in the header row
1289
1290 B<Value:> can be any PDF::API2::Resource::* type of font
1291 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1292
1293 =item B<font_size> - Font size of the header row
1294
1295 B<Value:> can be any positive number
1296 B<Default:> 'font_size' of the table + 2
1297
1298 =item B<font_color> - Font color of the header row
1299
1300 B<Value:> Color specifier as 'name' or 'HEX'
1301 B<Default:> '#000066'
1302
1303 =item B<font_underline> - Font underline of the header row
1304
1305 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1306 B<Default:> none
1307
1308 =item B<bg_color> - Background color of the header row
1309
1310 B<Value:> Color specifier as 'name' or 'HEX'
1311 B<Default:> #FFFFAA
1312
1313 =item B<repeat> - Flag showing if header row should be repeated on every new page
1314
1315 B<Value:> 0,1   1-Yes/True, 0-No/False
1316 B<Default:> 0
1317
1318 =item B<justify> - Alignment of text in the header row.
1319
1320 B<Value:> One of 'left', 'right', 'center'
1321 B<Default:> Same as column alignment (or 'left' if undefined)
1322
1323     my $hdr_props =
1324     {
1325         font       => $pdf->corefont("Helvetica", -encoding => "utf8"),
1326         font_size  => 18,
1327         font_color => '#004444',
1328         bg_color   => 'yellow',
1329         repeat     => 1,
1330         justify    => 'center'
1331     };
1332
1333 =back
1334
1335 =head4 Column Properties
1336
1337 If the 'column_props' parameter is used, it should be an arrayref of hashrefs,
1338 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.
1339 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.
1340
1341 Each hashref can contain any of the keys shown below:
1342
1343 =over
1344
1345 =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.
1346
1347 B<Value:> can be any whole number satisfying 0 < min_w < w
1348 B<Default:> Auto calculated
1349
1350 =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.
1351
1352 B<Value:> can be any whole number satisfying 0 < max_w < w
1353 B<Default:> Auto calculated
1354
1355 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this column
1356
1357 B<Value:> can be any PDF::API2::Resource::* type of font
1358 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1359
1360 =item B<font_size> - Font size of this column
1361
1362 B<Value:> can be any positive number
1363 B<Default:> 'font_size' of the table.
1364
1365 =item B<font_color> - Font color of this column
1366
1367 B<Value:> Color specifier as 'name' or 'HEX'
1368 B<Default:> 'font_color' of the table.
1369
1370 =item B<font_underline> - Font underline of this cell
1371
1372 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1373 B<Default:> none
1374
1375 =item B<background_color> - Background color of this column
1376
1377 B<Value:> Color specifier as 'name' or 'HEX'
1378 B<Default:> undef
1379
1380 =item B<justify> - Alignment of text in this column
1381
1382 B<Value:> One of 'left', 'right', 'center'
1383 B<Default:> 'left'
1384
1385 Example:
1386
1387     my $col_props = [
1388         {},# This is an empty hash so the next one will hold the properties for the second column from left to right.
1389         {
1390             min_w => 100,       # Minimum column width of 100.
1391             max_w => 150,       # Maximum column width of 150 .
1392             justify => 'right', # Right text alignment
1393             font => $pdf->corefont("Helvetica", -encoding => "latin1"),
1394             font_size => 10,
1395             font_color=> 'blue',
1396             background_color => '#FFFF00',
1397         },
1398         # etc.
1399     ];
1400
1401 =back
1402
1403 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.
1404 When this happens a warning will be issued with some advises what can be done.
1405 In cases of a conflict between column formatting and odd/even row formatting, 'col_props' will override odd/even.
1406
1407 =head4 Cell Properties
1408
1409 If the 'cell_props' parameter is used, it should be an arrayref with arrays of hashrefs
1410 (of the same dimension as the data array) with one hashref for each cell of the table.
1411
1412 Each hashref can contain any of the keys shown below:
1413
1414 =over
1415
1416 =item B<font> - instance of PDF::API2::Resource::Font defining the fontf to be used in this cell
1417
1418 B<Value:> can be any PDF::API2::Resource::* type of font
1419 B<Default:> 'font' of the table. See table parameter 'font' for more details.
1420
1421 =item B<font_size> - Font size of this cell
1422
1423 B<Value:> can be any positive number
1424 B<Default:> 'font_size' of the table.
1425
1426 =item B<font_color> - Font color of this cell
1427
1428 B<Value:> Color specifier as 'name' or 'HEX'
1429 B<Default:> 'font_color' of the table.
1430
1431 =item B<font_underline> - Font underline of this cell
1432
1433 B<Value:> 'auto', integer of distance, or arrayref of distance & thickness (more than one pair will provide mlultiple underlines. Negative distance gives strike-through.
1434 B<Default:> none
1435
1436 =item B<background_color> - Background color of this cell
1437
1438 B<Value:> Color specifier as 'name' or 'HEX'
1439 B<Default:> undef
1440
1441 =item B<justify> - Alignment of text in this cell
1442
1443 B<Value:> One of 'left', 'right', 'center'
1444 B<Default:> 'left'
1445
1446 Example:
1447
1448     my $cell_props = [
1449         [ #This array is for the first row. If header_props is defined it will overwrite these settings.
1450             {    #Row 1 cell 1
1451                 background_color => '#AAAA00',
1452                 font_color       => 'yellow',
1453                 font_underline   => [ 2, 2 ],
1454             },
1455
1456             # etc.
1457         ],
1458         [#Row 2
1459             {    #Row 2 cell 1
1460                 background_color => '#CCCC00',
1461                 font_color       => 'blue',
1462             },
1463             {    #Row 2 cell 2
1464                 background_color => '#BBBB00',
1465                 font_color       => 'red',
1466             },
1467             # etc.
1468         ],
1469         # etc.
1470     ];
1471
1472     OR
1473
1474     my $cell_props = [];
1475     $cell_props->[1][0] = {
1476         #Row 2 cell 1
1477         background_color => '#CCCC00',
1478         font_color       => 'blue',
1479     };
1480
1481 =back
1482
1483 NOTE: In case of a conflict between column, odd/even and cell formatting, cell formatting will overwrite the other two.
1484 In case of a conflict between header row and cell formatting, header formatting will override cell.
1485
1486 =head2 text_block()
1487
1488     my ($width_of_last_line, $ypos_of_last_line, $left_over_text) = text_block( $txt, $data, %settings)
1489
1490 =over
1491
1492 =item Description
1493
1494 Utility method to create a block of text. The block may contain multiple paragraphs.
1495 It is mainly used internaly but you can use it from outside for placing formatted text anywhere on the sheet.
1496
1497 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.
1498 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.
1499
1500 =item Parameters
1501
1502     $txt  - a PDF::API2::Page::Text instance representing the text tool
1503     $data - a string that will be placed inside the block
1504     %settings - HASH with geometry and formatting parameters.
1505
1506 =item Reuturns
1507
1508 The return value is a 3 items list where
1509
1510     $width_of_last_line - Width of last line in the block
1511     $final_y - The Y coordinate of the block bottom so that additional content can be added after it
1512     $left_over_text - Text that was did not fit in the provided box geometry.
1513
1514 =item Example
1515
1516     # PDF::API2 objects
1517     my $page = $pdf->page;
1518     my $txt  = $page->text;
1519
1520     my %settings = (
1521         x => 10,
1522         y => 570,
1523         w => 220,
1524         h => 180
1525
1526         #OPTIONAL PARAMS
1527         lead     => $font_size | $distance_between_lines,
1528         align    => "left|right|center|justify|fulljustify",
1529         hang     => $optional_hanging_indent,
1530         Only one of the subsequent 3params can be given.
1531         They override each other.-parspace is the weightest
1532         parspace => $optional_vertical_space_before_first_paragraph,
1533         flindent => $optional_indent_of_first_line,
1534         fpindent => $optional_indent_of_first_paragraph,
1535         indent   => $optional_indent_of_text_to_every_non_first_line,
1536     );
1537
1538     my ( $width_of_last_line, $final_y, $left_over_text ) = $pdftable->text_block( $txt, $data, %settings );
1539
1540 =back
1541
1542 =head1 VERSION
1543
1544 0.9.7
1545
1546 =head1 AUTHOR
1547
1548 Daemmon Hughes
1549
1550 =head1 DEVELOPMENT
1551
1552 Further development since Ver: 0.02 - Desislav Kamenov
1553
1554 =head1 COPYRIGHT AND LICENSE
1555
1556 Copyright (C) 2006 by Daemmon Hughes, portions Copyright 2004 Stone
1557 Environmental Inc. (www.stone-env.com) All Rights Reserved.
1558
1559 This library is free software; you can redistribute it and/or modify
1560 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1561 at your option, any later version of Perl 5 you may have available.
1562
1563 =head1 PLUGS
1564
1565 =over
1566
1567 =item by Daemmon Hughes
1568
1569 Much of the work on this module was sponsered by
1570 Stone Environmental Inc. (www.stone-env.com).
1571
1572 The text_block() method is a slightly modified copy of the one from
1573 Rick Measham's PDF::API2 tutorial at
1574 http://pdfapi2.sourceforge.net/cgi-bin/view/Main/YourFirstDocument
1575
1576 =item by Desislav Kamenov (@deskata on Twitter)
1577
1578 The development of this module was supported by SEEBURGER AG (www.seeburger.com) till year 2007
1579
1580 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
1581
1582 Thanks to all GitHub contributors!
1583
1584 =back
1585
1586 =head1 CONTRIBUTION
1587
1588 Hey PDF::Table is on GitHub. You are more than welcome to contribute!
1589
1590 https://github.com/kamenov/PDF-Table
1591
1592 =head1 SEE ALSO
1593
1594 L<PDF::API2>
1595
1596 =cut
1597