---
name: "Imager::Font::Wrap"
section: "3pm"
platform: "linux"
package: "libimager-perl"
version: "1.027+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Imager::Font::Wrap"
---

# Imager::Font::Wrap(3pm)

## NAME

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

## SYNOPSIS

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

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

  ```
    ($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:

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