al_do_multiline_text(3)

💖 al_do_multiline_text — the Allegro 5 API girlie's guide 💖

okay so bestie, welcome to the allegro_font.h cinematic universe ✨ this one lives in the Library Functions Manual, and honestly? it's giving "backend bestie who does all the work while al_draw_multiline_text gets the credit." 💅

---

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

look at that signature. gorgeous. no notes. 🎀

---

🌸 DESCRIPTION 🌸

so what this icon actually does: it takes your text, processes it, and splits it into lines exactly the way al_draw_multiline_text(3) would. then, for every single line it produced, it calls your callback cb once. one call per line. no cap. 🔥

why would you even want that? lowkey it's so useful:

• custom drawing of multiline text (your art, your rules 🎨)
• calculating the size of multiline text ahead of time (no more guessing, we love a planner 👑)

and if you wanna know the actual splitting algorithm? go read the docs on al_draw_multiline_text(3), because that's where the lore lives. iykyk 📖

---

🦋 the callback parameters 🦋

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

• line_num — the number of the line, starting from zero and counting up (yes, zero-indexed, we're programmers, bestie)
• line — a pointer to the beginning character of the line (see below 👇)
• size — the size of the line (0 for empty lines)
• extra — the same pointer that was passed to al_do_multiline_text

---

⚠️ the line lore (read this fr fr) ⚠️

okay this part is important and i need you to actually pay attention 💀

line is not guaranteed to be a NUL-terminated string. it merely points to a character within text, or to an empty string in the case of an empty line. so if you need a NUL-terminated string, you're gonna have to copy line to a buffer and NUL-terminate it yourself. your copy, your problem, your slay 💅

you will also have to make your own copy if you need the contents of line after cb has returned, because line is not guaranteed to be valid after that. like, it's gone. bye. don't touch it. 🙈

---

🫶 the return-value vibe check 🫶

if the callback cb returns false, al_do_multiline_text will stop immediately 🛑. otherwise it just keeps going on to the next line, living its best life 🌈

---

⭐ SINCE ⭐

5.1.9 — an elder, but a legendary one 👑

---

🌸 SEE ALSO 🌸

• al_draw_multiline_text(3) — the main character this one is lowkey supporting 🎬

---

and that's the whole page, bestie! 🎀 this little gem comes to you straight from the Allegro reference manual, dated with a 5.1.9 "since" tag and living under the al_do_multiline_text(3) header — go forth, split those lines, and remember: copy your buffers 💖✨🧚