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

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

# Imager::Font::Wrap

```text
Imager::Font::Wrap - simple wrapped text output
```

## SYNOPSIS

```perl
use Imager::Font::Wrap;

my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);

my $font = Imager::Font->new(file=>$fontfile);

my $string = "..."; # text with or without newlines

Imager::Font::Wrap->wrap_text( image  => $img,
                               font   => $font,
                               string => $string,
                               x      => $left,
                               y      => $top,
                               width  => $width,
                               .... );
```

## DESCRIPTION

This is a simple text wrapper with options to control the layout of
text within the line.

You can control the position, width and height of the text with the
`image`, `x`, `y`, `width` and `height` options.

You can simply calculate space usage by setting `image` to `undef`,
or set `savepos` to see how much text can fit within the given
`height`.

- wrap\_text()

    Draw word-wrapped text.

    - `x`, `y` - The top-left corner of the rectangle the text is
    formatted into.  Defaults to (0, 0).
    - `width` - The width of the formatted text in pixels.  Defaults to the
    horizontal gap between the top-left corner and the right edge of the
    image.  If no image is supplied then this is required.
    - `height` - The maximum height of the formatted text in pixels.  Not
    required.
    - `savepos` - The amount of text consumed (as a count of characters)
    will be stored into the scalar this refers to.

        ```perl
        my $pagenum = 1;
        my $string = "...";
        my $font = ...;
        my $savepos;

        while (length $string) { 
          my $img = Imager->new(xsize=>$xsize, ysize=>$ysize);
          Imager::Font::Wrap->wrap_text(string=>$string, font=>$font, 
                                        image=>$img, savepos => \$savepos)
            or die $img->errstr;
          $savepos > 0
            or die "Could not fit any text on page\n";
          $string = substr($string, $savepos);
          $img->write(file=>"page$pagenum.ppm");
        }
        ```

    - `image` - The image to render the text to.  Can be supplied as
    `undef` or not provided to simply calculate the bounding box.
    - `font` - The font used to render the text.  Required.
    - `size` - The size to render the font in.  Defaults to the size stored
    in the font object.  Required if it isn't stored in the font object.
    - `string` - The text to render.  This can contain non-white-space,
    blanks (ASCII 0x20), and newlines.

        Newlines must match /(?:\\x0A\\x0D?|\\x0D\\x0A?)/.  White-space other than
        blanks and newlines are completely ignored.

    - `justify`

        The way text is formatted within each line.  Possible values include:

        - `left` - left aligned against the left edge of the text box.
        - `right` - right aligned against the right edge of the text box.
        - `center` - centered horizontally in the text box.
        - fill - all but the final line of the paragraph has spaces expanded so
        that the line fills from the left to the right edge of the text box.

    - `linegap` - Gap between lines of text in pixels.  This is in addition
    to the size from `$font->font_height`.  Can be positive or
    negative.  Default 0.

    Any other parameters are passed onto Imager::Font->draw().

    Returns a list:

    ```perl
    ($left, $top, $right, $bottom)
    ```

    which are the bounds of the space used to layout the text.

    If `height` is set then this is the space used within that height.

    You can use this to calculate the space required to format the text
    before doing it:

    ```perl
    my ($left, $top, $right, $bottom) =
      Imager::Font::Wrap->wrap_text(string => $string,
                                    font   => $font,
                                    width  => $xsize);
    my $img = Imager->new(xsize=>$xsize, ysize=>$bottom);
    Imager::Font::Wrap->wrap_text(string => $string,
                                  font   => $font,
                                  width  => $xsize,
                                  image  => $image);
    ```

## BUGS

Imager::Font can handle UTF-8 encoded text itself, but this module
doesn't support that (and probably won't).  This could probably be
done with regex magic.

Currently ignores the `sizew` parameter, if you supply one it will be
supplied to the draw() function and the text will be too short or too
long for the `width`.

Uses a simplistic text model, which is why there's no hyphenation, and
no tabs.

## AUTHOR

Tony Cook <tony@develop-help.com>

## SEE ALSO

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