SDL 3.0
SDL_dialog.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryDialog
24 *
25 * File dialog support.
26 *
27 * SDL offers file dialogs, to let users select files with native GUI
28 * interfaces. There are "open" dialogs, "save" dialogs, and folder selection
29 * dialogs. The app can control some details, such as filtering to specific
30 * files, or whether multiple files can be selected by the user.
31 *
32 * Note that launching a file dialog is a non-blocking operation; control
33 * returns to the app immediately, and a callback is called later (possibly in
34 * another thread) when the user makes a choice.
35 */
36
37#ifndef SDL_dialog_h_
38#define SDL_dialog_h_
39
40#include <SDL3/SDL_stdinc.h>
41#include <SDL3/SDL_error.h>
42#include <SDL3/SDL_properties.h>
43#include <SDL3/SDL_video.h>
44
45#include <SDL3/SDL_begin_code.h>
46/* Set up for C function definitions, even when using C++ */
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/**
52 * An entry for filters for file dialogs.
53 *
54 * `name` is a user-readable label for the filter (for example, "Office
55 * document").
56 *
57 * `pattern` is a semicolon-separated list of file extensions (for example,
58 * "doc;docx"). File extensions may only contain alphanumeric characters,
59 * hyphens, underscores and periods. Alternatively, the whole string can be a
60 * single asterisk ("*"), which serves as an "All files" filter.
61 *
62 * \since This struct is available since SDL 3.1.3.
63 *
64 * \sa SDL_DialogFileCallback
65 * \sa SDL_ShowOpenFileDialog
66 * \sa SDL_ShowSaveFileDialog
67 * \sa SDL_ShowOpenFolderDialog
68 * \sa SDL_ShowFileDialogWithProperties
69 */
71{
72 const char *name;
73 const char *pattern;
75
76/**
77 * Callback used by file dialog functions.
78 *
79 * The specific usage is described in each function.
80 *
81 * If `filelist` is:
82 *
83 * - NULL, an error occurred. Details can be obtained with SDL_GetError().
84 * - A pointer to NULL, the user either didn't choose any file or canceled the
85 * dialog.
86 * - A pointer to non-`NULL`, the user chose one or more files. The argument
87 * is a null-terminated list of pointers to C strings, each containing a
88 * path.
89 *
90 * The filelist argument should not be freed; it will automatically be freed
91 * when the callback returns.
92 *
93 * The filter argument is the index of the filter that was selected, or -1 if
94 * no filter was selected or if the platform or method doesn't support
95 * fetching the selected filter.
96 *
97 * \param userdata an app-provided pointer, for the callback's use.
98 * \param filelist the file(s) chosen by the user.
99 * \param filter index of the selected filter.
100 *
101 * \since This datatype is available since SDL 3.1.3.
102 *
103 * \sa SDL_DialogFileFilter
104 * \sa SDL_ShowOpenFileDialog
105 * \sa SDL_ShowSaveFileDialog
106 * \sa SDL_ShowOpenFolderDialog
107 * \sa SDL_ShowFileDialogWithProperties
108 */
109typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter);
110
111/**
112 * Displays a dialog that lets the user select a file on their filesystem.
113 *
114 * This is an asynchronous function; it will return immediately, and the
115 * result will be passed to the callback.
116 *
117 * The callback will be invoked with a null-terminated list of files the user
118 * chose. The list will be empty if the user canceled the dialog, and it will
119 * be NULL if an error occurred.
120 *
121 * Note that the callback may be called from a different thread than the one
122 * the function was invoked on.
123 *
124 * Depending on the platform, the user may be allowed to input paths that
125 * don't yet exist.
126 *
127 * On Linux, dialogs may require XDG Portals, which requires DBus, which
128 * requires an event-handling loop. Apps that do not use SDL to handle events
129 * should add a call to SDL_PumpEvents in their main loop.
130 *
131 * \param callback a function pointer to be invoked when the user selects a
132 * file and accepts, or cancels the dialog, or an error
133 * occurs.
134 * \param userdata an optional pointer to pass extra data to the callback when
135 * it will be invoked.
136 * \param window the window that the dialog should be modal for, may be NULL.
137 * Not all platforms support this option.
138 * \param filters a list of filters, may be NULL. Not all platforms support
139 * this option, and platforms that do support it may allow the
140 * user to ignore the filters. If non-NULL, it must remain
141 * valid at least until the callback is invoked.
142 * \param nfilters the number of filters. Ignored if filters is NULL.
143 * \param default_location the default folder or file to start the dialog at,
144 * may be NULL. Not all platforms support this option.
145 * \param allow_many if non-zero, the user will be allowed to select multiple
146 * entries. Not all platforms support this option.
147 *
148 * \threadsafety This function should be called only from the main thread. The
149 * callback may be invoked from the same thread or from a
150 * different one, depending on the OS's constraints.
151 *
152 * \since This function is available since SDL 3.1.3.
153 *
154 * \sa SDL_DialogFileCallback
155 * \sa SDL_DialogFileFilter
156 * \sa SDL_ShowSaveFileDialog
157 * \sa SDL_ShowOpenFolderDialog
158 * \sa SDL_ShowFileDialogWithProperties
159 */
160extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many);
161
162/**
163 * Displays a dialog that lets the user choose a new or existing file on their
164 * filesystem.
165 *
166 * This is an asynchronous function; it will return immediately, and the
167 * result will be passed to the callback.
168 *
169 * The callback will be invoked with a null-terminated list of files the user
170 * chose. The list will be empty if the user canceled the dialog, and it will
171 * be NULL if an error occurred.
172 *
173 * Note that the callback may be called from a different thread than the one
174 * the function was invoked on.
175 *
176 * The chosen file may or may not already exist.
177 *
178 * On Linux, dialogs may require XDG Portals, which requires DBus, which
179 * requires an event-handling loop. Apps that do not use SDL to handle events
180 * should add a call to SDL_PumpEvents in their main loop.
181 *
182 * \param callback a function pointer to be invoked when the user selects a
183 * file and accepts, or cancels the dialog, or an error
184 * occurs.
185 * \param userdata an optional pointer to pass extra data to the callback when
186 * it will be invoked.
187 * \param window the window that the dialog should be modal for, may be NULL.
188 * Not all platforms support this option.
189 * \param filters a list of filters, may be NULL. Not all platforms support
190 * this option, and platforms that do support it may allow the
191 * user to ignore the filters. If non-NULL, it must remain
192 * valid at least until the callback is invoked.
193 * \param nfilters the number of filters. Ignored if filters is NULL.
194 * \param default_location the default folder or file to start the dialog at,
195 * may be NULL. Not all platforms support this option.
196 *
197 * \threadsafety This function should be called only from the main thread. The
198 * callback may be invoked from the same thread or from a
199 * different one, depending on the OS's constraints.
200 *
201 * \since This function is available since SDL 3.1.3.
202 *
203 * \sa SDL_DialogFileCallback
204 * \sa SDL_DialogFileFilter
205 * \sa SDL_ShowOpenFileDialog
206 * \sa SDL_ShowOpenFolderDialog
207 * \sa SDL_ShowFileDialogWithProperties
208 */
209extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location);
210
211/**
212 * Displays a dialog that lets the user select a folder on their filesystem.
213 *
214 * This is an asynchronous function; it will return immediately, and the
215 * result will be passed to the callback.
216 *
217 * The callback will be invoked with a null-terminated list of files the user
218 * chose. The list will be empty if the user canceled the dialog, and it will
219 * be NULL if an error occurred.
220 *
221 * Note that the callback may be called from a different thread than the one
222 * the function was invoked on.
223 *
224 * Depending on the platform, the user may be allowed to input paths that
225 * don't yet exist.
226 *
227 * On Linux, dialogs may require XDG Portals, which requires DBus, which
228 * requires an event-handling loop. Apps that do not use SDL to handle events
229 * should add a call to SDL_PumpEvents in their main loop.
230 *
231 * \param callback a function pointer to be invoked when the user selects a
232 * file and accepts, or cancels the dialog, or an error
233 * occurs.
234 * \param userdata an optional pointer to pass extra data to the callback when
235 * it will be invoked.
236 * \param window the window that the dialog should be modal for, may be NULL.
237 * Not all platforms support this option.
238 * \param default_location the default folder or file to start the dialog at,
239 * may be NULL. Not all platforms support this option.
240 * \param allow_many if non-zero, the user will be allowed to select multiple
241 * entries. Not all platforms support this option.
242 *
243 * \threadsafety This function should be called only from the main thread. The
244 * callback may be invoked from the same thread or from a
245 * different one, depending on the OS's constraints.
246 *
247 * \since This function is available since SDL 3.1.3.
248 *
249 * \sa SDL_DialogFileCallback
250 * \sa SDL_ShowOpenFileDialog
251 * \sa SDL_ShowSaveFileDialog
252 * \sa SDL_ShowFileDialogWithProperties
253 */
254extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many);
255
256/**
257 * Various types of file dialogs.
258 *
259 * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of
260 * dialog to present to the user.
261 *
262 * \since This enum is available since SDL 3.1.3.
263 *
264 * \sa SDL_ShowFileDialogWithProperties
265 */
272
273/**
274 * Create and launch a file dialog with the specified properties.
275 *
276 * These are the supported properties:
277 *
278 * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of
279 * SDL_DialogFileFilter structs, which will be used as filters for
280 * file-based selections. Ignored if the dialog is an "Open Folder" dialog.
281 * If non-NULL, the array of filters must remain valid at least until the
282 * callback is invoked.
283 * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the
284 * array of filters, if it exists.
285 * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should
286 * be modal for.
287 * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to
288 * start the dialog at.
289 * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select
290 * more than one entry.
291 * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog.
292 * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button
293 * should have.
294 * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button
295 * should have.
296 *
297 * Note that each platform may or may not support any of the properties.
298 *
299 * \param type the type of file dialog.
300 * \param callback a function pointer to be invoked when the user selects a
301 * file and accepts, or cancels the dialog, or an error
302 * occurs.
303 * \param userdata an optional pointer to pass extra data to the callback when
304 * it will be invoked.
305 * \param props the properties to use.
306 *
307 * \threadsafety This function should be called only from the main thread. The
308 * callback may be invoked from the same thread or from a
309 * different one, depending on the OS's constraints.
310 *
311 * \since This function is available since SDL 3.2.0.
312 *
313 * \sa SDL_FileDialogType
314 * \sa SDL_DialogFileCallback
315 * \sa SDL_DialogFileFilter
316 * \sa SDL_ShowOpenFileDialog
317 * \sa SDL_ShowSaveFileDialog
318 * \sa SDL_ShowOpenFolderDialog
319 */
320extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props);
321
322#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters"
323#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters"
324#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window"
325#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location"
326#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many"
327#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title"
328#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept"
329#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel"
330
331/* Ends C function definitions when using C++ */
332#ifdef __cplusplus
333}
334#endif
335#include <SDL3/SDL_close_code.h>
336
337#endif /* SDL_dialog_h_ */
void SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location)
void(* SDL_DialogFileCallback)(void *userdata, const char *const *filelist, int filter)
Definition SDL_dialog.h:109
void SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many)
SDL_FileDialogType
Definition SDL_dialog.h:267
@ SDL_FILEDIALOG_SAVEFILE
Definition SDL_dialog.h:269
@ SDL_FILEDIALOG_OPENFILE
Definition SDL_dialog.h:268
@ SDL_FILEDIALOG_OPENFOLDER
Definition SDL_dialog.h:270
void SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many)
void SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props)
Uint32 SDL_PropertiesID
struct SDL_Window SDL_Window
Definition SDL_video.h:165
const char * name
Definition SDL_dialog.h:72
const char * pattern
Definition SDL_dialog.h:73