Imager::Font::Wrap(3pm)

1Imager::Font::Wrap(3) User Contributed Perl DocumentationImager::Font::Wrap(3)
2
3
4

NAME

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

SYNOPSIS

9         use Imager::Font::Wrap;
10
11         my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);
12
13         my $font = Imager::Font->new(file=>$fontfile);
14
15         my $string = "..."; # text with or without newlines
16
17         Imager::Font::Wrap->wrap_text( image  => $img,
18                                        font   => $font,
19                                        string => $string,
20                                        x      => $left,
21                                        y      => $top,
22                                        width  => $width,
23                                        .... );
24

DESCRIPTION

26       This is a simple text wrapper with options to control the layout of
27       text within the line.
28
29       You can control the position, width and height of the text with the
30       "image", "x", "y", "width" and "height" options.
31
32       You can simply calculate space usage by setting "image" to "undef", or
33       set "savepos" to see how much text can fit within the given "height".
34
35       wrap_text()
36           Draw word-wrapped text.
37
38           •   "x", "y" - The top-left corner of the rectangle the text is
39               formatted into.  Defaults to (0, 0).
40
41           •   "width" - The width of the formatted text in pixels.  Defaults
42               to the horizontal gap between the top-left corner and the right
43               edge of the image.  If no image is supplied then this is
44               required.
45
46           •   "height" - The maximum height of the formatted text in pixels.
47               Not required.
48
49           •   "savepos" - The amount of text consumed (as a count of
50               characters) will be stored into the scalar this refers to.
51
52                 my $pagenum = 1;
53                 my $string = "...";
54                 my $font = ...;
55                 my $savepos;
56
57                 while (length $string) {
58                   my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);
59                   Imager::Font::Wrap->wrap_text(string=>$string, font=>$font,
60                                                 image=>$img, savepos => \$savepos)
61                     or die $img->errstr;
62                   $savepos > 0
63                     or die "Could not fit any text on page\n";
64                   $string = substr($string, $savepos);
65                   $img->write(file=>"page$pagenum.ppm");
66                 }
67
68           •   "image" - The image to render the text to.  Can be supplied as
69               "undef" or not provided to simply calculate the bounding box.
70
71           •   "font" - The font used to render the text.  Required.
72
73           •   "size" - The size to render the font in.  Defaults to the size
74               stored in the font object.  Required if it isn't stored in the
75               font object.
76
77           •   "string" - The text to render.  This can contain non-white-
78               space, blanks (ASCII 0x20), and newlines.
79
80               Newlines must match /(?:\x0A\x0D?|\x0D\x0A?)/.  White-space
81               other than blanks and newlines are completely ignored.
82
83           •   "justify"
84
85               The way text is formatted within each line.  Possible values
86               include:
87
88               •   "left" - left aligned against the left edge of the text
89                   box.
90
91               •   "right" - right aligned against the right edge of the text
92                   box.
93
94               •   "center" - centered horizontally in the text box.
95
96               •   fill - all but the final line of the paragraph has spaces
97                   expanded so that the line fills from the left to the right
98                   edge of the text box.
99
100           •   "linegap" - Gap between lines of text in pixels.  This is in
101               addition to the size from "$font->font_height".  Can be
102               positive or negative.  Default 0.
103
104           Any other parameters are passed onto Imager::Font->draw().
105
106           Returns a list:
107
108             ($left, $top, $right, $bottom)
109
110           which are the bounds of the space used to layout the text.
111
112           If "height" is set then this is the space used within that height.
113
114           You can use this to calculate the space required to format the text
115           before doing it:
116
117             my ($left, $top, $right, $bottom) =
118               Imager::Font::Wrap->wrap_text(string => $string,
119                                             font   => $font,
120                                             width  => $xsize);
121             my $img = Imager->new(xsize=>$xsize, ysize=>$bottom);
122             Imager::Font::Wrap->wrap_text(string => $string,
123                                           font   => $font,
124                                           width  => $xsize,
125                                           image  => $image);
126

BUGS

128       Imager::Font can handle UTF-8 encoded text itself, but this module
129       doesn't support that (and probably won't).  This could probably be done
130       with regex magic.
131
132       Currently ignores the "sizew" parameter, if you supply one it will be
133       supplied to the draw() function and the text will be too short or too
134       long for the "width".
135
136       Uses a simplistic text model, which is why there's no hyphenation, and
137       no tabs.
138

AUTHOR

140       Tony Cook <tony@develop-help.com>
141

NAME

SYNOPSIS

DESCRIPTION

BUGS

AUTHOR

SEE ALSO