.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "al_do_multiline_text" "3alleg5" "" "Allegro reference manual" ""
.hy
.SH NAME
.PP
al_do_multiline_text - Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <allegro5/allegro_font.h>

void al_do_multiline_text(const ALLEGRO_FONT *font,
   float max_width, const char *text,
   bool (*cb)(int line_num, const char *line, int size, void *extra),
   void *extra)
\f[R]
.fi
.SH DESCRIPTION
.PP
This function processes the \f[C]text\f[R] and splits it into lines as
al_draw_multiline_text(3alleg5) would, and then calls the callback
\f[C]cb\f[R] once for every line.
This is useful for custom drawing of multiline text, or for calculating
the size of multiline text ahead of time.
See the documentation on al_draw_multiline_text(3alleg5) for an
explanation of the splitting algorithm.
.PP
For every line that this function splits \f[C]text\f[R] into the
callback \f[C]cb\f[R] will be called once with the following parameters:
.IP \[bu] 2
\f[C]line_num\f[R] - the number of the line starting from zero and
counting up
.IP \[bu] 2
\f[C]line\f[R] - a pointer to the beginning character of the line (see
below)
.IP \[bu] 2
\f[C]size\f[R] - the size of the line (0 for empty lines)
.IP \[bu] 2
\f[C]extra\f[R] - the same pointer that was passed to
al_do_multiline_text
.PP
Note that \f[C]line\f[R] is \f[I]not\f[R] guaranteed to be a
NUL-terminated string, but will merely point to a character within
\f[C]text\f[R] or to an empty string in case of an empty line.
If you need a NUL-terminated string, you will have to copy
\f[C]line\f[R] to a buffer and NUL-terminate it yourself.
You will also have to make your own copy if you need the contents of
\f[C]line\f[R] after \f[C]cb\f[R] has returned, as \f[C]line\f[R] is
\f[I]not\f[R] guaranteed to be valid after that.
.PP
If the callback \f[C]cb\f[R] returns false, al_do_multiline_text will
stop immediately, otherwise it will continue on to the next line.
.SH SINCE
.PP
5.1.9
.SH SEE ALSO
.PP
al_draw_multiline_text(3alleg5)