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