SDL_ShowOpenFileDialog(3)

💖 SDL_ShowOpenFileDialog 💖

okay bestie, welcome to SDL_ShowOpenFileDialog(3) — a lil function from the SDL3 crew that pops open a file picker so your user can go grab a file off their own filesystem. it's giving "choose your own adventure" but the adventure is a filesystem. let's get into it 🫶

---

✨ NAME ✨

SDL_ShowOpenFileDialog — pops a dialog that lets the user select a file on their filesystem. that's the whole vibe. 🌸

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_dialog.h>

void SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many);

---

✨ DESCRIPTION ✨

okay so first things first, this is an asynchronous function. meaning it returns immediately, like, right away, no waiting around. the actual result gets handed off to your callback later. main character behavior honestly. 💅

that callback gets invoked with a null-terminated list of files the user chose. and listen:

• if the user canceled the dialog, the list will be empty.
• if an error happened, the list will be NULL.

⚠️ also, heads up bestie: the callback may be called from a different thread than the one you invoked the function on. so don't be weird about it. 😭

depending on the platform, the user may be allowed to input paths that don't exist yet. no cap.

on Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. so if your app doesn't use SDL to handle events, you need to add a call to SDL_PumpEvents in your main loop. yes, fr fr, just do it. ✨

---

✨ FUNCTION PARAMETERS ✨

• callback — a function pointer that gets invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs. your moment to shine, king. 👑
• userdata — an optional pointer so you can pass extra data to the callback when it gets invoked. optional!! (say it with me)
• window — the window that the dialog should be modal for. may be NULL. not all platforms support this option, so don't get attached. 🙈
• filters — a list of filters, may be NULL. see the SDL_DialogFileFilter documentation for examples (it's got code examples and everything 💖). not all platforms support this option, and platforms that do support it may still let the user ignore the filters. rude, but okay. if it's non-NULL, it must remain valid at least until the callback is invoked — do not let it die early, that's a crime.
• nfilters — the number of filters. ignored if filters is NULL. it said what it said.
• default_location — the default folder or file to start the dialog at, may be NULL. not all platforms support this option.
• allow_many — if non-zero, the user will be allowed to select multiple entries. not all platforms support this option. multi-select girlies stay winning 🎀

---

✨ THREAD SAFETY ✨

this function should be called only from the main thread. periodt.

the callback though? it may be invoked from the same thread or from a different one, depending on the OS's constraints. so basically, it depends. classic. 🦋

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. iconic since day one. ⭐

---

✨ SEE ALSO ✨

• SDL_DialogFileCallback(3type)
• SDL_DialogFileFilter(3type)
• SDL_ShowSaveFileDialog(3)
• SDL_ShowOpenFolderDialog(3)
• SDL_ShowFileDialogWithProperties(3)

go read those too, bestie, iykyk. 🌈

---

k bye!! this has been your girl bringing you the good word from Simple Directmedia Layer, SDL 3.4.18 edition. stay asynchronous, stay slay. 💜🧚💖