SDL_ShowSaveFileDialog(3)

💾 SDL_ShowSaveFileDialog ✨

okay bestie, welcome to the SDL_ShowSaveFileDialog(3) page, part of the SDL3 FUNCTIONS lineup 🎀 she's a lil function in the SDL 3 world and she's here to pop open a save-file dialog for you 💅

---

🌸 NAME 🌸

SDL_ShowSaveFileDialog — pops up a dialog so your user can pick a new or existing file on their filesystem 🗂️✨ like "where do you wanna put this, queen?"

---

📜 SYNOPSIS 📜

#include <SDL3/SDL_dialog.h>

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

she takes six arguments and returns void, no cap 🫶

---

🦋 DESCRIPTION 🦋

first thing, and this is important: this is an asynchronous function. she returns immediately — like, she does not wait around for your user to make up their mind 😌 the actual result gets handed off to the callback.

so when the callback gets invoked, it receives a null-terminated list of the files the user chose 📝 here's the vibe check on that list:

• the list will be empty if the user canceled the dialog 🙈
• the list will be NULL if an error occurred 😭

not me warning you about this: the callback may be called from a different thread than the one the function was invoked on 💀 keep that in mind, bestie.

also, the chosen file may or may not already exist — she's flexible like that, she doesn't gatekeep 👑

and a Linux-specific note for my portal girlies 🐧 on Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. if your app doesn't use SDL to handle events, you should add a call to SDL_PumpEvents in your main loop. periodt. 💅

---

🎀 FUNCTION PARAMETERS 🎀

• callback — a function pointer that gets invoked when the user selects a file and accepts, or cancels the dialog, or when an error occurs 🫶
• userdata — an optional pointer you can pass extra data through to the callback when it gets invoked ✨
• window — the window that the dialog should be modal for. it may be NULL. heads up tho: not all platforms support this option 🙈
• filters — a list of filters, may be NULL. again, not all platforms support this option, and even the platforms that do support it may let the user just... ignore the filters 😭 if it's non-NULL, it must remain valid at least until the callback is invoked — don't let it die early bestie, she's holding onto it 💀
• nfilters — the number of filters. ignored if filters is NULL 👀
• default_location — the default folder or file to start the dialog at, may be NULL. and yep, you guessed it: not all platforms support this option 🌸

---

🧵 THREAD SAFETY 🧵

call this function only from the main thread, no exceptions, that's the rule 📏 the callback, though? she may be invoked from the same thread or from a different one, depending on the OS's constraints. main character energy with a lil unpredictability 💅✨

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0 🎉 she's not ancient, she's fresh.

---

👀 SEE ALSO 👀

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

go read those too, iykyk 💖

---

and that's the whole page, bestie!! this was brought to you by Simple Directmedia Layer, rocking SDL 3.4.18 🦋 now go save some files, slay, and remember: the callback might be on another thread, so stay safe out there 💜🌸✨