Mercurial > foo_out_sdl

comparison SDL3/SDL_dialog.h @ 1:20d02a178406 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: check in everything else yay
author Paper <paper@tflc.us>
date Mon, 05 Jan 2026 02:15:46 -0500
parents
children
comparison
equal deleted inserted replaced
0:e9bb126753e7 1:20d02a178406
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_ */