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
|
.TH "al_do_multiline_text" "3" "" "Allegro reference manual" ""
.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[]
.fi
.SH DESCRIPTION
.PP
This function processes the \f[C]text\f[] and splits it into lines as
al_draw_multiline_text(3) would, and then calls the callback \f[C]cb\f[]
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[C]text\f[] into the callback
\f[C]cb\f[] will be called once with the following parameters:
.IP \[bu] 2
\f[C]line_num\f[] \- the number of the line starting from zero and
counting up
.IP \[bu] 2
\f[C]line\f[] \- a pointer to the beginning character of the line (see
below)
.IP \[bu] 2
\f[C]size\f[] \- the size of the line (0 for empty lines)
.IP \[bu] 2
\f[C]extra\f[] \- the same pointer that was passed to
al_do_multiline_text
.PP
Note that \f[C]line\f[] is \f[I]not\f[] guaranteed to be a
NUL\-terminated string, but will merely point to a character within
\f[C]text\f[] or to an empty string in case of an empty line.
If you need a NUL\-terminated string, you will have to copy
\f[C]line\f[] to a buffer and NUL\-terminate it yourself.
You will also have to make your own copy if you need the contents of
\f[C]line\f[] after \f[C]cb\f[] has returned, as \f[C]line\f[] is
\f[I]not\f[] guaranteed to be valid after that.
.PP
If the callback \f[C]cb\f[] 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)
|
