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