|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 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
|
|
|
48 extern "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.2.0.
|
|
|
63 *
|
|
|
64 * \sa SDL_DialogFileCallback
|
|
|
65 * \sa SDL_ShowOpenFileDialog
|
|
|
66 * \sa SDL_ShowSaveFileDialog
|
|
|
67 * \sa SDL_ShowOpenFolderDialog
|
|
|
68 * \sa SDL_ShowFileDialogWithProperties
|
|
|
69 */
|
|
|
70 typedef struct SDL_DialogFileFilter
|
|
|
71 {
|
|
|
72 const char *name;
|
|
|
73 const char *pattern;
|
|
|
74 } SDL_DialogFileFilter;
|
|
|
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 array of pointers to UTF-8 encoded strings, each
|
|
|
88 * containing a 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 * In Android, the `filelist` are `content://` URIs. They should be opened
|
|
|
98 * using SDL_IOFromFile() with appropriate modes. This applies both to open
|
|
|
99 * and save file dialog.
|
|
|
100 *
|
|
|
101 * \param userdata an app-provided pointer, for the callback's use.
|
|
|
102 * \param filelist the file(s) chosen by the user.
|
|
|
103 * \param filter index of the selected filter.
|
|
|
104 *
|
|
|
105 * \since This datatype is available since SDL 3.2.0.
|
|
|
106 *
|
|
|
107 * \sa SDL_DialogFileFilter
|
|
|
108 * \sa SDL_ShowOpenFileDialog
|
|
|
109 * \sa SDL_ShowSaveFileDialog
|
|
|
110 * \sa SDL_ShowOpenFolderDialog
|
|
|
111 * \sa SDL_ShowFileDialogWithProperties
|
|
|
112 */
|
|
|
113 typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter);
|
|
|
114
|
|
|
115 /**
|
|
|
116 * Displays a dialog that lets the user select a file on their filesystem.
|
|
|
117 *
|
|
|
118 * This is an asynchronous function; it will return immediately, and the
|
|
|
119 * result will be passed to the callback.
|
|
|
120 *
|
|
|
121 * The callback will be invoked with a null-terminated list of files the user
|
|
|
122 * chose. The list will be empty if the user canceled the dialog, and it will
|
|
|
123 * be NULL if an error occurred.
|
|
|
124 *
|
|
|
125 * Note that the callback may be called from a different thread than the one
|
|
|
126 * the function was invoked on.
|
|
|
127 *
|
|
|
128 * Depending on the platform, the user may be allowed to input paths that
|
|
|
129 * don't yet exist.
|
|
|
130 *
|
|
|
131 * On Linux, dialogs may require XDG Portals, which requires DBus, which
|
|
|
132 * requires an event-handling loop. Apps that do not use SDL to handle events
|
|
|
133 * should add a call to SDL_PumpEvents in their main loop.
|
|
|
134 *
|
|
|
135 * \param callback a function pointer to be invoked when the user selects a
|
|
|
136 * file and accepts, or cancels the dialog, or an error
|
|
|
137 * occurs.
|
|
|
138 * \param userdata an optional pointer to pass extra data to the callback when
|
|
|
139 * it will be invoked.
|
|
|
140 * \param window the window that the dialog should be modal for, may be NULL.
|
|
|
141 * Not all platforms support this option.
|
|
|
142 * \param filters a list of filters, may be NULL. See the
|
|
|
143 * [`SDL_DialogFileFilter`](SDL_DialogFileFilter#code-examples)
|
|
|
144 * documentation for examples]. Not all platforms support this
|
|
|
145 * option, and platforms that do support it may allow the user
|
|
|
146 * to ignore the filters. If non-NULL, it must remain valid at
|
|
|
147 * least until the callback is invoked.
|
|
|
148 * \param nfilters the number of filters. Ignored if filters is NULL.
|
|
|
149 * \param default_location the default folder or file to start the dialog at,
|
|
|
150 * may be NULL. Not all platforms support this option.
|
|
|
151 * \param allow_many if non-zero, the user will be allowed to select multiple
|
|
|
152 * entries. Not all platforms support this option.
|
|
|
153 *
|
|
|
154 * \threadsafety This function should be called only from the main thread. The
|
|
|
155 * callback may be invoked from the same thread or from a
|
|
|
156 * different one, depending on the OS's constraints.
|
|
|
157 *
|
|
|
158 * \since This function is available since SDL 3.2.0.
|
|
|
159 *
|
|
|
160 * \sa SDL_DialogFileCallback
|
|
|
161 * \sa SDL_DialogFileFilter
|
|
|
162 * \sa SDL_ShowSaveFileDialog
|
|
|
163 * \sa SDL_ShowOpenFolderDialog
|
|
|
164 * \sa SDL_ShowFileDialogWithProperties
|
|
|
165 */
|
|
|
166 extern 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);
|
|
|
167
|
|
|
168 /**
|
|
|
169 * Displays a dialog that lets the user choose a new or existing file on their
|
|
|
170 * filesystem.
|
|
|
171 *
|
|
|
172 * This is an asynchronous function; it will return immediately, and the
|
|
|
173 * result will be passed to the callback.
|
|
|
174 *
|
|
|
175 * The callback will be invoked with a null-terminated list of files the user
|
|
|
176 * chose. The list will be empty if the user canceled the dialog, and it will
|
|
|
177 * be NULL if an error occurred.
|
|
|
178 *
|
|
|
179 * Note that the callback may be called from a different thread than the one
|
|
|
180 * the function was invoked on.
|
|
|
181 *
|
|
|
182 * The chosen file may or may not already exist.
|
|
|
183 *
|
|
|
184 * On Linux, dialogs may require XDG Portals, which requires DBus, which
|
|
|
185 * requires an event-handling loop. Apps that do not use SDL to handle events
|
|
|
186 * should add a call to SDL_PumpEvents in their main loop.
|
|
|
187 *
|
|
|
188 * \param callback a function pointer to be invoked when the user selects a
|
|
|
189 * file and accepts, or cancels the dialog, or an error
|
|
|
190 * occurs.
|
|
|
191 * \param userdata an optional pointer to pass extra data to the callback when
|
|
|
192 * it will be invoked.
|
|
|
193 * \param window the window that the dialog should be modal for, may be NULL.
|
|
|
194 * Not all platforms support this option.
|
|
|
195 * \param filters a list of filters, may be NULL. Not all platforms support
|
|
|
196 * this option, and platforms that do support it may allow the
|
|
|
197 * user to ignore the filters. If non-NULL, it must remain
|
|
|
198 * valid at least until the callback is invoked.
|
|
|
199 * \param nfilters the number of filters. Ignored if filters is NULL.
|
|
|
200 * \param default_location the default folder or file to start the dialog at,
|
|
|
201 * may be NULL. Not all platforms support this option.
|
|
|
202 *
|
|
|
203 * \threadsafety This function should be called only from the main thread. The
|
|
|
204 * callback may be invoked from the same thread or from a
|
|
|
205 * different one, depending on the OS's constraints.
|
|
|
206 *
|
|
|
207 * \since This function is available since SDL 3.2.0.
|
|
|
208 *
|
|
|
209 * \sa SDL_DialogFileCallback
|
|
|
210 * \sa SDL_DialogFileFilter
|
|
|
211 * \sa SDL_ShowOpenFileDialog
|
|
|
212 * \sa SDL_ShowOpenFolderDialog
|
|
|
213 * \sa SDL_ShowFileDialogWithProperties
|
|
|
214 */
|
|
|
215 extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location);
|
|
|
216
|
|
|
217 /**
|
|
|
218 * Displays a dialog that lets the user select a folder on their filesystem.
|
|
|
219 *
|
|
|
220 * This is an asynchronous function; it will return immediately, and the
|
|
|
221 * result will be passed to the callback.
|
|
|
222 *
|
|
|
223 * The callback will be invoked with a null-terminated list of files the user
|
|
|
224 * chose. The list will be empty if the user canceled the dialog, and it will
|
|
|
225 * be NULL if an error occurred.
|
|
|
226 *
|
|
|
227 * Note that the callback may be called from a different thread than the one
|
|
|
228 * the function was invoked on.
|
|
|
229 *
|
|
|
230 * Depending on the platform, the user may be allowed to input paths that
|
|
|
231 * don't yet exist.
|
|
|
232 *
|
|
|
233 * On Linux, dialogs may require XDG Portals, which requires DBus, which
|
|
|
234 * requires an event-handling loop. Apps that do not use SDL to handle events
|
|
|
235 * should add a call to SDL_PumpEvents in their main loop.
|
|
|
236 *
|
|
|
237 * \param callback a function pointer to be invoked when the user selects a
|
|
|
238 * file and accepts, or cancels the dialog, or an error
|
|
|
239 * occurs.
|
|
|
240 * \param userdata an optional pointer to pass extra data to the callback when
|
|
|
241 * it will be invoked.
|
|
|
242 * \param window the window that the dialog should be modal for, may be NULL.
|
|
|
243 * Not all platforms support this option.
|
|
|
244 * \param default_location the default folder or file to start the dialog at,
|
|
|
245 * may be NULL. Not all platforms support this option.
|
|
|
246 * \param allow_many if non-zero, the user will be allowed to select multiple
|
|
|
247 * entries. Not all platforms support this option.
|
|
|
248 *
|
|
|
249 * \threadsafety This function should be called only from the main thread. The
|
|
|
250 * callback may be invoked from the same thread or from a
|
|
|
251 * different one, depending on the OS's constraints.
|
|
|
252 *
|
|
|
253 * \since This function is available since SDL 3.2.0.
|
|
|
254 *
|
|
|
255 * \sa SDL_DialogFileCallback
|
|
|
256 * \sa SDL_ShowOpenFileDialog
|
|
|
257 * \sa SDL_ShowSaveFileDialog
|
|
|
258 * \sa SDL_ShowFileDialogWithProperties
|
|
|
259 */
|
|
|
260 extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many);
|
|
|
261
|
|
|
262 /**
|
|
|
263 * Various types of file dialogs.
|
|
|
264 *
|
|
|
265 * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of
|
|
|
266 * dialog to present to the user.
|
|
|
267 *
|
|
|
268 * \since This enum is available since SDL 3.2.0.
|
|
|
269 *
|
|
|
270 * \sa SDL_ShowFileDialogWithProperties
|
|
|
271 */
|
|
|
272 typedef enum SDL_FileDialogType
|
|
|
273 {
|
|
|
274 SDL_FILEDIALOG_OPENFILE,
|
|
|
275 SDL_FILEDIALOG_SAVEFILE,
|
|
|
276 SDL_FILEDIALOG_OPENFOLDER
|
|
|
277 } SDL_FileDialogType;
|
|
|
278
|
|
|
279 /**
|
|
|
280 * Create and launch a file dialog with the specified properties.
|
|
|
281 *
|
|
|
282 * These are the supported properties:
|
|
|
283 *
|
|
|
284 * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of
|
|
|
285 * SDL_DialogFileFilter structs, which will be used as filters for
|
|
|
286 * file-based selections. Ignored if the dialog is an "Open Folder" dialog.
|
|
|
287 * If non-NULL, the array of filters must remain valid at least until the
|
|
|
288 * callback is invoked.
|
|
|
289 * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the
|
|
|
290 * array of filters, if it exists.
|
|
|
291 * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should
|
|
|
292 * be modal for.
|
|
|
293 * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to
|
|
|
294 * start the dialog at.
|
|
|
295 * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select
|
|
|
296 * more than one entry.
|
|
|
297 * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog.
|
|
|
298 * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button
|
|
|
299 * should have.
|
|
|
300 * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button
|
|
|
301 * should have.
|
|
|
302 *
|
|
|
303 * Note that each platform may or may not support any of the properties.
|
|
|
304 *
|
|
|
305 * \param type the type of file dialog.
|
|
|
306 * \param callback a function pointer to be invoked when the user selects a
|
|
|
307 * file and accepts, or cancels the dialog, or an error
|
|
|
308 * occurs.
|
|
|
309 * \param userdata an optional pointer to pass extra data to the callback when
|
|
|
310 * it will be invoked.
|
|
|
311 * \param props the properties to use.
|
|
|
312 *
|
|
|
313 * \threadsafety This function should be called only from the main thread. The
|
|
|
314 * callback may be invoked from the same thread or from a
|
|
|
315 * different one, depending on the OS's constraints.
|
|
|
316 *
|
|
|
317 * \since This function is available since SDL 3.2.0.
|
|
|
318 *
|
|
|
319 * \sa SDL_FileDialogType
|
|
|
320 * \sa SDL_DialogFileCallback
|
|
|
321 * \sa SDL_DialogFileFilter
|
|
|
322 * \sa SDL_ShowOpenFileDialog
|
|
|
323 * \sa SDL_ShowSaveFileDialog
|
|
|
324 * \sa SDL_ShowOpenFolderDialog
|
|
|
325 */
|
|
|
326 extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props);
|
|
|
327
|
|
|
328 #define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters"
|
|
|
329 #define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters"
|
|
|
330 #define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window"
|
|
|
331 #define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location"
|
|
|
332 #define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many"
|
|
|
333 #define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title"
|
|
|
334 #define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept"
|
|
|
335 #define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel"
|
|
|
336
|
|
|
337 /* Ends C function definitions when using C++ */
|
|
|
338 #ifdef __cplusplus
|
|
|
339 }
|
|
|
340 #endif
|
|
|
341 #include <SDL3/SDL_close_code.h>
|
|
|
342
|
|
|
343 #endif /* SDL_dialog_h_ */
|
