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

NOTES

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

BUGS

121       None that I know of, but that doesn't mean much. There may be some
122       problems with exotic fonts, or locales and character encodings that I
123       am not used to.
124

TODO

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

COPYRIGHT

145       copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)
146