al_show_native_message_box(3alleg5)

💖 al_show_native_message_box 💖

okay bestie, so this one is literally from the Allegro 5 API and it's giving "pop up a real, actual, native GUI message box" energy and honestly? iconic. ✨

---

🌸 NAME 🌸

al_show_native_message_box — the Allegro 5 API function that pops a native message box at the user like "hey. read this. 🫶"

---

🦋 SYNOPSIS 🦋

#include <allegro5/allegro_native_dialog.h>

int al_show_native_message_box(ALLEGRO_DISPLAY *display,
   char const *title, char const *heading, char const *text,
   char const *buttons, int flags)

---

✨ DESCRIPTION ✨

So like, this shows a native GUI message box. It's the real deal, the operating system's own dialog, not some fake little in-game rectangle. 💅

You'd use it for stuff like showing an error message if creating your initial display fails. And here's the cute part: the display can be NULL, but if you do pass one, that display gets treated as the parent if possible. 🍼

By default the message box has a single "OK" button and rocks the style that informative dialog boxes usually have on the native system. Very demure, very mindful. But if the buttons parameter is not NULL, you can instead write the button text yourself in a string, with the buttons separated by a vertical bar (|). slay. 🎀

Note: the buttons parameter is currently unimplemented on Windows. 😭 Not me finding out the hard way. It's just not there yet, bestie.

The flags you can use are:

• ALLEGRO_MESSAGEBOX_WARN — the message is a warning. This may cause a different icon (or other effects). ⚠️
• ALLEGRO_MESSAGEBOX_ERROR — the message is an error. 💀
• ALLEGRO_MESSAGEBOX_QUESTION — the message is a question. 🤔
• ALLEGRO_MESSAGEBOX_OK_CANCEL — display a cancel button alongside the "OK" button. Ignored if buttons is not NULL.
• ALLEGRO_MESSAGEBOX_YES_NO — display Yes/No buttons instead of the "OK" button. Ignored if buttons is not NULL.

And the wildest part: al_show_native_message_box(3alleg5) may be called without Allegro being installed. Not me being able to yell for help before Allegro even wakes up 😭 — this is useful to report an error during initialisation of Allegro itself. Periodt.

---

👑 Returns 👑

• 0 if the dialog window was closed without activating a button.
• 1 if the OK or Yes button was pressed.
• 2 if the Cancel or No button was pressed.

If buttons is not NULL, the number of the pressed button is returned, starting with 1.

All of the remaining parameters must not be NULL. fr fr, don't test it. 🙈

If a message box could not be created then this returns 0, as if the window was dismissed without activating a button. So 0 is doing double duty, iykyk. 💜

---

🌈 Example 🌈

int button = al_show_native_message_box(
  display,
  "Warning",
  "Are you sure?",
  "If you click yes then you are confirming that \"Yes\" "
  "is your response to the query which you have "
  "generated by the action you took to open this "
  "message box.",
  NULL,
  ALLEGRO_MESSAGEBOX_YES_NO
);

---

okay that's the whole vibe. go forth and pop your message boxes, bestie. main character energy only. 💅✨

---

signing off with love — this was the Allegro reference manual's take on `al_show_native_message_box(3alleg5)**, straight from the source, no cap. 🎀🦋🌸