.\" Automatically generated by Pandoc 3.6.1
.\"
.TH "al_do_multiline_text" "3" "" "Allegro reference manual"
.SH NAME
al_do_multiline_text \- Allegro 5 API
.SH SYNOPSIS
.IP
.EX
#include \f[B]<allegro5/allegro_font.h>\f[R]

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)
.EE
.SH DESCRIPTION
This function processes the \f[CR]text\f[R] and splits it into lines as
al_draw_multiline_text(3) would, and then calls the callback
\f[CR]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(3) for an explanation of
the splitting algorithm.
.PP
For every line that this function splits \f[CR]text\f[R] into the
callback \f[CR]cb\f[R] will be called once with the following
parameters:
.IP \[bu] 2
\f[CR]line_num\f[R] \- the number of the line starting from zero and
counting up
.IP \[bu] 2
\f[CR]line\f[R] \- a pointer to the beginning character of the line (see
below)
.IP \[bu] 2
\f[CR]size\f[R] \- the size of the line (0 for empty lines)
.IP \[bu] 2
\f[CR]extra\f[R] \- the same pointer that was passed to
al_do_multiline_text
.PP
Note that \f[CR]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[CR]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[CR]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[CR]line\f[R] after \f[CR]cb\f[R] has returned, as \f[CR]line\f[R] is
\f[I]not\f[R] guaranteed to be valid after that.
.PP
If the callback \f[CR]cb\f[R] returns false, al_do_multiline_text will
stop immediately, otherwise it will continue on to the next line.
.SH SINCE
5.1.9
.SH SEE ALSO
al_draw_multiline_text(3)