SDL_DialogFileCallback(3type)

💖 SDL_DialogFileCallback — bestie edition 💖

okay so this is a SDL3 DATATYPES page, and it's literally all about SDL_DialogFileCallback, the callback that file dialog functions call back to. yes the name is a mouthful. we love her anyway. 🎀

---

✨ NAME ✨

SDL_DialogFileCallback — the callback used by file dialog functions. that's it, that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_dialog.h>

typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter);

look at her. iconic signature. no notes. 👑

---

🦋 DESCRIPTION 🦋

so the specific usage is described in each function — this page is just the general tea. but here's the important part, and bestie, you're gonna wanna pay attention because filelist can mean three completely different things and that's the whole plot twist: 😭

• if filelist is NULL, an error occurred. you can get the details with SDL_GetError().
• if filelist is a pointer to NULL, the user either didn't choose any file or canceled the dialog. no file for you. 💀
• if filelist is a pointer to non-NULL, the user chose one or more files! slay! the argument is a null-terminated array of pointers to UTF-8 encoded strings, and each one contains a path. 🫶

⚠️ do NOT free the filelist argument. like, don't. it gets automatically freed when the callback returns. it's not yours, it's on loan. hands off. 🙈

the filter argument is the index of the filter that was selected, or -1 if no filter was selected, or if the platform or method doesn't support fetching the selected filter. so -1 is basically the "idk bestie" value. 😌

now, Android section, because Android is always doing something extra: in Android, the filelist are content:// URIs. they should be opened using SDL_IOFromFile() with appropriate modes. and this applies both to open and save file dialogs. so don't forget it. ✨

---

🧚 FUNCTION PARAMETERS 🧚

• userdata — an app-provided pointer, for the callback's use. it's your little bag of stuff you get to bring along. 🎀
• filelist — the file(s) chosen by the user. the main character of this whole page, honestly. 💖
• filter — index of the selected filter. yes, just the index. the number. that's it. 🌸

---

🌈 AVAILABILITY 🌈

this datatype is available since SDL 3.2.0. so if you're on anything older... bestie. upgrade. 💅

---

👑 SEE ALSO 👑

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

the whole friend group. go read them next, iykyk. 🦋

---

okay that's the page!! brought to you by Simple Directmedia Layer, version SDL 3.4.18, and this little SDL_DialogFileCallback(3type) moment. mwah. stay hydrated, read your docs, and never free that filelist. 💜✨🔥