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