SDL 3.0
SDL_dialog.h File Reference
+ Include dependency graph for SDL_dialog.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_DialogFileFilter
 

Typedefs

typedef void(* SDL_DialogFileCallback) (void *userdata, const char *const *filelist, int filter)
 

Functions

void SDL_ShowOpenFileDialog (SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, const char *default_location, SDL_bool allow_many)
 
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)
 

Typedef Documentation

◆ SDL_DialogFileCallback

typedef void(* SDL_DialogFileCallback) (void *userdata, const char *const *filelist, int filter)

Callback used by file dialog functions.

The specific usage is described in each function.

If filelist is... - NULL, an error occured. Details can be obtained with SDL_GetError(). - A pointer to NULL, the user either didn't choose any file or canceled the dialog. - A pointer to non-NULL, the user chose one or more files. The argument is a null-terminated list of pointers to C strings, each containing a path.

The filelist argument does not need to be freed; it will automatically be freed when the callback returns.

The filter argument is the index of the filter that was selected, or one more than the size of the list (therefore the index of the terminating NULL entry) if no filter was selected, or -1 if the platform or method doesn't support fetching the selected filter or if an error occured.

Since
This datatype is available since SDL 3.0.0.
See also
SDL_DialogFileFilter
SDL_ShowOpenFileDialog
SDL_ShowSaveFileDialog
SDL_ShowOpenFolderDialog

Definition at line 84 of file SDL_dialog.h.

Function Documentation

◆ SDL_ShowOpenFileDialog()

void SDL_ShowOpenFileDialog ( SDL_DialogFileCallback  callback,
void *  userdata,
SDL_Window window,
const SDL_DialogFileFilter filters,
const char *  default_location,
SDL_bool  allow_many 
)
extern

Displays a dialog that lets the user select a file on their filesystem.

This function should only be invoked from the main thread.

This is an asynchronous function; it will return immediately, and the result will be passed to the callback.

The callback will be invoked with a null-terminated list of files the user chose. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured.

Note that the callback may be called from a different thread than the one the function was invoked on.

Depending on the platform, the user may be allowed to input paths that don't yet exist.

Parameters
callbackThe function to be invoked when the user selects a file and accepts, or the user cancels the dialog, or an error occurs. The first argument is a null-terminated list of C strings, representing the paths chosen by the user. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured. If an error occured, it can be fetched with SDL_GetError(). The second argument is the userdata pointer passed to the function.
userdataAn optional pointer to pass extra data to the callback when it will be invoked.
windowThe window that the dialog should be modal for. May be NULL. Not all platforms support this option.
filtersA null-terminated list of SDL_DialogFileFilter's. May be NULL. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters.
default_locationThe default folder or file to start the dialog at. May be NULL. Not all platforms support this option.
allow_manyIf non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.
Since
This function is available since SDL 3.0.0.
See also
SDL_ShowSaveFileDialog
SDL_ShowOpenFolderDialog

◆ SDL_ShowOpenFolderDialog()

void SDL_ShowOpenFolderDialog ( SDL_DialogFileCallback  callback,
void *  userdata,
SDL_Window window,
const char *  default_location,
SDL_bool  allow_many 
)
extern

Displays a dialog that lets the user select a folder on their filesystem.

This function should only be invoked from the main thread.

This is an asynchronous function; it will return immediately, and the result will be passed to the callback.

The callback will be invoked with a null-terminated list of files the user chose. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured.

Note that the callback may be called from a different thread than the one the function was invoked on.

Depending on the platform, the user may be allowed to input paths that don't yet exist.

Parameters
callbackThe function to be invoked when the user selects a folder and accepts, or the user cancels the dialog, or an error occurs. The first argument is a null-terminated list of C strings, representing the paths chosen by the user. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured. If an error occured, it can be fetched with SDL_GetError(). The second argument is the userdata pointer passed to the function.
userdataAn optional pointer to pass extra data to the callback when it will be invoked.
windowThe window that the dialog should be modal for. May be NULL. Not all platforms support this option.
default_locationThe default folder or file to start the dialog at. May be NULL. Not all platforms support this option.
allow_manyIf non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.
Since
This function is available since SDL 3.0.0.
See also
SDL_ShowOpenFileDialog

◆ SDL_ShowSaveFileDialog()

void SDL_ShowSaveFileDialog ( SDL_DialogFileCallback  callback,
void *  userdata,
SDL_Window window,
const SDL_DialogFileFilter filters,
const char *  default_location 
)
extern

Displays a dialog that lets the user choose a new or existing file on their filesystem.

This function should only be invoked from the main thread.

This is an asynchronous function; it will return immediately, and the result will be passed to the callback.

The callback will be invoked with a null-terminated list of files the user chose. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured.

Note that the callback may be called from a different thread than the one the function was invoked on.

The chosen file may or may not already exist.

Parameters
callbackThe function to be invoked when the user selects a file and accepts, or the user cancels the dialog, or an error occurs. The first argument is a null-terminated list of C strings, representing the paths chosen by the user. The list will be empty if the user canceled the dialog, and it will be NULL if an error occured. If an error occured, it can be fetched with SDL_GetError(). The second argument is the userdata pointer passed to the function.
userdataAn optional pointer to pass extra data to the callback when it will be invoked.
windowThe window that the dialog should be modal for. May be NULL. Not all platforms support this option.
filtersA null-terminated list of SDL_DialogFileFilter's. May be NULL. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters.
default_locationThe default folder or file to start the dialog at. May be NULL. Not all platforms support this option.
Since
This function is available since SDL 3.0.0.
See also
SDL_ShowOpenFileDialog