- Imager::Font::BBox advance_width() method was falling back to
[imager.git] / lib / Imager / Font / BBox.pm
1 package Imager::Font::BBox;
2 use strict;
3
4 =head1 NAME
5
6 Imager::Font::BBox - objects representing the bounding box of a string.
7
8 =head1 SYNOPSIS
9
10   use Imager::Font;
11
12   # get the object
13   my $font = Imager::Font->new(...);
14   my $bbox = $font->bounding_box(string=>$text, size=>$size);
15
16   # methods
17   my $start = $bbox->start_offset;
18   my $end = $bbox->end_offset;
19   my $gdescent = $box->global_descent;
20   my $gascent = $bbox->global_ascent;
21   my $ascent = $bbox->ascent;
22   my $decent = $bbox->descent;
23   my $total_width = $bbox->total_width;
24   my $fheight = $bbox->font_height;
25   my $theight = $bbox->text_height;
26
27 =head1 DESCRIPTION
28
29 Objects of this class are returned by the Imager::Font bounding_box()
30 method when it is called in scalar context.
31
32 This will hopefully make the information from this method more
33 accessible.
34
35 =head1 METHODS
36
37 =over
38
39 =item start_offset()
40
41 Returns the horizonatal offset from the selected drawing location to
42 the left edge of the first character drawn.  If this is positive, the
43 first glyph is to the right of the drawing location.
44
45 The alias neg_width() is present to match the bounding_box()
46 documentation for list context.
47
48 =cut
49
50 sub start_offset {
51   return $_[0][0];
52 }
53
54 sub neg_width {
55   return $_[0][0];
56 }
57
58 =item end_offset()
59
60 The offset from the selected drawing location to the right edge of the
61 last character drawn.  Should always be positive.
62
63 You can use the alias pos_width() if you are used to the
64 bounding_box() documentation for list context.
65
66 =cut
67
68 sub end_offset {
69   return $_[0][2];
70 }
71
72 sub pos_width {
73   return $_[0][2];
74 }
75
76 =item global_descent()
77
78 The lowest position relative to the font baseline that any character
79 in the font reaches in the character cell.  Normally negative.
80
81 At least one font we've seen has reported a positive number for this.
82
83 =cut
84
85 sub global_descent {
86   return $_[0][1];
87 }
88
89 =item global_ascent()
90
91 The highest position relative to the font baseline that any character
92 in the font reaches in the character cell.  Normally positive.
93
94 =cut
95
96 sub global_ascent {
97   return $_[0][3];
98 }
99
100 =item descent()
101
102 The lowest position relative to the font baseline that any character
103 in the supplied string reaches.  Negative when any character's glyph
104 reaches below the baseline.
105
106 =cut
107
108 sub descent {
109   return $_[0][4];
110 }
111
112 =item ascent()
113
114 The highest position relative to the font baseline that any character
115 in the supplied string reaches.  Positive if any character's glyph
116 reaches above the baseline.
117
118 =cut
119
120 sub ascent {
121   return $_[0][5];
122 }
123
124 =item advance_width()
125
126 The advance width of the string, if the driver supports that,
127 otherwise the same as end_offset.
128
129 =cut
130
131 sub advance_width {
132   my $self = shift;
133
134   @$self > 6 ? $self->[6] : $self->[2];
135 }
136
137 =item total_width()
138
139 The total displayed width of the string.
140
141 =cut
142
143 sub total_width {
144   my $self = shift;
145
146   $self->end_offset - $self->start_offset;
147 }
148
149 =item font_height()
150
151 The maximum displayed height of any string using this font.
152
153 =cut
154
155 sub font_height {
156   my $self = shift;
157   $self->global_ascent - $self->global_descent;
158 }
159
160 =item text_height()
161
162 The displayed height of the supplied string.
163
164 =cut
165
166 sub text_height {
167   my $self = shift;
168
169   $self->ascent - $self->descent;
170 }
171
172 =back
173
174 =head1 INTERNAL FUNCTIONS
175
176 =over
177
178 =item new(...)
179
180 Called by Imager::Font->bounding_box() to create the object.
181
182 =cut
183
184 sub new {
185   my $class = shift;
186   return bless [ @_ ], $class;
187 }
188
189 =back
190
191 =head1 BUGS
192
193 Doesn't reproduce the functionality that you get using the x and y
194 parameters to Imager::Font->bounding_box().  I considered:
195
196   my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)
197
198 but this is about as clumsy as the original.
199
200 =head1 AUTHOR
201
202 Tony Cook <tony@develop-help.com>
203
204 =head1 SEE ALSO
205
206 Imager(3), Imager::Font(3)
207
208 =cut
209
210 1;
211