<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Imager/Font/BBox.md. Do not edit. -->

```{index} single: Imager::Font::BBox
```

# Imager::Font::BBox

objects representing the bounding box of a string.

## SYNOPSIS

```perl
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:

```perl
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)