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

void al_draw_multiline_text(const ALLEGRO_FONT *font,
     ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
     int flags, const char *text)
.EE
.SH DESCRIPTION
Like al_draw_text(3), but this function supports drawing multiple lines
of text.
It will break \f[CR]text\f[R] in lines based on its contents and the
\f[CR]max_width\f[R] parameter.
The lines are then layed out vertically depending on the
\f[CR]line_height\f[R] parameter and drawn each as if al_draw_text(3)
was called on them.
.PP
A newline \f[CR]\[rs]n\f[R] in the \f[CR]text\f[R] will cause a
\[lq]hard\[rq] line break after its occurrence in the string.
The text after a hard break is placed on a new line.
Carriage return \f[CR]\[rs]r\f[R] is not supported, will not cause a
line break, and will likely be drawn as a square or a space depending on
the font.
.PP
The \f[CR]max_width\f[R] parameter controls the maximum desired width of
the lines.
This function will try to introduce a \[lq]soft\[rq] line break after
the longest possible series of words that will fit in
\f[CR]max_length\f[R] when drawn with the given \f[CR]font\f[R].
A \[lq]soft\[rq] line break can occur either on a space or tab
(\f[CR]\[rs]t\f[R]) character.
.PP
However, it is possible that \f[CR]max_width\f[R] is too small, or the
words in \f[CR]text\f[R] are too long to fit \f[CR]max_width\f[R] when
drawn with \f[CR]font\f[R].
In that case, the word that is too wide will simply be drawn completely
on a line by itself.
If you don\[cq]t want the text that overflows \f[CR]max_width\f[R] to be
visible, then use al_set_clipping_rectangle(3) to clip it off and hide
it.
.PP
The lines \f[CR]text\f[R] was split into will each be drawn using the
\f[CR]font\f[R], \f[CR]x\f[R], \f[CR]color\f[R] and \f[CR]flags\f[R]
parameters, vertically starting at \f[CR]y\f[R] and with a distance of
\f[CR]line_height\f[R] between them.
If \f[CR]line_height\f[R] is zero (\f[CR]0\f[R]), the value returned by
calling al_get_font_line_height(3) on \f[CR]font\f[R] will be used as a
default instead.
.PP
The \f[CR]flags\f[R] ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE,
ALLEGRO_ALIGN_RIGHT and ALLEGRO_ALIGN_INTEGER will be honoured by this
function.
.PP
If you want to calculate the size of what this function will draw
without actually drawing it, or if you need a complex and/or custom
layout, you can use al_do_multiline_text(3).
.SH SINCE
5.1.9
.SH SEE ALSO
al_do_multiline_text(3), al_draw_multiline_ustr(3),
al_draw_multiline_textf(3)