File Coverage

blib/lib/Imager/Font/BBox.pm
Criterion Covered Total %
statement 5 29 17.2
branch 0 4 0.0
condition n/a
subroutine 2 18 11.1
pod 16 16 100.0
total 23 67 34.3


line stmt bran cond sub pod time code
1             package Imager::Font::BBox;
2 1     1   755 use 5.006;
  1         3  
3 1     1   4 use strict;
  1         1  
  1         405  
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 0     0 1   return $_[0][0];
64             }
65              
66             sub neg_width {
67 0     0 1   return $_[0][0];
68             }
69              
70             sub left_bearing {
71 0     0 1   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 0     0 1   my $self = shift;
83              
84 0 0         @$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 0     0 1   my $self = shift;
99              
100 0 0         @$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 0           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 0     0 1   my ($self) = @_;
119              
120 0           $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 0     0 1   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 0     0 1   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 0     0 1   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 0     0 1   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 0     0 1   my $self = shift;
179 0           $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 0     0 1   my $self = shift;
190              
191 0           $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 0     0 1   my $self = shift;
216              
217 0           $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 0     0 1   return $_[0][2];
237             }
238              
239             sub pos_width {
240 0     0 1   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 0     0 1   my $class = shift;
257 0           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
274              
275             =head1 SEE ALSO
276              
277             Imager(3), Imager::Font(3)
278              
279             =cut
280              
281             1;
282