diff options
Diffstat (limited to 'lib/PDF/Builder/Lite.pm')
| -rw-r--r-- | lib/PDF/Builder/Lite.pm | 362 |
1 files changed, 297 insertions, 65 deletions
diff --git a/lib/PDF/Builder/Lite.pm b/lib/PDF/Builder/Lite.pm index 76ce2fe..379649e 100644 --- a/lib/PDF/Builder/Lite.pm +++ b/lib/PDF/Builder/Lite.pm @@ -3,8 +3,8 @@ package PDF::Builder::Lite; use strict; use warnings; -our $VERSION = '3.025'; # VERSION -our $LAST_UPDATE = '3.024'; # manually update whenever code is changed +our $VERSION = '3.026'; # VERSION +our $LAST_UPDATE = '3.026'; # manually update whenever code is changed # NOTE that this sub-package has not been tested and is not well documented! # It is possible that it will be deprecated and removed. @@ -45,11 +45,11 @@ It remains solely for compatibility with existing legacy code. =head1 METHODS -=over +=head2 new -=item $pdf = PDF::Builder::Lite->new(%opts) + $pdf = PDF::Builder::Lite->new(%opts) -=item $pdf = PDF::Builder::Lite->new() + $pdf = PDF::Builder::Lite->new() =cut @@ -63,14 +63,20 @@ sub new { return $self; } -=item $pdf->page() +=head2 page + + $pdf->page() -=item $pdf->page($width,$height) + $pdf->page($width,$height) -=item $pdf->page($llx,$lly, $urx,$ury) + $pdf->page($llx,$lly, $urx,$ury) + +=over Opens a new page. +=back + =cut sub page { @@ -82,12 +88,18 @@ sub page { return $self; } -=item $pdf->mediabox($w,$h) +=head2 mediabox + + $pdf->mediabox($w,$h) -=item $pdf->mediabox($llx,$lly, $urx,$ury) + $pdf->mediabox($llx,$lly, $urx,$ury) + +=over Sets the global mediabox. +=back + =cut sub mediabox { @@ -100,7 +112,11 @@ sub mediabox { return $self; } -=item $pdf->saveas($file) +=head2 saveas + + $pdf->saveas($file) + +=over Saves the document (may B<not> be modified later) and deallocates the PDF structures. @@ -108,6 +124,8 @@ deallocates the PDF structures. If C<$file> is just a hyphen '-', the stringified copy is returned, otherwise the file is saved, and C<$self> is returned (for chaining calls). +=back + =cut sub saveas { @@ -133,8 +151,11 @@ sub saveas { return; } +=head2 corefont -=item $font = $pdf->corefont($fontname) + $font = $pdf->corefont($fontname) + +=over Returns a new or existing Adobe core font object. @@ -145,6 +166,8 @@ B<Examples:> $font = $pdf->corefont('Helvetica'); $font = $pdf->corefont('ZapfDingbats'); +=back + =cut sub corefont { @@ -154,7 +177,11 @@ sub corefont { return $obj; } -=item $font = $pdf->ttfont($ttfile) +=head2 ttfont + + $font = $pdf->ttfont($ttfile) + +=over Returns a new or existing TrueType font object. @@ -164,6 +191,8 @@ B<Examples:> $font = $pdf->ttfont('/fonts/Univers-Bold.ttf'); $font = $pdf->ttfont('../Democratica-SmallCaps.ttf'); +=back + =cut sub ttfont { @@ -172,9 +201,13 @@ sub ttfont { return $self->{'api'}->ttfont($file, @opts); } -=item $font = $pdf->psfont($ps_file, %options) +=head2 psfont + + $font = $pdf->psfont($ps_file, %options) -=item $font = $pdf->psfont($ps_file) + $font = $pdf->psfont($ps_file) + +=over Returns a new Type1 (PS) font object. @@ -183,6 +216,8 @@ B<Examples:> $font = $pdf->psfont('TimesRoman.pfa', 'afmfile' => 'TimesRoman.afm', 'encode' => 'latin1'); $font = $pdf->psfont('/fonts/Univers.pfb', 'pfmfile' => '/fonts/Univers.pfm', 'encode' => 'latin2'); +=back + =cut sub psfont { @@ -191,9 +226,13 @@ sub psfont { return $self->{'api'}->psfont(@args); } -#=item @color = $pdf->color($colornumber [, $lightdark ]) +#=head2 color # -#=item @color = $pdf->color($basecolor [, $lightdark ]) +# @color = $pdf->color($colornumber [, $lightdark ]) +# +# @color = $pdf->color($basecolor [, $lightdark ]) +# +#=over # #Returns a color. # @@ -206,6 +245,8 @@ sub psfont { # @color = $pdf->color('red',+1); # red, +10% white # @color = $pdf->color('green',-2); # green, +20% black # +#=back +# #=cut # #sub color { @@ -214,7 +255,11 @@ sub psfont { # return $self->{'api'}->businesscolor(@_); #} -=item $egs = $pdf->create_egs() +=head2 create_egs + + $egs = $pdf->create_egs() + +=over Returns a new extended-graphics-state object. @@ -222,6 +267,8 @@ B<Examples:> $egs = $pdf->create_egs(); +=back + =cut sub create_egs { @@ -230,10 +277,16 @@ sub create_egs { return $self->{'api'}->egstate(); } -=item $img = $pdf->image_jpeg($file) +=head2 image_jpeg + + $img = $pdf->image_jpeg($file) + +=over Returns a new JPEG image object. +=back + =cut sub image_jpeg { @@ -242,10 +295,16 @@ sub image_jpeg { return $self->{'api'}->image_jpeg($file); } -=item $img = $pdf->image_png($file) +=head2 image_png + + $img = $pdf->image_png($file) + +=over Returns a new PNG image object. +=back + =cut sub image_png { @@ -254,12 +313,18 @@ sub image_png { return $self->{'api'}->image_png($file); } -=item $img = $pdf->image_tiff($file, %opts) +=head2 image_tiff + + $img = $pdf->image_tiff($file, %opts) -=item $img = $pdf->image_tiff($file) + $img = $pdf->image_tiff($file) + +=over Returns a new TIFF image object. +=back + =cut sub image_tiff { @@ -268,10 +333,16 @@ sub image_tiff { return $self->{'api'}->image_tiff($file, @opts); } -=item $img = $pdf->image_pnm($file) +=head2 image_pnm + + $img = $pdf->image_pnm($file) + +=over Returns a new PNM image object. +=back + =cut sub image_pnm { @@ -280,10 +351,16 @@ sub image_pnm { return $self->{'api'}->image_pnm($file); } -=item $pdf->savestate() +=head2 savestate + + $pdf->savestate() + +=over Saves the state of the page. +=back + =cut sub savestate { @@ -292,10 +369,16 @@ sub savestate { return $self->{'gfx'}->save(); } -=item $pdf->restorestate() +=head2 restorestate + + $pdf->restorestate() + +=over Restores the state of the page. +=back + =cut sub restorestate { @@ -304,10 +387,16 @@ sub restorestate { return $self->{'gfx'}->restore(); } -=item $pdf->egstate($egs) +=head2 egstate + + $pdf->egstate($egs) + +=over Sets extended-graphics state. +=back + =cut sub egstate { @@ -317,10 +406,16 @@ sub egstate { return $self; } -=item $pdf->fillcolor($color) +=head2 fillcolor + + $pdf->fillcolor($color) + +=over Sets the fill color. See C<strokecolor> for color names and specifications. +=back + =cut sub fillcolor { @@ -330,7 +425,11 @@ sub fillcolor { return $self; } -=item $pdf->strokecolor($color) +=head2 strokecolor + + $pdf->strokecolor($color) + +=over Sets the stroke color. @@ -371,6 +470,8 @@ or the hsv-hex-notation: !hsv, !hhssvv, !hhhsssvvv and !hhhhssssvvvv +=back + =cut sub strokecolor { @@ -380,10 +481,16 @@ sub strokecolor { return $self; } -=item $pdf->linedash(@dash) +=head2 linedash + + $pdf->linedash(@dash) + +=over Sets the line dash pattern. +=back + =cut sub linedash { @@ -392,10 +499,16 @@ sub linedash { return $self; } -=item $pdf->linewidth($width) +=head2 linewidth + + $pdf->linewidth($width) + +=over Sets the line width. +=back + =cut sub linewidth { @@ -405,7 +518,11 @@ sub linewidth { return $self; } -=item $pdf->transform(%opts) +=head2 transform + + $pdf->transform(%opts) + +=over Sets transformations (i.e., translate, rotate, scale, skew) in PDF-canonical order. @@ -418,6 +535,8 @@ B<Example:> 'skew' => [$sa,$sb], ) +=back + =cut sub transform { @@ -427,10 +546,16 @@ sub transform { return $self; } -=item $pdf->move($x,$y) +=head2 move + + $pdf->move($x,$y) + +=over Move to a new drawing location at C[$x,$y]. +=back + =cut sub move { # x,y ... @@ -440,10 +565,16 @@ sub move { # x,y ... return $self; } -=item $pdf->line($x,$y) +=head2 line + + $pdf->line($x,$y) + +=over Draw a line to C[$x,$y]. +=back + =cut sub line { # x,y ... @@ -453,10 +584,16 @@ sub line { # x,y ... return $self; } -=item $pdf->curve($x1,$y1, $x2,$y2, $x3,$y3) +=head2 curve + + $pdf->curve($x1,$y1, $x2,$y2, $x3,$y3) + +=over Draw a Bezier curve with three control points. +=back + =cut sub curve { # x1,y1,x2,y2,x3,y3 ... @@ -465,15 +602,21 @@ sub curve { # x1,y1,x2,y2,x3,y3 ... return $self; } -=item $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir) +=head2 arc -=item $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move) + $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir) + + $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move) + +=over Draw an arc centered at C[$xc,$yc], with x radius C[$rx] and y radius C[$ry], from C[$alpha] degrees to C[$beta] degrees. If C[$move] is I<true>, do B<not> draw a line to the start of the arc. C[$dir] defaults to 0 for counter-clockwise sweep, and may be set to 1 for a clockwise sweep. +=back + =cut sub arc { # xc,yc, rx,ry, alpha,beta ,move [,dir] @@ -483,10 +626,16 @@ sub arc { # xc,yc, rx,ry, alpha,beta ,move [,dir] return $self; } -=item $pdf->ellipse($xc,$yc, $rx,$ry) +=head2 ellipse + + $pdf->ellipse($xc,$yc, $rx,$ry) + +=over Draw an ellipse centered at C[$xc,$yc], with x radius C[$rx] and y radius C[$ry]. +=back + =cut sub ellipse { @@ -496,10 +645,16 @@ sub ellipse { return $self; } -=item $pdf->circle($xc,$yc, $r) +=head2 circle + + $pdf->circle($xc,$yc, $r) + +=over Draw a circle centered at C[$xc,$yc], of radius C[$r]. +=back + =cut sub circle { @@ -509,11 +664,17 @@ sub circle { return $self; } -=item $pdf->rect($x,$y, $w,$h) +=head2 rect + + $pdf->rect($x,$y, $w,$h) + +=over Draw a rectangle with lower left corner at C[$x,$y], width (+x) C[$w] and height (+y) C[$h]. +=back + =cut sub rect { # x,y, w,h ... @@ -523,10 +684,16 @@ sub rect { # x,y, w,h ... return $self; } -=item $pdf->rectxy($x1,$y1, $x2,$y2) +=head2 rectxy + + $pdf->rectxy($x1,$y1, $x2,$y2) + +=over Draw a rectangle with opposite corners C[$x1,$y1] and C[$x2,$y2]. +=back + =cut sub rectxy { @@ -536,11 +703,17 @@ sub rectxy { return $self; } -=item $pdf->poly($x1,$y1, ..., $xn,$yn) +=head2 poly + + $pdf->poly($x1,$y1, ..., $xn,$yn) + +=over Draw a polyline (multiple line segments) starting at (I<move> to) C[$x1,$y1] and continuing on to C[$x2,$y2], ..., C[$xn,$yn]. +=back + =cut sub poly { @@ -550,10 +723,16 @@ sub poly { return $self; } -=item $pdf->close() +=head2 close + + $pdf->close() + +=over Close a shape (draw a line back to the beginning). +=back + =cut sub close { @@ -563,11 +742,17 @@ sub close { return $self; } -=item $pdf->stroke() +=head2 stroke + + $pdf->stroke() + +=over Stroke (actually draw) a shape whose path has already been laid out, using the requested C<strokecolor>. +=back + =cut sub stroke { @@ -577,11 +762,17 @@ sub stroke { return $self; } -=item $pdf->fill() +=head2 fill + + $pdf->fill() + +=over Fill in a closed geometry (path), using the requested C<fillcolor>. The I<non-zero winding rule> is used if the path crosses itself. +=back + =cut sub fill { # nonzero winding rule @@ -591,11 +782,17 @@ sub fill { # nonzero winding rule return $self; } -=item $pdf->fillstroke() +=head2 fillstroke + + $pdf->fillstroke() + +=over Fill (using C<fillcolor>) I<and> stroke (using C<strokecolor>) a closed path. The I<non-zero winding rule> is used if the path crosses itself. +=back + =cut sub fillstroke { # nonzero winding rule @@ -605,11 +802,15 @@ sub fillstroke { # nonzero winding rule return $self; } -=item $pdf->image($imgobj, $x,$y, $w,$h) +=head2 image + + $pdf->image($imgobj, $x,$y, $w,$h) -=item $pdf->image($imgobj, $x,$y, $scale) + $pdf->image($imgobj, $x,$y, $scale) -=item $pdf->image($imgobj, $x,$y) + $pdf->image($imgobj, $x,$y) + +=over B<Please Note:> The width/height or scale given is in user-space coordinates, which are subject to @@ -619,6 +820,8 @@ Per default this has a 72dpi resolution, so if you want an image to have a 150 or 300dpi resolution, you should specify a scale of 72/150 (or 72/300) or adjust width/height accordingly. +=back + =cut sub image { @@ -628,10 +831,16 @@ sub image { return $self; } -=item $pdf->textstart() +=head2 textstart + + $pdf->textstart() + +=over Forces the start of text mode while in graphics. +=back + =cut sub textstart { @@ -641,10 +850,16 @@ sub textstart { return $self; } -=item $pdf->textfont($fontobj, $size) +=head2 textfont + + $pdf->textfont($fontobj, $size) + +=over Define the current font to be an (already defined) font object at the given size. +=back + =cut sub textfont { @@ -654,23 +869,18 @@ sub textfont { return $self; } -=item $txt->textleading($leading) +=head2 textleading -Set the baseline-to-baseline "leading" to be used for text lines. + $txt->textleading($leading) -=item $txt->textlead($leading) +=over Set the baseline-to-baseline "leading" to be used for text lines. -B<Deprecated,> will be removed March 2023 or later. Use textleading(). +=back =cut -# remove on or after March 2023 -sub textlead { - return $_[0]->textleading($_[1]); -} - sub textleading { my $self = shift(); @@ -678,11 +888,17 @@ sub textleading { return $self; } -=item $pdf->text($string) +=head2 text + + $pdf->text($string) + +=over Applies (writes out) the given text at the current text location, using the already-specified font. +=back + =cut sub text { @@ -691,10 +907,16 @@ sub text { return $self->{'gfx'}->text(@_) || $self; } -=item $pdf->nl() +=head2 nl + + $pdf->nl() + +=over Write a newline (drop down to the next line). +=back + =cut sub nl { @@ -704,10 +926,16 @@ sub nl { return $self; } -=item $pdf->textend() +=head2 textend + + $pdf->textend() + +=over Force an end to text output and return to graphics. +=back + =cut sub textend { @@ -717,7 +945,11 @@ sub textend { return $self; } -=item $pdf->print($font, $size, $x,$y, $rot, $just, $text) +=head2 print + + $pdf->print($font, $size, $x,$y, $rot, $just, $text) + +=over Convenience wrapper for shortening the textstart..textend sequence. @@ -725,6 +957,8 @@ Go into text mode, set the font to the object and size, go to the location, set any rotation, set justification, and write the array of text. Justification is 0 for left, 1 for center, and 2 for right. +=back + =cut sub print { @@ -753,8 +987,6 @@ sub print { __END__ -=back - =head1 AUTHOR This module was originally written by Alfred Reibenschuh. It has had some |