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#ifndef SDL_dialog_h_
23#define SDL_dialog_h_
24
25#include <SDL3/SDL_video.h>
26
27#include <SDL3/SDL_begin_code.h>
28/* Set up for C function definitions, even when using C++ */
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/**
34 * An entry for filters for file dialogs.
35 *
36 * `name` is a user-readable label for the filter (for example, "Office document").
37 *
38 * `pattern` is a semicolon-separated list of file extensions (for example,
39 * "doc;docx").
40 *
41 * \sa SDL_DialogFileCallback
42 * \sa SDL_ShowOpenFileDialog
43 * \sa SDL_ShowSaveFileDialog
44 * \sa SDL_ShowOpenFolderDialog
45 */
46typedef struct
47{
48 const char *name;
49 const char *pattern;
51
52/**
53 * Callback used by file dialog functions.
54 *
55 * The specific usage is described in each function.
56 *
57 * If filelist is...
58 * - `NULL`, an error occured. Details can be obtained with SDL_GetError().
59 * - A pointer to `NULL`, the user either didn't choose any file or canceled
60 * the dialog.
61 * - A pointer to non-`NULL`, the user chose one or more files. The argument is
62 * a null-terminated list of pointers to C strings, each containing a path.
63 *
64 * The filelist argument does not need to be freed; it will automatically be
65 * freed when the callback returns.
66 *
67 * The filter argument is the index of the filter that was selected, or one
68 * more than the size of the list (therefore the index of the terminating NULL
69 * entry) if no filter was selected, or -1 if the platform or method doesn't
70 * support fetching the selected filter or if an error occured.
71 *
72 * \sa SDL_DialogFileFilter
73 * \sa SDL_ShowOpenFileDialog
74 * \sa SDL_ShowSaveFileDialog
75 * \sa SDL_ShowOpenFolderDialog
76 */
77typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter);
78
79/**
80 * Displays a dialog that lets the user select a file on their filesystem.
81 *
82 * This function should only be invoked from the main thread.
83 *
84 * This is an asynchronous function; it will return immediately, and the
85 * result will be passed to the callback.
86 *
87 * The callback will be invoked with a null-terminated list of files the user
88 * chose. The list will be empty if the user canceled the dialog, and it will
89 * be NULL if an error occured.
90 *
91 * Note that the callback may be called from a different thread than the one
92 * the function was invoked on.
93 *
94 * Depending on the platform, the user may be allowed to input paths that
95 * don't yet exist.
96 *
97 * \param callback The function to be invoked when the user selects a file and
98 * accepts, or the user cancels the dialog, or an error
99 * occurs. The first argument is a null-terminated list of C
100 * strings, representing the paths chosen by the user. The
101 * list will be empty if the user canceled the dialog, and it
102 * will be NULL if an error occured. If an error occured, it
103 * can be fetched with SDL_GetError(). The second argument is
104 * the userdata pointer passed to the function.
105 * \param userdata An optional pointer to pass extra data to the callback when
106 * it will be invoked.
107 * \param window The window that the dialog should be modal for. May be NULL.
108 * Not all platforms support this option.
109 * \param filters A null-terminated list of SDL_DialogFileFilter's. May be
110 * NULL. Not all platforms support this option, and platforms
111 * that do support it may allow the user to ignore the filters.
112 * \param default_location The default folder or file to start the dialog at.
113 * May be NULL. Not all platforms support this option.
114 * \param allow_many If non-zero, the user will be allowed to select multiple
115 * entries. Not all platforms support this option.
116 *
117 * \since This function is available since SDL 3.0.0.
118 *
119 * \sa SDL_ShowSaveFileDialog
120 * \sa SDL_ShowOpenFolderDialog
121 */
122extern DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location, SDL_bool allow_many);
123
124/**
125 * Displays a dialog that lets the user choose a new or existing file on their
126 * filesystem.
127 *
128 * This function should only be invoked from the main thread.
129 *
130 * This is an asynchronous function; it will return immediately, and the
131 * result will be passed to the callback.
132 *
133 * The callback will be invoked with a null-terminated list of files the user
134 * chose. The list will be empty if the user canceled the dialog, and it will
135 * be NULL if an error occured.
136 *
137 * Note that the callback may be called from a different thread than the one
138 * the function was invoked on.
139 *
140 * The chosen file may or may not already exist.
141 *
142 * \param callback The function to be invoked when the user selects a file and
143 * accepts, or the user cancels the dialog, or an error
144 * occurs. The first argument is a null-terminated list of C
145 * strings, representing the paths chosen by the user. The
146 * list will be empty if the user canceled the dialog, and it
147 * will be NULL if an error occured. If an error occured, it
148 * can be fetched with SDL_GetError(). The second argument is
149 * the userdata pointer passed to the function.
150 * \param userdata An optional pointer to pass extra data to the callback when
151 * it will be invoked.
152 * \param window The window that the dialog should be modal for. May be NULL.
153 * Not all platforms support this option.
154 * \param filters A null-terminated list of SDL_DialogFileFilter's. May be
155 * NULL. Not all platforms support this option, and platforms
156 * that do support it may allow the user to ignore the filters.
157 * \param default_location The default folder or file to start the dialog at.
158 * May be NULL. Not all platforms support this option.
159 *
160 * \since This function is available since SDL 3.0.0.
161 *
162 * \sa SDL_ShowOpenFileDialog
163 */
164extern DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location);
165
166/**
167 * Displays a dialog that lets the user select a folder on their filesystem.
168 *
169 * This function should only be invoked from the main thread.
170 *
171 * This is an asynchronous function; it will return immediately, and the
172 * result will be passed to the callback.
173 *
174 * The callback will be invoked with a null-terminated list of files the user
175 * chose. The list will be empty if the user canceled the dialog, and it will
176 * be NULL if an error occured.
177 *
178 * Note that the callback may be called from a different thread than the one
179 * the function was invoked on.
180 *
181 * Depending on the platform, the user may be allowed to input paths that
182 * don't yet exist.
183 *
184 * \param callback The function to be invoked when the user selects a folder
185 * and accepts, or the user cancels the dialog, or an error
186 * occurs. The first argument is a null-terminated list of C
187 * strings, representing the paths chosen by the user. The
188 * list will be empty if the user canceled the dialog, and it
189 * will be NULL if an error occured. If an error occured, it
190 * can be fetched with SDL_GetError(). The second argument is
191 * the userdata pointer passed to the function.
192 * \param userdata An optional pointer to pass extra data to the callback when
193 * it will be invoked.
194 * \param window The window that the dialog should be modal for. May be NULL.
195 * Not all platforms support this option.
196 * \param default_location The default folder or file to start the dialog at.
197 * May be NULL. Not all platforms support this option.
198 * \param allow_many If non-zero, the user will be allowed to select multiple
199 * entries. Not all platforms support this option.
200 *
201 * \since This function is available since SDL 3.0.0.
202 *
203 * \sa SDL_ShowOpenFileDialog
204 */
205extern DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many);
206
207/* Ends C function definitions when using C++ */
208#ifdef __cplusplus
209}
210#endif
211#include <SDL3/SDL_close_code.h>
212
213#endif /* SDL_joystick_h_ */
void SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location)
void SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many)
void(* SDL_DialogFileCallback)(void *userdata, const char *const *filelist, int filter)
Definition SDL_dialog.h:77
void SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location, SDL_bool allow_many)
int SDL_bool
Definition SDL_stdinc.h:137
struct SDL_Window SDL_Window
Definition SDL_video.h:108
const char * name
Definition SDL_dialog.h:48
const char * pattern
Definition SDL_dialog.h:49