- added VERSION numbers to most .pms
[imager.git] / lib / Imager / Font / BBox.pm
1 package Imager::Font::BBox;
2 use strict;
3 use vars qw($VERSION);
4
5 $VERSION = sprintf "%d.%03d", q$Revision$=~/\d+/g;
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 Returns the horizonatal offset from the selected drawing location to
48 the left edge of the first character drawn.  If this is positive, the
49 first glyph is to the right of the drawing location.
50
51 The alias neg_width() is present to match the bounding_box()
52 documentation for list context.
53
54 The alias left_bearing() is present to match font terminology.
55
56 =cut
57
58 sub start_offset {
59   return $_[0][0];
60 }
61
62 sub neg_width {
63   return $_[0][0];
64 }
65
66 sub left_bearing {
67   return $_[0][0];
68 }
69
70 =item end_offset()
71
72 The offset from the selected drawing location to the right edge of the
73 last character drawn.  Should always be positive.
74
75 You can use the alias pos_width() if you are used to the
76 bounding_box() documentation for list context.
77
78 =cut
79
80 sub end_offset {
81   return $_[0][2];
82 }
83
84 sub pos_width {
85   return $_[0][2];
86 }
87
88 =item global_descent()
89
90 The lowest position relative to the font baseline that any character
91 in the font reaches in the character cell.  Normally negative.
92
93 At least one font we've seen has reported a positive number for this.
94
95 =cut
96
97 sub global_descent {
98   return $_[0][1];
99 }
100
101 =item global_ascent()
102
103 The highest position relative to the font baseline that any character
104 in the font reaches in the character cell.  Normally positive.
105
106 =cut
107
108 sub global_ascent {
109   return $_[0][3];
110 }
111
112 =item descent()
113
114 The lowest position relative to the font baseline that any character
115 in the supplied string reaches.  Negative when any character's glyph
116 reaches below the baseline.
117
118 =cut
119
120 sub descent {
121   return $_[0][4];
122 }
123
124 =item ascent()
125
126 The highest position relative to the font baseline that any character
127 in the supplied string reaches.  Positive if any character's glyph
128 reaches above the baseline.
129
130 =cut
131
132 sub ascent {
133   return $_[0][5];
134 }
135
136 =item advance_width()
137
138 The advance width of the string, if the driver supports that,
139 otherwise the same as end_offset.
140
141 =cut
142
143 sub advance_width {
144   my $self = shift;
145
146   @$self > 6 ? $self->[6] : $self->[2];
147 }
148
149 =item total_width()
150
151 The total displayed width of the string.
152
153 =cut
154
155 sub total_width {
156   my $self = shift;
157
158   $self->end_offset - $self->start_offset;
159 }
160
161 =item font_height()
162
163 The maximum displayed height of any string using this font.
164
165 =cut
166
167 sub font_height {
168   my $self = shift;
169   $self->global_ascent - $self->global_descent;
170 }
171
172 =item text_height()
173
174 The displayed height of the supplied string.
175
176 =cut
177
178 sub text_height {
179   my $self = shift;
180
181   $self->ascent - $self->descent;
182 }
183
184 =item right_bearing
185
186 The distance from the right of the last glyph to the end of the advance
187 point.
188
189 If the glyph overflows the right side of the advance width this value
190 is negative.
191
192 =cut
193
194 sub right_bearing {
195   my $self = shift;
196
197   @$self >= 8 && return $self->[7]; # driver gives it to us
198
199   # otherwise the closest we have is the difference between the 
200   # end_pos and advance_width
201   return $self->advance_width - $self->pos_width;
202 }
203
204 =item display_width
205
206 The distance from the left-most pixel of the left-most glyph to the
207 right-most pixel of the right-most glyph.
208
209 Equals advance_width - left_bearing - right_bearing (and implemented
210 that way.)
211
212 =cut
213
214 sub display_width {
215   my ($self) = @_;
216
217   $self->advance_width - $self->left_bearing - $self->right_bearing;
218 }
219
220 =back
221
222 =head1 INTERNAL FUNCTIONS
223
224 =over
225
226 =item new(...)
227
228 Called by Imager::Font->bounding_box() to create the object.
229
230 =cut
231
232 sub new {
233   my $class = shift;
234   return bless [ @_ ], $class;
235 }
236
237 =back
238
239 =head1 BUGS
240
241 Doesn't reproduce the functionality that you get using the x and y
242 parameters to Imager::Font->bounding_box().  I considered:
243
244   my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)
245
246 but this is about as clumsy as the original.
247
248 =head1 AUTHOR
249
250 Tony Cook <tony@develop-help.com>
251
252 =head1 SEE ALSO
253
254 Imager(3), Imager::Font(3)
255
256 =cut
257
258 1;
259