eliminate use vars
[imager.git] / lib / Imager / Font / BBox.pm
CommitLineData
3799c4d1 1package Imager::Font::BBox;
ee64a81f 2use 5.006;
3799c4d1 3use strict;
f17b46d8 4
ee64a81f 5our $VERSION = "1.007";
3799c4d1
TC
6
7=head1 NAME
8
9Imager::Font::BBox - objects representing the bounding box of a string.
10
11=head1 SYNOPSIS
12
13 use Imager::Font;
14
15 # get the object
16 my $font = Imager::Font->new(...);
17 my $bbox = $font->bounding_box(string=>$text, size=>$size);
18
19 # methods
20 my $start = $bbox->start_offset;
dc35bde9
TC
21 my $left_bearing = $bbox->left_bearing;
22 my $right_bearing = $bbox->right_bearing;
3799c4d1
TC
23 my $end = $bbox->end_offset;
24 my $gdescent = $box->global_descent;
25 my $gascent = $bbox->global_ascent;
26 my $ascent = $bbox->ascent;
27 my $decent = $bbox->descent;
28 my $total_width = $bbox->total_width;
29 my $fheight = $bbox->font_height;
30 my $theight = $bbox->text_height;
dc35bde9 31 my $display_width = $bbox->display_width;
3799c4d1
TC
32
33=head1 DESCRIPTION
34
35Objects of this class are returned by the Imager::Font bounding_box()
36method when it is called in scalar context.
37
38This will hopefully make the information from this method more
39accessible.
40
41=head1 METHODS
42
43=over
44
45=item start_offset()
46
d5556805
TC
47=item neg_width
48
49=item left_bearing
50
5715f7c3 51Returns the horizontal offset from the selected drawing location to
3799c4d1
TC
52the left edge of the first character drawn. If this is positive, the
53first glyph is to the right of the drawing location.
54
55The alias neg_width() is present to match the bounding_box()
56documentation for list context.
57
dc35bde9
TC
58The alias left_bearing() is present to match font terminology.
59
3799c4d1
TC
60=cut
61
62sub start_offset {
63 return $_[0][0];
64}
65
66sub neg_width {
67 return $_[0][0];
68}
69
dc35bde9
TC
70sub left_bearing {
71 return $_[0][0];
72}
73
6b22ba84 74=item advance_width()
d5556805 75
6b22ba84
TC
76The advance width of the string, if the driver supports that,
77otherwise the same as end_offset.
3799c4d1 78
6b22ba84 79=cut
3799c4d1 80
6b22ba84
TC
81sub advance_width {
82 my $self = shift;
83
84 @$self > 6 ? $self->[6] : $self->[2];
85}
86
87=item right_bearing
88
89The distance from the right of the last glyph to the end of the advance
90point.
91
92If the glyph overflows the right side of the advance width this value
93is negative.
3799c4d1
TC
94
95=cut
96
6b22ba84
TC
97sub right_bearing {
98 my $self = shift;
99
100 @$self >= 8 && return $self->[7]; # driver gives it to us
101
102 # otherwise the closest we have is the difference between the
103 # end_pos and advance_width
104 return $self->advance_width - $self->pos_width;
3799c4d1
TC
105}
106
6b22ba84
TC
107=item display_width
108
109The distance from the left-most pixel of the left-most glyph to the
110right-most pixel of the right-most glyph.
111
112Equals advance_width - left_bearing - right_bearing (and implemented
113that way.)
114
115=cut
116
117sub display_width {
118 my ($self) = @_;
119
120 $self->advance_width - $self->left_bearing - $self->right_bearing;
3799c4d1
TC
121}
122
123=item global_descent()
124
125The lowest position relative to the font baseline that any character
126in the font reaches in the character cell. Normally negative.
127
128At least one font we've seen has reported a positive number for this.
129
130=cut
131
132sub global_descent {
133 return $_[0][1];
134}
135
136=item global_ascent()
137
138The highest position relative to the font baseline that any character
139in the font reaches in the character cell. Normally positive.
140
141=cut
142
143sub global_ascent {
144 return $_[0][3];
145}
146
147=item descent()
148
149The lowest position relative to the font baseline that any character
150in the supplied string reaches. Negative when any character's glyph
151reaches below the baseline.
152
153=cut
154
155sub descent {
156 return $_[0][4];
157}
158
159=item ascent()
160
161The highest position relative to the font baseline that any character
162in the supplied string reaches. Positive if any character's glyph
163reaches above the baseline.
164
165=cut
166
167sub ascent {
168 return $_[0][5];
169}
170
3799c4d1
TC
171=item font_height()
172
173The maximum displayed height of any string using this font.
174
175=cut
176
177sub font_height {
178 my $self = shift;
179 $self->global_ascent - $self->global_descent;
180}
181
182=item text_height()
183
184The displayed height of the supplied string.
185
186=cut
187
188sub text_height {
189 my $self = shift;
190
191 $self->ascent - $self->descent;
192}
193
6b22ba84 194=back
dc35bde9 195
6b22ba84 196=head1 OBSOLETE METHODS
dc35bde9 197
6b22ba84
TC
198These methods include bugs kept for backwards compatibility and
199shouldn't be used in new code.
200
201=over
202
203=item total_width()
204
205The total displayed width of the string.
206
207New code should use display_width().
208
209This depends on end_offset(), and is limited by it's backward
210compatibility.
dc35bde9
TC
211
212=cut
213
6b22ba84 214sub total_width {
dc35bde9
TC
215 my $self = shift;
216
6b22ba84 217 $self->end_offset - $self->start_offset;
dc35bde9
TC
218}
219
6b22ba84 220=item end_offset
dc35bde9 221
6b22ba84 222=item pos_width
dc35bde9 223
6b22ba84
TC
224The offset from the selected drawing location to the right edge of the
225last character drawn. Should always be positive.
226
227You can use the alias pos_width() if you are used to the
228bounding_box() documentation for list context.
229
230For backwards compatibility this method returns the maximum of the
231advance width and the offset of the right edge of the last glyph.
dc35bde9
TC
232
233=cut
234
6b22ba84
TC
235sub end_offset {
236 return $_[0][2];
237}
dc35bde9 238
6b22ba84
TC
239sub pos_width {
240 return $_[0][2];
dc35bde9
TC
241}
242
3799c4d1
TC
243=back
244
245=head1 INTERNAL FUNCTIONS
246
247=over
248
249=item new(...)
250
251Called by Imager::Font->bounding_box() to create the object.
252
253=cut
254
255sub new {
256 my $class = shift;
257 return bless [ @_ ], $class;
258}
259
260=back
261
262=head1 BUGS
263
264Doesn't reproduce the functionality that you get using the x and y
265parameters to Imager::Font->bounding_box(). I considered:
266
267 my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)
268
269but this is about as clumsy as the original.
270
271=head1 AUTHOR
272
273Tony Cook <tony@develop-help.com>
274
275=head1 SEE ALSO
276
277Imager(3), Imager::Font(3)
278
279=cut
280
2811;
282