eliminate use vars
[imager.git] / lib / Imager / Font / BBox.pm
index f39c864..579378a 100644 (file)
@@ -1,6 +1,9 @@
 package Imager::Font::BBox;
+use 5.006;
 use strict;
 
+our $VERSION = "1.007";
+
 =head1 NAME
 
 Imager::Font::BBox - objects representing the bounding box of a string.
@@ -15,6 +18,8 @@ Imager::Font::BBox - objects representing the bounding box of a string.
 
   # methods
   my $start = $bbox->start_offset;
+  my $left_bearing = $bbox->left_bearing;
+  my $right_bearing = $bbox->right_bearing;
   my $end = $bbox->end_offset;
   my $gdescent = $box->global_descent;
   my $gascent = $bbox->global_ascent;
@@ -23,6 +28,7 @@ Imager::Font::BBox - objects representing the bounding box of a string.
   my $total_width = $bbox->total_width;
   my $fheight = $bbox->font_height;
   my $theight = $bbox->text_height;
+  my $display_width = $bbox->display_width;
 
 =head1 DESCRIPTION
 
@@ -38,13 +44,19 @@ accessible.
 
 =item start_offset()
 
-Returns the horizonatal offset from the selected drawing location to
+=item neg_width
+
+=item left_bearing
+
+Returns the horizontal offset from the selected drawing location to
 the left edge of the first character drawn.  If this is positive, the
 first glyph is to the right of the drawing location.
 
 The alias neg_width() is present to match the bounding_box()
 documentation for list context.
 
+The alias left_bearing() is present to match font terminology.
+
 =cut
 
 sub start_offset {
@@ -55,22 +67,57 @@ sub neg_width {
   return $_[0][0];
 }
 
-=item end_offset()
+sub left_bearing {
+  return $_[0][0];
+}
 
-The offset from the selected drawing location to the right edge of the
-last character drawn.  Should always be positive.
+=item advance_width()
 
-You can use the alias pos_width() if you are used to the
-bounding_box() documentation for list context.
+The advance width of the string, if the driver supports that,
+otherwise the same as end_offset.
 
 =cut
 
-sub end_offset {
-  return $_[0][2];
+sub advance_width {
+  my $self = shift;
+
+  @$self > 6 ? $self->[6] : $self->[2];
 }
 
-sub pos_width {
-  return $_[0][2];
+=item right_bearing
+
+The distance from the right of the last glyph to the end of the advance
+point.
+
+If the glyph overflows the right side of the advance width this value
+is negative.
+
+=cut
+
+sub right_bearing {
+  my $self = shift;
+
+  @$self >= 8 && return $self->[7]; # driver gives it to us
+
+  # otherwise the closest we have is the difference between the 
+  # end_pos and advance_width
+  return $self->advance_width - $self->pos_width;
+}
+
+=item display_width
+
+The distance from the left-most pixel of the left-most glyph to the
+right-most pixel of the right-most glyph.
+
+Equals advance_width - left_bearing - right_bearing (and implemented
+that way.)
+
+=cut
+
+sub display_width {
+  my ($self) = @_;
+
+  $self->advance_width - $self->left_bearing - $self->right_bearing;
 }
 
 =item global_descent()
@@ -121,20 +168,47 @@ sub ascent {
   return $_[0][5];
 }
 
-=item advance_width()
+=item font_height()
+
+The maximum displayed height of any string using this font.
 
 =cut
 
-sub advance_width {
+sub font_height {
+  my $self = shift;
+  $self->global_ascent - $self->global_descent;
+}
+
+=item text_height()
+
+The displayed height of the supplied string.
+
+=cut
+
+sub text_height {
   my $self = shift;
 
-  @$self > 6 ? $self->[6] : $self->[5];
+  $self->ascent - $self->descent;
 }
 
+=back
+
+=head1 OBSOLETE METHODS
+
+These methods include bugs kept for backwards compatibility and
+shouldn't be used in new code.
+
+=over
+
 =item total_width()
 
 The total displayed width of the string.
 
+New code should use display_width().
+
+This depends on end_offset(), and is limited by it's backward
+compatibility.
+
 =cut
 
 sub total_width {
@@ -143,27 +217,27 @@ sub total_width {
   $self->end_offset - $self->start_offset;
 }
 
-=item font_height()
+=item end_offset
 
-The maximum displayed height of any string using this font.
+=item pos_width
 
-=cut
-
-sub font_height {
-  my $self = shift;
-  $self->global_ascent - $self->global_descent;
-}
+The offset from the selected drawing location to the right edge of the
+last character drawn.  Should always be positive.
 
-=item text_height()
+You can use the alias pos_width() if you are used to the
+bounding_box() documentation for list context.
 
-The displayed height of the supplied string.
+For backwards compatibility this method returns the maximum of the
+advance width and the offset of the right edge of the last glyph.
 
 =cut
 
-sub text_height {
-  my $self = shift;
+sub end_offset {
+  return $_[0][2];
+}
 
-  $self->ascent - $self->descent;
+sub pos_width {
+  return $_[0][2];
 }
 
 =back