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