Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Imager::Font::Wrap(3) User Contributed Perl DocumentationImager::Font::Wrap(3)

	 Imager::Font::Wrap - simple wrapped text output

	 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,
					.... );

       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".

	   Draw	word-wrapped text.

	   o   "x", "y"	- The top-left corner of the rectangle the text	is
	       formatted into.	Defaults to (0,	0).

	   o   "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

	   o   "height"	- The maximum height of	the formatted text in pixels.
	       Not required.

	   o   "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);

	   o   "image" - The image to render the text to.  Can be supplied as
	       "undef" or not provided to simply calculate the bounding	box.

	   o   "font" -	The font used to render	the text.  Required.

	   o   "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.

	   o   "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.

	   o   "justify"

	       The way text is formatted within	each line.  Possible values

	       o   "left" - left aligned against the left edge of the text

	       o   "right" - right aligned against the right edge of the text

	       o   "center" - centered horizontally in the text	box.

	       o   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.

	   o   "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);

       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.

       Tony Cook <>

       Imager(3), Imager::Font(3)

perl v5.32.1			  2020-06-13		 Imager::Font::Wrap(3)


Want to link to this manual page? Use this URL:

home | help