1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
.TH "al_draw_multiline_text" "3" "" "Allegro reference manual" ""
.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(3), 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(3) was
called on them.
.PP
A newline \f[C]\\n\f[] in the \f[C]text\f[] will cause a "hard" 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 "soft" 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 "soft" 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\[aq]t want the text that overflows \f[C]max_width\f[] to be
visible, then use al_set_clipping_rectangle(3) 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(3) 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(3).
.SH SINCE
.PP
5.1.9
.SH SEE ALSO
.PP
al_do_multiline_text(3), al_draw_multiline_text(3),
al_draw_multiline_textf(3)
|
