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