al_create_native_file_dialog(3alleg5)

💖 al_create_native_file_dialog — Allegro 5 API 💖

okay bestie, welcome to the Allegro reference manual, and today we're doing al_create_native_file_dialog — the function that literally pops up a real, native, operating-system-blessed file picker for you. iconic behaviour, no cap. ✨

---

🌸 NAME 🌸

al_create_native_file_dialog — Allegro 5 API

---

🦋 SYNOPSIS 🦋

#include <allegro5/allegro_native_dialog.h>

ALLEGRO_FILECHOOSER *al_create_native_file_dialog(
   char const *initial_path,
   char const *title,
   char const *patterns,
   int mode)

---

✨ DESCRIPTION ✨

It makes you a brand new native file dialog, bestie. and listen — you should only have one such dialog opened at a time. one. single. dialog. don't be greedy, it's not the vibe. 💅

Parameters — the group chat lineup:

• initial_path — the starting search path and filename. this one can be NULL. 🫶 if you want it to start with a blank file name, your string should end with a directory separator — and that's actually the common case, so don't overthink it.
• title — the title of the dialog. the little name tag. the main character energy on the window bar. 👑
• patterns — a string of newline-separated sets of patterns to match. a pattern is either a shell-style glob pattern (like "*.txt") or a MIME type (like "image/png"). and here's the tea: not all platforms support both, and some don't even support globs at all 😭, so the portable move is to give a MIME type and simple-style globs, and let Allegro pick whichever one the platform actually supports (so like, do "image/png;*.png"). multiple patterns get separated with a semicolon. if the platform doesn't support patterns at all, this parameter is just ignored. shrug, we move on. 💁

here's some example patterns so you can see the vision:

• "*.txt" — defines a single filter, matching *.txt files.
• "*.txt;*.md" — like above, but matching two types of files.
• "Text files (*.txt, *.md) *.txt;*.md" — like above, but with a custom description (separated from the patterns using a space).
• "Text files *.txt\nPNG images image/png;*.png" — defines two filters, with the second filter using a MIME type and extension at the same time.

🚨 note time, and this one matters: Windows does not support MIME types. Android supports only MIME types. and MacOS supports extensions instead of file patterns, so matching based on filename beyond file type does not work there — Allegro will parse your file pattern to try to extract the file extension. MacOS also supports MIME types though, which behave more predictably. also MacOS does not support detailed descriptions or multiple pattern sets, so Allegro will strip the detailed descriptions and concatenate all patterns into one list. it's giving chaos but it's fine, Allegro handles it. 🧚

• mode — 0, or a combination of the following flags:
  • ALLEGRO_FILECHOOSER_FILE_MUST_EXIST — if the native dialog supports it, it won't let you enter new names, it'll just let existing files be selected. else it is ignored.
  • ALLEGRO_FILECHOOSER_SAVE — if the native dialog system has a different dialog for saving (for example one which allows creating new directories), it gets used. else it is ignored.
  • ALLEGRO_FILECHOOSER_FOLDER — if there's support for a separate dialog to select a folder instead of a file, it will be used.
  • ALLEGRO_FILECHOOSER_PICTURES — if a different dialog is available for selecting pictures, it gets used. else it is ignored.
  • ALLEGRO_FILECHOOSER_SHOW_HIDDEN — if the platform supports it, hidden files will be shown too. peek behind the curtain 🫣
  • ALLEGRO_FILECHOOSER_MULTIPLE — if supported, it lets you select multiple files. slay. 🔥

Returns:

a handle to the dialog 💖 — you pass it to al_show_native_file_dialog(3alleg5) to actually display it, and then you can query the results using al_get_native_file_dialog_count(3alleg5) and al_get_native_file_dialog_path(3alleg5). and when you're done? call al_destroy_native_file_dialog(3alleg5) on it. clean up after yourself, bestie, it's the respectful thing. 🌈

and if a dialog window could not be created, this function returns NULL. 😭 it happens. it's not your fault.

---

and that's the whole page, fr fr. this has been the Allegro reference manual serving you al_create_native_file_dialog(3alleg5) — go forth, open a file picker, be the main character of your own desktop app 🎀🦋✨