view release on metacpan or  search on metacpan

lib/PDF/Table.pod  view on Meta::CPAN

=item B<new_page_func> - CODE reference to a function that returns a 
PDF::Builder::Page instance. See section L<New Page Function Hook> below.

    'new_page_func'  => $code_ref,

=item B<cell_render_hook> - CODE reference to a function called with the 
current cell coordinates. See section L<Cell Render Hook> below.

    'cell_render_hook'  => $code_ref,

=item B<header_props> - HASH reference to specific settings for the Header row 
of the table. See section L</Header Row Properties> below.

    'header_props' => $hdr_props,

=item B<row_props> - HASH reference to specific settings for each row of 
the table. See section L</Row Properties> below.

    'row_props' => $my_row_props,

=item B<column_props> - HASH reference to specific settings for each column of 
the table. See section L</Column Properties> below.

    'column_props' => $col_props,

=item B<cell_props> - HASH reference to specific settings for each column of 
the table. See section L</Cell Properties> below.

    'cell_props' => $cell_props,

=item B<border_w> - Width of table border lines.

=item B<h_border_w> - Width of horizontal border lines (top and bottom of the
table). Overrides 'border_w' value for horizontal usage. Note that if the
table spills over onto following pages, only the very first top and very last 
bottom table border will be full width. Dividers on row boundaries will be
1pt wide ($border_w_default) solid lines, and where a row is divided within 
its content, a dashed (pattern $dashed_rule_default) 1pt wide line is used.

=item B<v_border_w> -  Width of vertical border lines. Overrides 
'border_w' value for vertical usage.

B<Value:> can be any positive number. When set to 0, it will disable 
border lines. This is the line thickness for drawing a border.

B<Default:> C<1>  ($border_w_default)

The I<border> is the B<outside> frame around the table. It does not enter into
table height or width calculations, so be sure to set your C<x> and C<w>
settings to allow for the width of vertical borders, and your C<y> or C<next_y>
and C<h> or C<next_h> settings to allow for the width (thickness or height) of 
the horizontal borders, especially if you make them more than a Point or two 
in thickness (line width).

    'border_w'     => 3,     # border width is 3
    'h_border_w'   => 1,     # horizontal borders will be 1, overriding 3
    'v_border_w'   => undef, # vertical borders will be 3, as it will 
                             # fall back to 'border_w'

Note that both borders and rules overlay the exact boundary between two cells
(i.e., the centerline). That is, one half of a rule or border will overlay the
adjoining cells. Rules do not expand the size of the table, although
borders will (by a total of their thickness/width). If you set particularly
thick (wide) rules, pay attention to adding some padding on the appropriate
side(s), so that valuable content is not overlaid. For cells along the outer
border, one half the width of a border will overlay the cell, so account for
this in the padding specification.

B<Deprecated names:> I<border> (now 'border_w'), 
I<horizontal_borders> (now 'h_border_w'), 
and I<vertical_borders> (now 'v_border_w'); will go away in the future!

=item B<border_c> -  Border color for all borders.

B<Value:> Color specifier as 'name' or '#rrggbb'

B<Default:> C<'black'> ($fg_color_default)

    'border_c' => 'red',

B<Deprecated name:> I<border_color> (will go away in the future!)

The same color is used for both the horizontal and vertical borders.

=back

=head4 Optional Cell, Column, Row, or Global Settings

These settings can be specified to apply to the entire table, or more
narrowly applied to the header row (in header_props hash), one or more rows
(in row_props array), one or more columns (in column_props array), or one
or more individual cells (in cell_props hash).

If a setting is specified in more than one place, the order of precedence is
as follows: a header property (header row only), followed by a cell property, 
followed by a column property, followed by a row property, followed by a 
global setting, and finally, any hard-coded default value (if required).

A global setting may only occur once (although it may be overridden by cell,
column, or row usage of the same setting).

=over

=item B<default_text> - A string to use if no content (text) is defined for
a cell.

It is also used if a cell has exhausted its given text content, and has been
split over a page break. This can happen if other cells in the row have much
more text content than this cell. Therefore, it might be a good idea to I<not>
use a default such as "no cell content", as this could be confusing to readers
who have seen content for this cell on the previous page.

Note that C<max_word_length> splitting is I<not> applied to the default text,
so be careful about using long words.

If you want different effects for different rows, columns, or cells, you can
override the global default setting. If you want B<(No content)> for the first
printout of a cell (split over two or more pages) and B<-> for second and later
printouts, you could leave the global default as '-' and simply give the cell
the text "(No content)" (no longer really I<empty>, but you get the idea). If
you have some content for a cell, and want B<no further entry> after it runs
out of content, you could set C<default_text> to B<no further entry>, and so on.

B<Value:> any string (can be a blank ' ' or an empty string '').

B<Default:> '-'  ($empty_cell_text)

lib/PDF/Table.pod  view on Meta::CPAN

=item B<justify> - Alignment of text in a cell.

B<Value:> One of 'left', 'right', 'center'

B<Default:> C<'left'>

=item B<min_w> - Minimum width of this cell or column. 

PDF::Table will set a cell (and the column it's in) minimum width to fit the
longest word (after splitting on C<max_word_length>) found in the text. This
amount may be increased to C<min_w>. A column should be no narrower than its
widest minimum width, but could be larger in order to fill out the table width.

B<Value:> can be any number satisfying C<0 < min_w < w>

B<Default:> Auto calculated

Note that C<min_w> is usually used for a column_props to set the column
minimum width. If used in a row_props, it will act as a I<global> setting; if
used in a cell_props, that will force the minimum width for the cell's column.

=item B<max_w> - Maximum width of this column. 

PDF::Table will set a cell (and the column it's in) maximum width to fit the
total length of the text content. This will seldom be actually used, but 
C<max_w> may be used to I<reduce> this maximum. When columns are being widened
in order to meet the desired table width, it will try to honor the maximum
width setting and avoid adding any width to a column already at its maximum
width (but this cannot be guaranteed).

B<Value:> can be any number satisfying C<0 < min_w E<le> max_w < w>

B<Default:> Auto calculated

=item B<rule_w> - Width of table rule lines (internal table dividers).

=item B<h_rule_w> - Width of horizontal rules (bottom of a cell).
Overrides 'rule_w' value for horizontal usage.

=item B<v_rule_w> -  Width of vertical rules (left side of a cell). 
Overrides 'rule_w' value for vertical usage.

B<Value:> can be any positive number. When set to 0, it will disable 
rules. This is the line thickness for drawing a rule.

B<Default:> C<1>  (corresponding border value)

A I<rule> is a line bordering a I<cell> in the table. While it does not enter 
into table height or width calculations, be sure to set your C<padding> 
settings to allow sufficient clearance of cell content, especially if you make 
the rules more than a Point or two in thickness (line width). Note that a
cell only defines and draws its left and bottom rules -- the top rule is 
defined in the cell or row above, and the right rule is defined in the cell
or column to the right of this one.

    'rule_w'     => 3,     # rule width is 3
    'h_rule_w'   => 1,     # horizontal rules will be 1, overriding 3
    'v_rule_w'   => undef, # vertical rules will be 3, as it will 
                           # fall back to 'rule_w'

Note that both borders and rules overlay the exact boundary between two cells
(i.e., the centerline). That is, one half of a rule or border will overlay the
adjoining cells. Rules do not expand the size of the table. If you set 
particularly thick (wide) rules, pay attention to adding some padding on the 
appropriate side(s), so that valuable content is not overlaid. For cells along 
the outer border, a I<border> will be drawn instead of a I<rule>.

Cell rules inherit thickness and color from the border settings, so if you want
no internal rules, you need to set 

    'rule_w'     => 0,     # no rules
    
=item B<rule_c> -  Rule color for all rules.

=item B<h_rule_c> -  Rule color for horizontal (bottom) rules, overriding C<rule_c> for this usage.

=item B<v_rule_c> -  Rule color for vertical (left) rules, overriding C<rule_c> for this usage.

B<Value:> Color specifier as 'name' or '#rrggbb'

B<Default:> C<'black'> (corresponding border value)

    'rule_c' => 'red',

=back

=head4 New Page Function Hook

B<new_page_func> is a CODE reference to a function that returns a 
PDF::Builder::Page instance.

If used, the parameter 'C<new_page_func>' must be a function reference which, 
when executed, will create a new page and will return the object to the module.
For example, you can use it to put Page Title, Page Frame, Page Numbers and 
other content that you need.
Also if you need a different paper size and orientation than the default 
US-Letter, e.g., B2-Landscape, you can use this function ref to set it up for 
you. For more info about creating pages, refer to PDF::Builder PAGE METHODS 
Section.
Don't forget that your function must return a page object created with the
PDF::Builder page() method. C<$code_ref> can be something like C<\&new_page>.

    'new_page_func'  => $code_ref,

The C<$code_ref> may be an inline sub definition (as show below), or a regular
named C<sub> (e.g., 'new_page()') referenced as C<\&new_page>. The latter may 
be cleaner than inlining, if the routine is quite long.

An example of reusing a saved PDF page as a I<template>:

    my $pdf      = PDF::API2->new();
    my $template = PDF::API2->open('pdf/template.pdf');
    my $new_page_func = sub { return $pdf->import_page($template, 1); }

    table(
        ...
        new_page_func => $new_page_func,
        ...

This will call a function to grab a copy of a template PDF's page 1 and
insert it as the new last page of the PDF, as the starting point for the next
I<overflow> (continuation) page of the table, if needed. Note that the