NAME

       Imager::Font::BBox - objects representing the bounding box of a string.

SYNOPSIS

         use Imager::Font;

         # get the object
         my $font = Imager::Font->new(...);
         my $bbox = $font->bounding_box(string=>$text, size=>$size);

         # 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;
         my $ascent = $bbox->ascent;
         my $decent = $bbox->descent;
         my $total_width = $bbox->total_width;
         my $fheight = $bbox->font_height;
         my $theight = $bbox->text_height;
         my $display_width = $bbox->display_width;

DESCRIPTION

       Objects of this class are returned by the Imager::Font bounding_box() method when it is
       called in scalar context.

       This will hopefully make the information from this method more accessible.

METHODS

       start_offset()
       neg_width
       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.

       advance_width()
           The advance width of the string, if the driver supports that, otherwise the same as
           end_offset.

       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.

       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.)

       global_descent()
           The lowest position relative to the font baseline that any character in the font
           reaches in the character cell.  Normally negative.

           At least one font we've seen has reported a positive number for this.

       global_ascent()
           The highest position relative to the font baseline that any character in the font
           reaches in the character cell.  Normally positive.

       descent()
           The lowest position relative to the font baseline that any character in the supplied
           string reaches.  Negative when any character's glyph reaches below the baseline.

       ascent()
           The highest position relative to the font baseline that any character in the supplied
           string reaches.  Positive if any character's glyph reaches above the baseline.

       font_height()
           The maximum displayed height of any string using this font.

       text_height()
           The displayed height of the supplied string.

OBSOLETE METHODS

       These methods include bugs kept for backwards compatibility and shouldn't be used in new
       code.

       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.

       end_offset
       pos_width
           The offset from the selected drawing location to the right edge of the last character
           drawn.  Should always be positive.

           You can use the alias pos_width() if you are used to the bounding_box() documentation
           for list context.

           For backwards compatibility this method returns the maximum of the advance width and
           the offset of the right edge of the last glyph.

INTERNAL FUNCTIONS

       new(...)
           Called by Imager::Font->bounding_box() to create the object.

BUGS

       Doesn't reproduce the functionality that you get using the x and y parameters to
       Imager::Font->bounding_box().  I considered:

         my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)

       but this is about as clumsy as the original.

AUTHOR

       Tony Cook <tony@develop-help.com>

SEE ALSO

       Imager(3), Imager::Font(3)