NAME¶
Imager::Font::Wrap - simple wrapped text output
SYNOPSIS¶
use Imager::Font::Wrap;
my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);
my $font = Imager::Font->new(file=>$fontfile);
my $string = "..."; # text with or without newlines
Imager::Font::Wrap->wrap_text( image => $img,
font => $font,
string => $string,
x => $left,
y => $top,
width => $width,
.... );
DESCRIPTION¶
This is a simple text wrapper with options to control the layout of text within
the line.
You can control the position, width and height of the text with the
"image", "x", "y", "width" and
"height" options.
You can simply calculate space usage by setting "image" to
"undef", or set "savepos" to see how much text can fit
within the given "height".
- wrap_text()
- Draw word-wrapped text.
- •
- "x", "y" - The top-left corner of the rectangle the
text is formatted into. Defaults to (0, 0).
- •
- "width" - The width of the formatted text in pixels. Defaults to
the horizontal gap between the top-left corner and the right edge of the
image. If no image is supplied then this is required.
- •
- "height" - The maximum height of the formatted text in pixels.
Not required.
- •
- "savepos" - The amount of text consumed (as a count of
characters) will be stored into the scalar this refers to.
my $pagenum = 1;
my $string = "...";
my $font = ...;
my $savepos;
while (length $string) {
my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);
Imager::Font::Wrap->wrap_text(string=>$string, font=>$font,
image=>$img, savepos => \$savepos)
or die $img->errstr;
$savepos > 0
or die "Could not fit any text on page\n";
$string = substr($string, $savepos);
$img->write(file=>"page$pagenum.ppm");
}
- •
- "image" - The image to render the text to. Can be supplied as
"undef" or not provided to simply calculate the bounding
box.
- •
- "font" - The font used to render the text. Required.
- •
- "size" - The size to render the font in. Defaults to the size
stored in the font object. Required if it isn't stored in the font
object.
- •
- "string" - The text to render. This can contain non-white-space,
blanks (ASCII 0x20), and newlines.
Newlines must match /(?:\x0A\x0D?|\x0D\x0A?)/. White-space other than blanks
and newlines are completely ignored.
- •
- "justify"
The way text is formatted within each line. Possible values include:
- •
- "left" - left aligned against the left edge of the text
box.
- •
- "right" - right aligned against the right edge of the text
box.
- •
- "center" - centered horizontally in the text box.
- •
- fill - all but the final line of the paragraph has spaces expanded so that
the line fills from the left to the right edge of the text box.
- •
- "linegap" - Gap between lines of text in pixels. This is in
addition to the size from "$font->font_height". Can be
positive or negative. Default 0.
Any other parameters are passed onto Imager::Font->
draw().
Returns a list:
($left, $top, $right, $bottom)
which are the bounds of the space used to layout the text.
If "height" is set then this is the space used within that height.
You can use this to calculate the space required to format the text before doing
it:
my ($left, $top, $right, $bottom) =
Imager::Font::Wrap->wrap_text(string => $string,
font => $font,
width => $xsize);
my $img = Imager->new(xsize=>$xsize, ysize=>$bottom);
Imager::Font::Wrap->wrap_text(string => $string,
font => $font,
width => $xsize,
image => $image);
BUGS¶
Imager::Font can handle UTF-8 encoded text itself, but this module doesn't
support that (and probably won't). This could probably be done with regex
magic.
Currently ignores the "sizew" parameter, if you supply one it will be
supplied to the
draw() function and the text will be too short or too
long for the "width".
Uses a simplistic text model, which is why there's no hyphenation, and no tabs.
AUTHOR¶
Tony Cook <tony@develop-help.com>
SEE ALSO¶
Imager(3),
Imager::Font(3)