al_do_multiline_text(3alleg5)

💖 al_do_multiline_text — Allegro 5 API 💖

okay bestie, pull up a chair, we're in the 3alleg5 section of the Allegro reference manual and this one is so useful it's not even funny ✨

---

🌸 SYNOPSIS 🌸

#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)

---

🦋 DESCRIPTION 🦋

so basically, this function takes your text, does the whole line-splitting thing exactly the way al_draw_multiline_text(3alleg5) would do it, and then calls your callback cb once for every single line. no cap. one line, one callback, every time 💅

it's giving custom drawing of multiline text, and it's also giving calculating the size of multiline text ahead of time — both iconic uses, both valid. if you wanna know how the splitting algorithm actually works, go read the docs on al_draw_multiline_text(3alleg5), because that's where the explanation lives 🫶

---

🎀 the callback parameters (aka the tea) 🎀

for every line that this function splits text into, the callback cb gets called once with these cuties:

• line_num — the number of the line, starting from zero and counting up ⬆️
• line — a pointer to the beginning character of the line (more on this below, don't skip it 👀)
• size — the size of the line (0 for empty lines)
• extra — the exact same pointer that was passed to al_do_multiline_text

---

😭 the line pointer warning (read this, fr fr) 😭

not me about to save you from a segfault. line is NOT guaranteed to be a NUL-terminated string. it just points to a character inside text, or to an empty string if the line is empty. that's it. that's all you get.

so if you need a NUL-terminated string, you're gonna have to copy line into a buffer and NUL-terminate it yourself. no one's doing it for you bestie 💀

and listen — if you need the contents of line after cb has returned, you also have to make your own copy, because line is not guaranteed to be valid after that. it's giving expired. it's giving use-after-free waiting to happen. so copy it or lose it 🙈

---

🔥 the return value behaviour 🔥

• if your callback cb returns false, al_do_multiline_text stops immediately 🛑
• otherwise, it keeps going on to the next line, and the next, and the next ⭐

that's your early-exit button. use it with intention, queen 👑

---

⭐ SINCE ⭐

5.1.9

---

🌈 SEE ALSO 🌈

• al_draw_multiline_text(3alleg5)

---

okay that's the whole page, you absolutely ate this one 🫶 go forth and split some lines responsibly. this was al_do_multiline_text(3alleg5) straight outta the Allegro reference manual — mwah, catch you in the next one 💖✨🎀