SDL_SHOWFILEDIALOGWITHPROPERTIES(3)

💖 SDL_ShowFileDialogWithProperties 💖

okay bestie, so this one is from the SDL3 FUNCTIONS manual, and it's literally the ✨fanciest✨ way to pop open a file dialog. It's giving "I have a whole properties system and I'm not afraid to use it." 💅

---

🌸 NAME 🌸

SDL_ShowFileDialogWithProperties — create and launch a file dialog with the specified properties.

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_dialog.h>

void SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props);

---

🦋 DESCRIPTION 🦋

okay so here's the tea: instead of passing a million args, you pass a props ID and set all your little wishes on it. These are the supported properties, no cap:

• SDL_PROP_FILE_DIALOG_FILTERS_POINTER — a pointer to a list of SDL_DialogFileFilter structs, and those are the filters used for file-based selections. Lowkey important: it gets ignored if the dialog is an "Open Folder" dialog. And if it's non-NULL, the array of filters has to stay valid at least until the callback is invoked. So don't let it die early, bestie 😭
• SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER — the number of filters in that array of filters, if it exists.
• SDL_PROP_FILE_DIALOG_WINDOW_POINTER — the window that the dialog should be modal for.
• SDL_PROP_FILE_DIALOG_LOCATION_STRING — the default folder or file to start the dialog at.
• SDL_PROP_FILE_DIALOG_MANY_BOOLEAN — true to allow the user to select more than one entry. (main character behavior fr fr)
• SDL_PROP_FILE_DIALOG_TITLE_STRING — the title for the dialog.
• SDL_PROP_FILE_DIALOG_ACCEPT_STRING — the label that the accept button should have.
• SDL_PROP_FILE_DIALOG_CANCEL_STRING — the label that the cancel button should have.

⚠️ note that each platform may or may not support any of the properties. so like... vibe check your platform first, okay? 🙈

---

🎀 FUNCTION PARAMETERS 🎀

• type — the type of file dialog.
• callback — a function pointer that gets invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs. it's the glow-up moment, basically 💫
• userdata — an optional pointer to pass extra data to the callback when it will be invoked. lil care package for your callback 🫶
• props — the properties to use.

---

💜 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 it's giving "wherever the OS decides," and you just have to deal 💀

---

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. so if you're on anything older, it's simply not gonna show up for you 😭

---

🌈 SEE ALSO 🌈

• SDL_FileDialogType(3type)
• SDL_DialogFileCallback(3type)
• SDL_DialogFileFilter(3type)
• SDL_ShowOpenFileDialog(3)
• SDL_ShowSaveFileDialog(3)
• SDL_ShowOpenFolderDialog(3)

---

okay that's the whole page, you ate it, you understood it, iconic behavior 💅✨

this has been your girl signing off on behalf of Simple Directmedia Layer, running SDL 3.4.18 — go make some dialogs pop off, bestie 🎀🦋💖