Atlas - SDL_dialog.h
Home / ext / SDL / include / SDL3 Lines: 1 | Size: 14404 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2026 Sam Lantinga <[email protected]> 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.2.0. 63 * 64 * \sa SDL_DialogFileCallback 65 * \sa SDL_ShowOpenFileDialog 66 * \sa SDL_ShowSaveFileDialog 67 * \sa SDL_ShowOpenFolderDialog 68 * \sa SDL_ShowFileDialogWithProperties 69 */ 70typedef 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 */ 113typedef 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. Not all platforms support 143 * this option, and platforms that do support it may allow the 144 * user to ignore the filters. If non-NULL, it must remain 145 * valid at least until the callback is invoked. 146 * \param nfilters the number of filters. Ignored if filters is NULL. 147 * \param default_location the default folder or file to start the dialog at, 148 * may be NULL. Not all platforms support this option. 149 * \param allow_many if non-zero, the user will be allowed to select multiple 150 * entries. Not all platforms support this option. 151 * 152 * \threadsafety This function should be called only from the main thread. The 153 * callback may be invoked from the same thread or from a 154 * different one, depending on the OS's constraints. 155 * 156 * \since This function is available since SDL 3.2.0. 157 * 158 * \sa SDL_DialogFileCallback 159 * \sa SDL_DialogFileFilter 160 * \sa SDL_ShowSaveFileDialog 161 * \sa SDL_ShowOpenFolderDialog 162 * \sa SDL_ShowFileDialogWithProperties 163 */ 164extern 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); 165 166/** 167 * Displays a dialog that lets the user choose a new or existing file on their 168 * filesystem. 169 * 170 * This is an asynchronous function; it will return immediately, and the 171 * result will be passed to the callback. 172 * 173 * The callback will be invoked with a null-terminated list of files the user 174 * chose. The list will be empty if the user canceled the dialog, and it will 175 * be NULL if an error occurred. 176 * 177 * Note that the callback may be called from a different thread than the one 178 * the function was invoked on. 179 * 180 * The chosen file may or may not already exist. 181 * 182 * On Linux, dialogs may require XDG Portals, which requires DBus, which 183 * requires an event-handling loop. Apps that do not use SDL to handle events 184 * should add a call to SDL_PumpEvents in their main loop. 185 * 186 * \param callback a function pointer to be invoked when the user selects a 187 * file and accepts, or cancels the dialog, or an error 188 * occurs. 189 * \param userdata an optional pointer to pass extra data to the callback when 190 * it will be invoked. 191 * \param window the window that the dialog should be modal for, may be NULL. 192 * Not all platforms support this option. 193 * \param filters a list of filters, may be NULL. Not all platforms support 194 * this option, and platforms that do support it may allow the 195 * user to ignore the filters. If non-NULL, it must remain 196 * valid at least until the callback is invoked. 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 * \threadsafety This function should be called only from the main thread. The 202 * callback may be invoked from the same thread or from a 203 * different one, depending on the OS's constraints. 204 * 205 * \since This function is available since SDL 3.2.0. 206 * 207 * \sa SDL_DialogFileCallback 208 * \sa SDL_DialogFileFilter 209 * \sa SDL_ShowOpenFileDialog 210 * \sa SDL_ShowOpenFolderDialog 211 * \sa SDL_ShowFileDialogWithProperties 212 */ 213extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); 214 215/** 216 * Displays a dialog that lets the user select a folder on their filesystem. 217 * 218 * This is an asynchronous function; it will return immediately, and the 219 * result will be passed to the callback. 220 * 221 * The callback will be invoked with a null-terminated list of files the user 222 * chose. The list will be empty if the user canceled the dialog, and it will 223 * be NULL if an error occurred. 224 * 225 * Note that the callback may be called from a different thread than the one 226 * the function was invoked on. 227 * 228 * Depending on the platform, the user may be allowed to input paths that 229 * don't yet exist. 230 * 231 * On Linux, dialogs may require XDG Portals, which requires DBus, which 232 * requires an event-handling loop. Apps that do not use SDL to handle events 233 * should add a call to SDL_PumpEvents in their main loop. 234 * 235 * \param callback a function pointer to be invoked when the user selects a 236 * file and accepts, or cancels the dialog, or an error 237 * occurs. 238 * \param userdata an optional pointer to pass extra data to the callback when 239 * it will be invoked. 240 * \param window the window that the dialog should be modal for, may be NULL. 241 * Not all platforms support this option. 242 * \param default_location the default folder or file to start the dialog at, 243 * may be NULL. Not all platforms support this option. 244 * \param allow_many if non-zero, the user will be allowed to select multiple 245 * entries. Not all platforms support this option. 246 * 247 * \threadsafety This function should be called only from the main thread. The 248 * callback may be invoked from the same thread or from a 249 * different one, depending on the OS's constraints. 250 * 251 * \since This function is available since SDL 3.2.0. 252 * 253 * \sa SDL_DialogFileCallback 254 * \sa SDL_ShowOpenFileDialog 255 * \sa SDL_ShowSaveFileDialog 256 * \sa SDL_ShowFileDialogWithProperties 257 */ 258extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); 259 260/** 261 * Various types of file dialogs. 262 * 263 * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of 264 * dialog to present to the user. 265 * 266 * \since This enum is available since SDL 3.2.0. 267 * 268 * \sa SDL_ShowFileDialogWithProperties 269 */ 270typedef enum SDL_FileDialogType 271{ 272 SDL_FILEDIALOG_OPENFILE, 273 SDL_FILEDIALOG_SAVEFILE, 274 SDL_FILEDIALOG_OPENFOLDER 275} SDL_FileDialogType; 276 277/** 278 * Create and launch a file dialog with the specified properties. 279 * 280 * These are the supported properties: 281 * 282 * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of 283 * SDL_DialogFileFilter structs, which will be used as filters for 284 * file-based selections. Ignored if the dialog is an "Open Folder" dialog. 285 * If non-NULL, the array of filters must remain valid at least until the 286 * callback is invoked. 287 * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the 288 * array of filters, if it exists. 289 * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should 290 * be modal for. 291 * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to 292 * start the dialog at. 293 * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select 294 * more than one entry. 295 * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. 296 * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button 297 * should have. 298 * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button 299 * should have. 300 * 301 * Note that each platform may or may not support any of the properties. 302 * 303 * \param type the type of file dialog. 304 * \param callback a function pointer to be invoked when the user selects a 305 * file and accepts, or cancels the dialog, or an error 306 * occurs. 307 * \param userdata an optional pointer to pass extra data to the callback when 308 * it will be invoked. 309 * \param props the properties to use. 310 * 311 * \threadsafety This function should be called only from the main thread. The 312 * callback may be invoked from the same thread or from a 313 * different one, depending on the OS's constraints. 314 * 315 * \since This function is available since SDL 3.2.0. 316 * 317 * \sa SDL_FileDialogType 318 * \sa SDL_DialogFileCallback 319 * \sa SDL_DialogFileFilter 320 * \sa SDL_ShowOpenFileDialog 321 * \sa SDL_ShowSaveFileDialog 322 * \sa SDL_ShowOpenFolderDialog 323 */ 324extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); 325 326#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" 327#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" 328#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" 329#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" 330#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" 331#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" 332#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" 333#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" 334 335/* Ends C function definitions when using C++ */ 336#ifdef __cplusplus 337} 338#endif 339#include <SDL3/SDL_close_code.h> 340 341#endif /* SDL_dialog_h_ */ 342[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.