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