GD::Text::Wrap(3pm)

1Text::Wrap(3)         User Contributed Perl Documentation        Text::Wrap(3)
2
3
4

NAME

6       GD::Text::Wrap - Wrap strings in boxes
7

SYNOPSIS

9         use GD;
10         use GD::Text::Wrap;
11
12         my $gd = GD::Image->new(800,600);
13         # allocate colours, do other things.
14
15         my $text = <<EOSTR;
16         Lorem ipsum dolor sit amet, consectetuer adipiscing elit,
17         sed diam nonummy nibh euismod tincidunt ut laoreet dolore
18         magna aliquam erat volutpat.
19         EOSTR
20
21         my $wrapbox = GDTextWrap->new( $gd,
22             line_space  => 4,
23             color       => $black,
24             text        => $text,
25         );
26         $wrapbox->set_font(gdMediumBoldFont);
27         $wrapbox->set_font('arial', 12);
28         $wrapbox->set(align => 'left', width => 120);
29         $wrapbox->draw(10,140);
30
31         $gd->rectangle($wrap_box->get_bounds(10,140), $color);
32

DESCRIPTION

34       GD::Text::Wrap provides an object that draws a formatted paragraph of
35       text in a box on a GD::Image canvas, using either a builtin GD font or
36       a TrueType font.
37

METHODS

39       This class doesn't inherit from GD::Text directly, but delegates most
40       of its work to it (in fact to a GD::Text::Align object. That means that
41       most of the GD::Text::Align methods are available for this class,
42       specifically "set_font" and "font_path". Other methods and methods with
43       a different interface are described here:
44
45       GD::Text::Wrap->new( $gd_object, attribute => value, ... )
46
47       Create a new object. The first argument to new has to be a valid
48       GD::Image object. The other arguments will be passed to the set()
49       method for initialisation of the attributes.
50
51       $wrapbox->set( attribute => value, ... )
52
53       set the value for an attribute. Valid attributes are:
54
55       width
56           The width of the box to draw the text in. If unspecified, they will
57           default to the width of the GD::Image object.
58
59       line_space
60           The number of pixels between lines. Defaults to 2.
61
62       para_space, paragraph_space
63           The number of extra pixels between paragraphs, above line_space.
64           Defaults to 0.
65
66       color, colour
67           Synonyms. The colour to use when drawing the font. Will be ini‐
68           tialised to the last colour in the GD object's palette.
69
70       align, alignment
71           Synonyms. One of 'justified' (the default), 'left', 'right' or
72           'center'.
73
74       text
75           The text to draw. This is the only attribute that you absolutely
76           have to set.
77
78       preserve_nl
79           If set to a true value, newlines in the text will cause a line
80           break.  Note that lines will still be justified. If only one word
81           appears on the line, it could get ugly.  Defaults to 0.
82
83       As with the methods, attributes unknown to this class get delegated to
84       the GD::Text::Align class.
85
86       $wrapbox->get( attribute );
87
88       Get the current value of an attribute. All attributes mentioned under
89       the "set()" method can be retrieved
90
91       $wrapbox->get_bounds()
92
93       Returns the bounding box of the box that will be drawn with the current
94       attribute settings as a list. The values returned are the coordinates
95       of the upper left and lower right corner.
96
97               ($left, $top, $right, $bottom) = $wrapbox->get_bounds();
98
99       Returns an empty list on error.
100
101       NOTE: The return list of this method may change in a future implementa‐
102       tion that allows angled boxes.
103
104       $wrapbox->draw(x, y)
105
106       Draw the box, with (x,y) as the top right corner.  Returns the same
107       values as the "getbounds()" method.
108
109       NOTE: The return list of this method may change in a future implementa‐
110       tion that allows angled boxes.
111

NOTES

113       As with all Modules for Perl: Please stick to using the interface. If
114       you try to fiddle too much with knowledge of the internals of this mod‐
115       ule, you may get burned. I may change them at any time.
116
117       You can only use TrueType fonts with version of GD > 1.20, and then
118       only if compiled with support for this. If you attempt to do it anyway,
119       you will get errors.
120
121       Even though this module lives in the GD::Text namespace, it is not a
122       GD::Text. It does however delegate a lot of its functionality to a con‐
123       tained object that is one (GD::Text::Align).
124

BUGS

126       None that I know of, but that doesn't mean much. There may be some
127       problems with exotic fonts, or locales and character encodings that I
128       am not used to.
129

TODO

131       Angled boxes.
132
133       At the moment, the only bit of the box that is allowed to be unspeci‐
134       fied and in fact must be unspecified, is the bottom. If there is enough
135       need for it, I might implement more flexibility, in that that you need
136       to only specify three of the four sides of the box, and the fourth will
137       be calculated.
138
139       Automatic resizing of a TrueType font to fit inside a box when four
140       sides are specified, or maybe some other nifty things.
141
142       More flexibility in the interface. Especially draw needs some thought.
143
144       More and better error handling.
145
146       Warnings for lines that are too long and stick out of the box.  Warning
147       for emptyish lines?
148

COPYRIGHT

150       copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)
151