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 =cut
 127
 128 sub advance_width {
 129   my $self = shift;
 130
 131   @$self > 6 ? $self->[6] : $self->[5];
 132 }
 133
 134 =item total_width()
 135
 136 The total displayed width of the string.
 137
 138 =cut
 139
 140 sub total_width {
 141   my $self = shift;
 142
 143   $self->end_offset - $self->start_offset;
 144 }
 145
 146 =item font_height()
 147
 148 The maximum displayed height of any string using this font.
 149
 150 =cut
 151
 152 sub font_height {
 153   my $self = shift;
 154   $self->global_ascent - $self->global_descent;
 155 }
 156
 157 =item text_height()
 158
 159 The displayed height of the supplied string.
 160
 161 =cut
 162
 163 sub text_height {
 164   my $self = shift;
 165
 166   $self->ascent - $self->descent;
 167 }
 168
 169 =back
 170
 171 =head1 INTERNAL FUNCTIONS
 172
 173 =over
 174
 175 =item new(...)
 176
 177 Called by Imager::Font->bounding_box() to create the object.
 178
 179 =cut
 180
 181 sub new {
 182   my $class = shift;
 183   return bless [ @_ ], $class;
 184 }
 185
 186 =back
 187
 188 =head1 BUGS
 189
 190 Doesn't reproduce the functionality that you get using the x and y
 191 parameters to Imager::Font->bounding_box().  I considered:
 192
 193   my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)
 194
 195 but this is about as clumsy as the original.
 196
 197 =head1 AUTHOR
 198
 199 Tony Cook <tony@develop-help.com>
 200
 201 =head1 SEE ALSO
 202
 203 Imager(3), Imager::Font(3)
 204
 205 =cut
 206
 207 1;
 208