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

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)
\f[]
.fi
.SH DESCRIPTION
.PP
Like al_draw_text(3alleg5), but this function supports drawing multiple
lines of text.
It will break \f[C]text\f[] in lines based on its contents and the
\f[C]max_width\f[] parameter.
The lines are then layed out vertically depending on the
\f[C]line_height\f[] parameter and drawn each as if
al_draw_text(3alleg5) was called on them.
.PP
A newline \f[C]\\n\f[] in the \f[C]text\f[] 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[C]\\r\f[] 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[C]max_width\f[] 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[C]max_length\f[] when drawn with the given \f[C]font\f[].
A \[lq]soft\[rq] line break can occur either on a space or tab
(\f[C]\\t\f[]) character.
.PP
However, it is possible that \f[C]max_width\f[] is too small, or the
words in \f[C]text\f[] are too long to fit \f[C]max_width\f[] when drawn
with \f[C]font\f[].
In that case, the word that is too wide will simply be drawn completely
on a line by itself.
If you don't want the text that overflows \f[C]max_width\f[] to be
visible, then use al_set_clipping_rectangle(3alleg5) to clip it off and
hide it.
.PP
The lines \f[C]text\f[] was split into will each be drawn using the
\f[C]font\f[], \f[C]x\f[], \f[C]color\f[] and \f[C]flags\f[] parameters,
vertically starting at \f[C]y\f[] and with a distance of
\f[C]line_height\f[] between them.
If \f[C]line_height\f[] is zero (\f[C]0\f[]), the value returned by
calling al_get_font_line_height(3alleg5) on \f[C]font\f[] will be used
as a default instead.
.PP
The \f[C]flags\f[] 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(3alleg5).
.SH SINCE
.PP
5.1.9
.SH SEE ALSO
.PP
al_do_multiline_text(3alleg5), al_draw_multiline_text(3alleg5),
al_draw_multiline_textf(3alleg5)