.\" Automatically generated by Pandoc 3.1.6.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "al_do_multiline_text" "3" "" "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[V]text\f[R] and splits it into lines as
al_draw_multiline_text(3) would, and then calls the callback
\f[V]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[V]text\f[R] into the
callback \f[V]cb\f[R] will be called once with the following parameters:
.IP \[bu] 2
\f[V]line_num\f[R] - the number of the line starting from zero and
counting up
.IP \[bu] 2
\f[V]line\f[R] - a pointer to the beginning character of the line (see
below)
.IP \[bu] 2
\f[V]size\f[R] - the size of the line (0 for empty lines)
.IP \[bu] 2
\f[V]extra\f[R] - the same pointer that was passed to
al_do_multiline_text
.PP
Note that \f[V]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[V]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[V]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[V]line\f[R] after \f[V]cb\f[R] has returned, as \f[V]line\f[R] is
\f[I]not\f[R] guaranteed to be valid after that.
.PP
If the callback \f[V]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(3)