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
28#ifndef SDL_dialog_h_
29#define SDL_dialog_h_
30
31#include <SDL3/SDL_error.h>
32#include <SDL3/SDL_video.h>
33
34#include <SDL3/SDL_begin_code.h>
35/* Set up for C function definitions, even when using C++ */
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * An entry for filters for file dialogs.
42 *
43 * `name` is a user-readable label for the filter (for example, "Office
44 * document").
45 *
46 * `pattern` is a semicolon-separated list of file extensions (for example,
47 * "doc;docx"). File extensions may only contain alphanumeric characters,
48 * hyphens, underscores and periods. Alternatively, the whole string can be a
49 * single asterisk ("*"), which serves as an "All files" filter.
50 *
51 * \since This struct is available since SDL 3.0.0.
52 *
53 * \sa SDL_DialogFileCallback
54 * \sa SDL_ShowOpenFileDialog
55 * \sa SDL_ShowSaveFileDialog
56 * \sa SDL_ShowOpenFolderDialog
57 */
59{
60 const char *name;
61 const char *pattern;
63
64/**
65 * Callback used by file dialog functions.
66 *
67 * The specific usage is described in each function.
68 *
69 * If `filelist` is:
70 *
71 * - NULL, an error occurred. Details can be obtained with SDL_GetError().
72 * - A pointer to NULL, the user either didn't choose any file or canceled the
73 * dialog.
74 * - A pointer to non-`NULL`, the user chose one or more files. The argument
75 * is a null-terminated list of pointers to C strings, each containing a
76 * path.
77 *
78 * The filelist argument does not need to be freed; it will automatically be
79 * freed when the callback returns.
80 *
81 * The filter argument is the index of the filter that was selected, or -1 if
82 * no filter was selected or if the platform or method doesn't support
83 * fetching the selected filter.
84 *
85 * \param userdata an app-provided pointer, for the callback's use.
86 * \param filelist the file(s) chosen by the user.
87 * \param filter index of the selected filter.
88 *
89 * \since This datatype is available since SDL 3.0.0.
90 *
91 * \sa SDL_DialogFileFilter
92 * \sa SDL_ShowOpenFileDialog
93 * \sa SDL_ShowSaveFileDialog
94 * \sa SDL_ShowOpenFolderDialog
95 */
96typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter);
97
98/**
99 * Displays a dialog that lets the user select a file on their filesystem.
100 *
101 * This function should only be invoked from the main thread.
102 *
103 * This is an asynchronous function; it will return immediately, and the
104 * result will be passed to the callback.
105 *
106 * The callback will be invoked with a null-terminated list of files the user
107 * chose. The list will be empty if the user canceled the dialog, and it will
108 * be NULL if an error occurred.
109 *
110 * Note that the callback may be called from a different thread than the one
111 * the function was invoked on.
112 *
113 * Depending on the platform, the user may be allowed to input paths that
114 * don't yet exist.
115 *
116 * On Linux, dialogs may require XDG Portals, which requires DBus, which
117 * requires an event-handling loop. Apps that do not use SDL to handle events
118 * should add a call to SDL_PumpEvents in their main loop.
119 *
120 * \param callback an SDL_DialogFileCallback to be invoked when the user
121 * selects a file and accepts, or cancels the dialog, or an
122 * error occurs. The first argument is a null-terminated list
123 * of C strings, representing the paths chosen by the user.
124 * The list will be empty if the user canceled the dialog, and
125 * it will be NULL if an error occurred. If an error occurred,
126 * it can be fetched with SDL_GetError(). The second argument
127 * is the userdata pointer passed to the function. The third
128 * argument is the index of the filter selected by the user,
129 * or one past the index of the last filter (therefore the
130 * index of the terminating NULL filter) if no filter was
131 * chosen, or -1 if the platform does not support detecting
132 * the selected filter.
133 * \param userdata an optional pointer to pass extra data to the callback when
134 * it will be invoked.
135 * \param window the window that the dialog should be modal for. May be NULL.
136 * Not all platforms support this option.
137 * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
138 * platforms support this option, and platforms that do support
139 * it may allow the user to ignore the filters.
140 * \param nfilters the number of filters. Ignored if filters is NULL.
141 * \param default_location the default folder or file to start the dialog at.
142 * May be NULL. Not all platforms support this option.
143 * \param allow_many if non-zero, the user will be allowed to select multiple
144 * entries. Not all platforms support this option.
145 *
146 * \since This function is available since SDL 3.0.0.
147 *
148 * \sa SDL_DialogFileCallback
149 * \sa SDL_DialogFileFilter
150 * \sa SDL_ShowSaveFileDialog
151 * \sa SDL_ShowOpenFolderDialog
152 */
153extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many);
154
155/**
156 * Displays a dialog that lets the user choose a new or existing file on their
157 * filesystem.
158 *
159 * This function should only be invoked from the main thread.
160 *
161 * This is an asynchronous function; it will return immediately, and the
162 * result will be passed to the callback.
163 *
164 * The callback will be invoked with a null-terminated list of files the user
165 * chose. The list will be empty if the user canceled the dialog, and it will
166 * be NULL if an error occurred.
167 *
168 * Note that the callback may be called from a different thread than the one
169 * the function was invoked on.
170 *
171 * The chosen file may or may not already exist.
172 *
173 * On Linux, dialogs may require XDG Portals, which requires DBus, which
174 * requires an event-handling loop. Apps that do not use SDL to handle events
175 * should add a call to SDL_PumpEvents in their main loop.
176 *
177 * \param callback an SDL_DialogFileCallback to be invoked when the user
178 * selects a file and accepts, or cancels the dialog, or an
179 * error occurs. The first argument is a null-terminated list
180 * of C strings, representing the paths chosen by the user.
181 * The list will be empty if the user canceled the dialog, and
182 * it will be NULL if an error occurred. If an error occurred,
183 * it can be fetched with SDL_GetError(). The second argument
184 * is the userdata pointer passed to the function. The third
185 * argument is the index of the filter selected by the user,
186 * or one past the index of the last filter (therefore the
187 * index of the terminating NULL filter) if no filter was
188 * chosen, or -1 if the platform does not support detecting
189 * the selected filter.
190 * \param userdata an optional pointer to pass extra data to the callback when
191 * it will be invoked.
192 * \param window the window that the dialog should be modal for. May be NULL.
193 * Not all platforms support this option.
194 * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
195 * platforms support this option, and platforms that do support
196 * it may allow the user to ignore the filters.
197 * \param nfilters the number of filters. Ignored if filters is NULL.
198 * \param default_location the default folder or file to start the dialog at.
199 * May be NULL. Not all platforms support this option.
200 *
201 * \since This function is available since SDL 3.0.0.
202 *
203 * \sa SDL_DialogFileCallback
204 * \sa SDL_DialogFileFilter
205 * \sa SDL_ShowOpenFileDialog
206 * \sa SDL_ShowOpenFolderDialog
207 */
208extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location);
209
210/**
211 * Displays a dialog that lets the user select a folder on their filesystem.
212 *
213 * This function should only be invoked from the main thread.
214 *
215 * This is an asynchronous function; it will return immediately, and the
216 * result will be passed to the callback.
217 *
218 * The callback will be invoked with a null-terminated list of files the user
219 * chose. The list will be empty if the user canceled the dialog, and it will
220 * be NULL if an error occurred.
221 *
222 * Note that the callback may be called from a different thread than the one
223 * the function was invoked on.
224 *
225 * Depending on the platform, the user may be allowed to input paths that
226 * don't yet exist.
227 *
228 * On Linux, dialogs may require XDG Portals, which requires DBus, which
229 * requires an event-handling loop. Apps that do not use SDL to handle events
230 * should add a call to SDL_PumpEvents in their main loop.
231 *
232 * \param callback an SDL_DialogFileCallback to be invoked when the user
233 * selects a file and accepts, or cancels the dialog, or an
234 * error occurs. The first argument is a null-terminated list
235 * of C strings, representing the paths chosen by the user.
236 * The list will be empty if the user canceled the dialog, and
237 * it will be NULL if an error occurred. If an error occurred,
238 * it can be fetched with SDL_GetError(). The second argument
239 * is the userdata pointer passed to the function. The third
240 * argument is always -1 for SDL_ShowOpenFolderDialog.
241 * \param userdata an optional pointer to pass extra data to the callback when
242 * it will be invoked.
243 * \param window the window that the dialog should be modal for. May be NULL.
244 * Not all platforms support this option.
245 * \param default_location the default folder or file to start the dialog at.
246 * May be NULL. Not all platforms support this option.
247 * \param allow_many if non-zero, the user will be allowed to select multiple
248 * entries. Not all platforms support this option.
249 *
250 * \since This function is available since SDL 3.0.0.
251 *
252 * \sa SDL_DialogFileCallback
253 * \sa SDL_ShowOpenFileDialog
254 * \sa SDL_ShowSaveFileDialog
255 */
256extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many);
257
258/* Ends C function definitions when using C++ */
259#ifdef __cplusplus
260}
261#endif
262#include <SDL3/SDL_close_code.h>
263
264#endif /* SDL_joystick_h_ */
void SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many)
void SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many)
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:96
int SDL_bool
Definition SDL_stdinc.h:213
struct SDL_Window SDL_Window
Definition SDL_video.h:127
const char * name
Definition SDL_dialog.h:60
const char * pattern
Definition SDL_dialog.h:61