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

BUGS

137       Imager::Font can handle UTF8 encoded text itself, but this module
138       doesn't support that (and probably won't).  This could probably be done
139       with regex magic.
140
141       Currently ignores the "sizew" parameter, if you supply one it will be
142       supplied to the draw() function and the text will be too short or too
143       long for the "width".
144
145       Uses a simplistic text model, which is why there's no hyphenation, and
146       no tabs.
147

AUTHOR

149       Tony Cook <tony@develop-help.com>
150

NAME

SYNOPSIS

DESCRIPTION

BUGS

AUTHOR

SEE ALSO