| 1 | package Imager::Font::BBox; | ||||||||||
| 2 | 2 | ▶ | use 5.006; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 3 | 2 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | |||||||||||
| 5 | 2 | 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 | 0 | ▶ | sub start_offset { | ||||||||
|
Subroutine
start_offset: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 63 | 0 | return $_[0][0]; | |||||||||
| 64 | } | ||||||||||
| 65 | |||||||||||
| 66 | 0 | ▶ | sub neg_width { | ||||||||
|
Subroutine
neg_width: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 67 | 0 | return $_[0][0]; | |||||||||
| 68 | } | ||||||||||
| 69 | |||||||||||
| 70 | 0 | ▶ | sub left_bearing { | ||||||||
|
Subroutine
left_bearing: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 71 | 0 | 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 | 0 | ▶ | sub advance_width { | ||||||||
|
Subroutine
advance_width: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 82 | 0 | my $self = shift; | |||||||||
| 83 | |||||||||||
| 84 | 0 | ▶ | @$self > 6 ? $self->[6] : $self->[2]; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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 | 0 | ▶ | sub right_bearing { | ||||||||
|
Subroutine
right_bearing: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 98 | 0 | my $self = shift; | |||||||||
| 99 | |||||||||||
| 100 | 0 | ▶ | @$self >= 8 && return $self->[7]; # driver gives it to us | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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 | 0 | ▶ | sub display_width { | ||||||||
|
Subroutine
display_width: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 118 | 0 | 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 | 0 | ▶ | sub global_descent { | ||||||||
|
Subroutine
global_descent: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 133 | 0 | 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 | 0 | ▶ | sub global_ascent { | ||||||||
|
Subroutine
global_ascent: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 144 | 0 | 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 | 0 | ▶ | sub descent { | ||||||||
|
Subroutine
descent: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 156 | 0 | 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 | 0 | ▶ | sub ascent { | ||||||||
|
Subroutine
ascent: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 168 | 0 | 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 | 0 | ▶ | sub font_height { | ||||||||
|
Subroutine
font_height: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 178 | 0 | 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 | 0 | ▶ | sub text_height { | ||||||||
|
Subroutine
text_height: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 189 | 0 | 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 | 0 | ▶ | sub total_width { | ||||||||
|
Subroutine
total_width: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 215 | 0 | 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 | 0 | ▶ | sub end_offset { | ||||||||
|
Subroutine
end_offset: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 236 | 0 | return $_[0][2]; | |||||||||
| 237 | } | ||||||||||
| 238 | |||||||||||
| 239 | 0 | ▶ | sub pos_width { | ||||||||
|
Subroutine
pos_width: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 240 | 0 | 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 | 0 | ▶ | sub new { | ||||||||
|
Subroutine
new: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 256 | 0 | 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 <tony@develop-help.com> | ||||||||||
| 274 | |||||||||||
| 275 | =head1 SEE ALSO | ||||||||||
| 276 | |||||||||||
| 277 | Imager(3), Imager::Font(3) | ||||||||||
| 278 | |||||||||||
| 279 | =cut | ||||||||||
| 280 | |||||||||||
| 281 | 2 | 1; | |||||||||
| 282 | |||||||||||