NAME

PDF::Cairo::Box - rectangle-manipulation library

SYNOPSIS

PDF::Cairo::Box is designed to simplify PDF layout for forms, graph paper, calendars, practice sheets, etc.

    use PDF::Cairo::Box;

    my $page = PDF::Cairo::Box->new(paper => "a4");
    my $half = $page->fold;
    $half->shrink(all => 36)->rotate;
    $page->center($half);
    ...

DESCRIPTION

Creating new boxes

new %options

width => $width,

height => $height,

paper => $paper_size,

wide|landscape => 1,

tall|portrait => 1

x => $LLx,

y => $LLy,

All arguments are optional. If called with no arguments, creates a zero-size box with lower-left corner at (x,y)==(0,0). If called with the name of a known paper size (see PDF::Cairo::Papers) and optional orientation, sets width and height to the size of that paper in points.

bounds $box, ...

Return a new box that contains all the boxes passed as arguments.

Setting/getting box parameters

bbox [$x,$y, $width,$height]

Return the boundaries of the current box (convenient for passing to rect()). If four arguments are passed, set it to those values instead.

height [$height]

Return the height of the current box. If an argument is passed, set the height to that value instead.

iswide

Returns true if the current box is wider than it is tall.

size [$width, $height]

Return the (width, height) of the current box. If two arguments are passed, set them to those values.

width [$width]

Return the width of the current box. If an argument is passed, set the width to that value instead.

x [$x]

Return the X coordinate of the current box's lower-left corner. If an argument is passed, move the box to that location instead.

y [$y]

Return the Y coordinate of the current box's lower-left corner. If an argument is passed, move the box to that location instead.

xy [$x, $y]

Return the (X,Y) coordinates of the current box's lower-left corner. If two arguments are passed, move the box to that location instead.

cx [$center_x]

Return the X coordinate of the current box's center. If an argument is passed, move the box to that location instead.

cy [$center_y]

Return the Y coordinate of the current box's center. If an argument is passed, move the box to that location instead.

cxy [$center_x, $center_y]

Return the (X,Y) coordinates of the current box's center. If two arguments are passed, move the box to that location instead.

Creating boxes from existing boxes

copy

Return a new copy of the current box.

fold $folds

ISO-style paper folding, without rounding. Returns a new box created by halving the long dimension of the current box $folds times (default 1), maintaining the current orientation. That is, folding portrait-format A4 once creates portrait-format A5, and folding it twice creates portrait-format A6.

grid %options

rows => $n,

columns => $n,

width => $size|'$size%',

height => $size|'$size%',

xpack => 'left|center|right',

ypack => 'top|center|bottom',

center => 1,

Create a grid of new boxes by splitting the current box according to the passed arguments, either by absolute size or percentage. Returns an array of rows from top to bottom, with each row pointing to an array of cells, left to right. This is equivalent to calling slice by columns on the result of slice by rows.

By default, leftover space is evenly distributed between the boxes and the parent box. The xpack/ypack arguments aligns all of the boxes at the position requested, with no space between them. The center argument is equivalent to setting both xpack and ypack to center.

slice %options

rows => $n,

columns => $n,

width => $size|'$size%',

height => $size|'$size%',

xpack => 'left'|'center'|'right',

ypack => 'top'|'center'|'bottom',

center => 1,

Returns an array of new boxes created by dividing the current box according to the single argument provided. Width/height can be an absolute size or percentage, while row/column must be an integer greater than 1. Rows are returned left-to-right, columns top-to-bottom.

By default, leftover space is evenly distributed between the boxes and the parent box. The xpack/ypack arguments aligns all of the boxes at the position requested, with no space between them. The center argument is equivalent to setting both xpack and ypack to center.

split %options

width => $size|'$size%',

height => $size|'$size%',

Returns two new boxes created by splitting the current box at the supplied width or height, either by absolute size or percentage.

unfold $folds

Reverses an ISO-style paper fold. Returns a new box created by doubling the length of the short side of the current box $folds times, maintaining the current orientation.

Note that due to rounding, the official B5 is slightly larger than an unfolded B6.

Moving boxes

align [$box, ...], %options

top => 1,

center_v => 1,

bottom => 1,

left => 1,

center_h => 1,

right => 1,

center => 1,

Align one or more boxes to the current box. For convenience, if only one box is passed in the first argument, it doesn't need to be wrapped in an array reference.

center $box, ...

Center one or more boxes to the current box.

TODO distribute

distribute({by_row, by_col, pack}, $box, ...)

move $x, $y

move $box

Move a box to an absolute location, or to the same (x,y) position as another box.

rel_move $delta_x, $delta_y

Move a box relative to its current location.

Resizing boxes

expand %options

top => $size|'$size%',

bottom => $size|'$size%',

left => $size|'$size%',

right => $size|'$size%',

all => $size|'$size%',

Increases the size of the current box, maintaining its relative position.

rotate

Swaps width/height of a box. Does not change its (x,y) position.

scale $scale

Scale the location and size of the current box (1 = no change).

shrink %options

top => $size|'$size%',

bottom => $size|'$size%',

left => $size|'$size%',

right => $size|'$size%',

all => $size|'$size%',

Reduces the size of the current box, maintaining its relative position.

BUGS

Gosh, none I hope.

AUTHOR

J Greely, <jgreely at cpan.org>