.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Font::BBox 3pm"
.TH Imager::Font::BBox 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::Font::BBox \- objects representing the bounding box of a string.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  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;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Objects of this class are returned by the Imager::Font \fBbounding_box()\fR
method when it is called in scalar context.
.PP
This will hopefully make the information from this method more
accessible.
.SH METHODS
.IX Header "METHODS"
.IP \fBstart_offset()\fR 4
.IX Item "start_offset()"
.PD 0
.IP neg_width 4
.IX Item "neg_width"
.IP left_bearing 4
.IX Item "left_bearing"
.PD
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.
.Sp
The alias \fBneg_width()\fR is present to match the \fBbounding_box()\fR
documentation for list context.
.Sp
The alias \fBleft_bearing()\fR is present to match font terminology.
.IP \fBadvance_width()\fR 4
.IX Item "advance_width()"
The advance width of the string, if the driver supports that,
otherwise the same as end_offset.
.IP right_bearing 4
.IX Item "right_bearing"
The distance from the right of the last glyph to the end of the advance
point.
.Sp
If the glyph overflows the right side of the advance width this value
is negative.
.IP display_width 4
.IX 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.
.Sp
Equals advance_width \- left_bearing \- right_bearing (and implemented
that way.)
.IP \fBglobal_descent()\fR 4
.IX Item "global_descent()"
The lowest position relative to the font baseline that any character
in the font reaches in the character cell.  Normally negative.
.Sp
At least one font we've seen has reported a positive number for this.
.IP \fBglobal_ascent()\fR 4
.IX Item "global_ascent()"
The highest position relative to the font baseline that any character
in the font reaches in the character cell.  Normally positive.
.IP \fBdescent()\fR 4
.IX Item "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.
.IP \fBascent()\fR 4
.IX Item "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.
.IP \fBfont_height()\fR 4
.IX Item "font_height()"
The maximum displayed height of any string using this font.
.IP \fBtext_height()\fR 4
.IX Item "text_height()"
The displayed height of the supplied string.
.SH "OBSOLETE METHODS"
.IX Header "OBSOLETE METHODS"
These methods include bugs kept for backwards compatibility and
shouldn't be used in new code.
.IP \fBtotal_width()\fR 4
.IX Item "total_width()"
The total displayed width of the string.
.Sp
New code should use \fBdisplay_width()\fR.
.Sp
This depends on \fBend_offset()\fR, and is limited by it's backward
compatibility.
.IP end_offset 4
.IX Item "end_offset"
.PD 0
.IP pos_width 4
.IX Item "pos_width"
.PD
The offset from the selected drawing location to the right edge of the
last character drawn.  Should always be positive.
.Sp
You can use the alias \fBpos_width()\fR if you are used to the
\&\fBbounding_box()\fR documentation for list context.
.Sp
For backwards compatibility this method returns the maximum of the
advance width and the offset of the right edge of the last glyph.
.SH "INTERNAL FUNCTIONS"
.IX Header "INTERNAL FUNCTIONS"
.IP new(...) 4
.IX Item "new(...)"
Called by Imager::Font\->\fBbounding_box()\fR to create the object.
.SH BUGS
.IX Header "BUGS"
Doesn't reproduce the functionality that you get using the x and y
parameters to Imager::Font\->\fBbounding_box()\fR.  I considered:
.PP
.Vb 1
\&  my ($left, $top, $right, $bottom) = $box\->offset(x=>$x, y=>$y)
.Ve
.PP
but this is about as clumsy as the original.
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tony@develop\-help.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBImager\fR\|(3), \fBImager::Font\fR\|(3)