do_dialog(3alleg4)

💖 NAME 💖

okay so bestie, gather round — this is do_dialog, the basic dialog manager function from the Allegro game programming library. 🎀 (yes she's in section 3alleg4 of the Allegro manual, iykyk 💅)

✨ SYNOPSIS ✨

#include <allegro.h>

int do_dialog(DIALOG *dialog, int focus_obj);

like. that's the whole vibe right there. two args. one int back. slay. 🦋

🌸 DESCRIPTION 🌸

So this is the basic dialog manager function, the main character of dialog managing fr fr. 👑

What it does: it displays a dialog. And what's a dialog, you ask? It's an array of dialog objects, and that array is terminated by one with a NULL dialog procedure — that's your little end-of-the-line signal, don't forget it or she'll keep reading past the end, and we do not want that 💀.

It also sets the input focus to the focus_obj. And here's the tea: pass -1 if you don't want anything to have the focus. Nothing. No focus. Free range. Unbothered. ✨

Then it just... interprets user input and dispatches messages as they are required, over and over, like a little group chat that never sleeps, until one of the dialog procedures tells it to close the dialog. 🫶

And when that happens? It returns the index of the object that caused it to exit. 🎯

OR — plot twist — if ESC gets pressed, it returns -1. 😭 That's it. That's the escape hatch. Literally.

bestie pls note: those are the two exits, the object index or -1, and there is no third one, so plan accordingly 🙈

🌈 SEE ALSO 🌈

go read these next, they're all in her little friend group: 💜

• popup_dialog(3alleg4)
• init_dialog(3alleg4)
• centre_dialog(3alleg4)
• set_dialog_color(3alleg4)
• find_dialog_focus(3alleg4)
• excustom(3alleg4)
• exgui(3alleg4)
• exrgbhsv(3alleg4)

and that's the whole page, bestie!! this one came from the Allegro manual, version 4.4.3, and the page itself is dated do_dialog(3alleg4) — go forth and manage those dialogs, you absolute icon, periodt 💅✨🎀