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