SDL offers file dialogs, to let users select files with native GUI interfaces. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::FileDialog
	Properties for file dialogs.

Typedefs
using	SDL::DialogFileFilter = SDL_DialogFileFilter
	An entry for filters for file dialogs.
using	SDL::DialogFileCallback
	Callback used by file dialog functions.
using	SDL::DialogFileCB
	Callback used by file dialog functions.
using	SDL::FileDialogType = SDL_FileDialogType
	Various types of file dialogs.

Functions
void	SDL::ShowOpenFileDialog (DialogFileCallback callback, void *userdata, WindowRef window, std::span< const DialogFileFilter > filters={}, StringParam default_location={}, bool allow_many=false)
	Displays a dialog that lets the user select a file on their filesystem.
void	SDL::ShowOpenFileDialog (DialogFileCB callback, WindowRef window, std::span< const DialogFileFilter > filters={}, StringParam default_location={}, bool allow_many=false)
	Displays a dialog that lets the user select a file on their filesystem.
void	SDL::ShowSaveFileDialog (DialogFileCallback callback, void *userdata, WindowRef window={}, std::span< const DialogFileFilter > filters={}, StringParam default_location={})
	Displays a dialog that lets the user choose a new or existing file on their filesystem.
void	SDL::ShowSaveFileDialog (DialogFileCB callback, WindowRef window={}, std::span< const DialogFileFilter > filters={}, StringParam default_location={})
	Displays a dialog that lets the user choose a new or existing file on their filesystem.
void	SDL::ShowOpenFolderDialog (DialogFileCallback callback, void *userdata, WindowRef window={}, StringParam default_location={}, bool allow_many=false)
	Displays a dialog that lets the user select a folder on their filesystem.
void	SDL::ShowOpenFolderDialog (DialogFileCB callback, WindowRef window={}, StringParam default_location={}, bool allow_many=false)
	Displays a dialog that lets the user select a folder on their filesystem.
void	SDL::ShowFileDialogWithProperties (FileDialogType type, DialogFileCallback callback, void *userdata, PropertiesRef props)
	Create and launch a file dialog with the specified properties.
void	SDL::ShowFileDialogWithProperties (FileDialogType type, DialogFileCB callback, PropertiesID props)
	Create and launch a file dialog with the specified properties.

Variables
constexpr FileDialogType	SDL::FILEDIALOG_OPENFILE
	OPENFILE.
constexpr FileDialogType	SDL::FILEDIALOG_SAVEFILE
	SAVEFILE.
constexpr FileDialogType	SDL::FILEDIALOG_OPENFOLDER
	OPENFOLDER.

Detailed Description

SDL offers file dialogs, to let users select files with native GUI interfaces.

There are "open" dialogs, "save" dialogs, and folder selection dialogs. The app can control some details, such as filtering to specific files, or whether multiple files can be selected by the user.

Note that launching a file dialog is a non-blocking operation; control returns to the app immediately, and a callback is called later (possibly in another thread) when the user makes a choice.

Typedef Documentation

◆ DialogFileCallback

using SDL::DialogFileCallback

Initial value:

void(SDLCALL*)(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:

nullptr, an error occurred. Details can be obtained with GetError().
A pointer to nullptr, the user either didn't choose any file or canceled the dialog.
A pointer to non-nullptr, the user chose one or more files. The argument is a null-terminated array of pointers to UTF-8 encoded strings, each containing a path.

The filelist argument should not be freed; it will automatically be freed when the callback returns.

The filter argument is the index of the filter that was selected, or -1 if no filter was selected or if the platform or method doesn't support fetching the selected filter.

In Android, the filelist are content:// URIs. They should be opened using IOStream.FromFile() with appropriate modes. This applies both to open and save file dialog.

Parameters

userdata	an app-provided pointer, for the callback's use.
filelist	the file(s) chosen by the user.
filter	index of the selected filter.

Since: This datatype is available since SDL 3.2.0.

See also: DialogFileFilter; ShowOpenFileDialog; ShowSaveFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

◆ DialogFileCB

using SDL::DialogFileCB

Initial value:

std::function<void(const char* const* filelist, int filter)>

Callback used by file dialog functions.

The specific usage is described in each function.

If filelist is:

nullptr, an error occurred. Details can be obtained with GetError().
A pointer to nullptr, the user either didn't choose any file or canceled the dialog.
A pointer to non-nullptr, the user chose one or more files. The argument is a null-terminated array of pointers to UTF-8 encoded strings, each containing a path.

The filelist argument should not be freed; it will automatically be freed when the callback returns.

The filter argument is the index of the filter that was selected, or -1 if no filter was selected or if the platform or method doesn't support fetching the selected filter.

In Android, the filelist are content:// URIs. They should be opened using IOStream.FromFile() with appropriate modes. This applies both to open and save file dialog.

Parameters

filelist	the file(s) chosen by the user.
filter	index of the selected filter.

Since: This datatype is available since SDL 3.2.0.

See also: DialogFileFilter; ShowOpenFileDialog; ShowSaveFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties; DialogFileCallback

◆ DialogFileFilter

using SDL::DialogFileFilter = SDL_DialogFileFilter

An entry for filters for file dialogs.

name is a user-readable label for the filter (for example, "Office document").

pattern is a semicolon-separated list of file extensions (for example, "doc;docx"). File extensions may only contain alphanumeric characters, hyphens, underscores and periods. Alternatively, the whole string can be a single asterisk ("*"), which serves as an "All files" filter.

Since: This struct is available since SDL 3.2.0.

See also: DialogFileCallback; ShowOpenFileDialog; ShowSaveFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

◆ FileDialogType

using SDL::FileDialogType = SDL_FileDialogType

Various types of file dialogs.

This is used by ShowFileDialogWithProperties() to decide what kind of dialog to present to the user.

Since: This enum is available since SDL 3.2.0.

See also: ShowFileDialogWithProperties

Function Documentation

◆ ShowFileDialogWithProperties() [1/2]

void SDL::ShowFileDialogWithProperties	(	FileDialogType	type,
		DialogFileCallback	callback,
		void *	userdata,
		PropertiesRef	props )

inline

Create and launch a file dialog with the specified properties.

These are the supported properties:

prop.FileDialog.FILTERS_POINTER: a pointer to a list of DialogFileFilter structs, which will be used as filters for file-based selections. Ignored if the dialog is an "Open Folder" dialog. If non-nullptr, the array of filters must remain valid at least until the callback is invoked.
prop.FileDialog.NFILTERS_NUMBER: the number of filters in the array of filters, if it exists.
prop.FileDialog.WINDOW_POINTER: the window that the dialog should be modal for.
prop.FileDialog.LOCATION_STRING: the default folder or file to start the dialog at.
prop.FileDialog.MANY_BOOLEAN: true to allow the user to select more than one entry.
prop.FileDialog.TITLE_STRING: the title for the dialog.
prop.FileDialog.ACCEPT_STRING: the label that the accept button should have.
prop.FileDialog.CANCEL_STRING: the label that the cancel button should have.

Note that each platform may or may not support any of the properties.

Parameters

type	the type of file dialog.
callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
userdata	an optional pointer to pass extra data to the callback when it will be invoked.
props	the properties to use.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: FileDialogType; DialogFileCallback; DialogFileFilter; ShowOpenFileDialog; ShowSaveFileDialog; ShowOpenFolderDialog

◆ ShowFileDialogWithProperties() [2/2]

void SDL::ShowFileDialogWithProperties	(	FileDialogType	type,
		DialogFileCB	callback,
		PropertiesID	props )

inline

Create and launch a file dialog with the specified properties.

These are the supported properties:

prop.FileDialog.FILTERS_POINTER: a pointer to a list of DialogFileFilter structs, which will be used as filters for file-based selections. Ignored if the dialog is an "Open Folder" dialog. If non-nullptr, the array of filters must remain valid at least until the callback is invoked.
prop.FileDialog.NFILTERS_NUMBER: the number of filters in the array of filters, if it exists.
prop.FileDialog.WINDOW_POINTER: the window that the dialog should be modal for.
prop.FileDialog.LOCATION_STRING: the default folder or file to start the dialog at.
prop.FileDialog.MANY_BOOLEAN: true to allow the user to select more than one entry.
prop.FileDialog.TITLE_STRING: the title for the dialog.
prop.FileDialog.ACCEPT_STRING: the label that the accept button should have.
prop.FileDialog.CANCEL_STRING: the label that the cancel button should have.

Note that each platform may or may not support any of the properties.

Parameters

type	the type of file dialog.
callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
props	the properties to use.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: FileDialogType; DialogFileCallback; DialogFileFilter; ShowOpenFileDialog; ShowSaveFileDialog; ShowOpenFolderDialog

◆ ShowOpenFileDialog() [1/2]

void SDL::ShowOpenFileDialog	(	DialogFileCallback	callback,
		void *	userdata,
		WindowRef	window,
		std::span< const DialogFileFilter >	filters = {},
		StringParam	default_location = {},
		bool	allow_many = false )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
userdata	an optional pointer to pass extra data to the callback when it will be invoked.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
filters	a list of filters, may be nullptr. See the `DialogFileFilter` documentation for examples]. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-nullptr, it must remain valid at least until the callback is invoked.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.
allow_many	if non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; DialogFileFilter; ShowSaveFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

◆ ShowOpenFileDialog() [2/2]

void SDL::ShowOpenFileDialog	(	DialogFileCB	callback,
		WindowRef	window,
		std::span< const DialogFileFilter >	filters = {},
		StringParam	default_location = {},
		bool	allow_many = false )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
filters	a list of filters, may be nullptr. See the `DialogFileFilter` documentation for examples]. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-nullptr, it must remain valid at least until the callback is invoked.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.
allow_many	if non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; DialogFileFilter; ShowSaveFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

◆ ShowOpenFolderDialog() [1/2]

void SDL::ShowOpenFolderDialog	(	DialogFileCallback	callback,
		void *	userdata,
		WindowRef	window = {},
		StringParam	default_location = {},
		bool	allow_many = false )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
userdata	an optional pointer to pass extra data to the callback when it will be invoked.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.
allow_many	if non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; ShowOpenFileDialog; ShowSaveFileDialog; ShowFileDialogWithProperties

◆ ShowOpenFolderDialog() [2/2]

void SDL::ShowOpenFolderDialog	(	DialogFileCB	callback,
		WindowRef	window = {},
		StringParam	default_location = {},
		bool	allow_many = false )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.
allow_many	if non-zero, the user will be allowed to select multiple entries. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; ShowOpenFileDialog; ShowSaveFileDialog; ShowFileDialogWithProperties

◆ ShowSaveFileDialog() [1/2]

void SDL::ShowSaveFileDialog	(	DialogFileCallback	callback,
		void *	userdata,
		WindowRef	window = {},
		std::span< const DialogFileFilter >	filters = {},
		StringParam	default_location = {} )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
userdata	an optional pointer to pass extra data to the callback when it will be invoked.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
filters	a list of filters, may be nullptr. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-nullptr, it must remain valid at least until the callback is invoked.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; DialogFileFilter; ShowOpenFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

◆ ShowSaveFileDialog() [2/2]

void SDL::ShowSaveFileDialog	(	DialogFileCB	callback,
		WindowRef	window = {},
		std::span< const DialogFileFilter >	filters = {},
		StringParam	default_location = {} )

inline

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

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 nullptr if an error occurred.

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.

On Linux, dialogs may require XDG Portals, which requires DBus, which requires an event-handling loop. Apps that do not use SDL to handle events should add a call to PumpEvents in their main loop.

Parameters

callback	a function pointer to be invoked when the user selects a file and accepts, or cancels the dialog, or an error occurs.
window	the window that the dialog should be modal for, may be nullptr. Not all platforms support this option.
filters	a list of filters, may be nullptr. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-nullptr, it must remain valid at least until the callback is invoked.
default_location	the default folder or file to start the dialog at, may be nullptr. Not all platforms support this option.

Thread safety:: This function should be called only from the main thread. The callback may be invoked from the same thread or from a different one, depending on the OS's constraints.

Since: This function is available since SDL 3.2.0.

See also: DialogFileCallback; DialogFileFilter; ShowOpenFileDialog; ShowOpenFolderDialog; ShowFileDialogWithProperties

Variable Documentation

◆ FILEDIALOG_OPENFILE

FileDialogType SDL::FILEDIALOG_OPENFILE

constexpr

Initial value:

=

SDL_FILEDIALOG_OPENFILE

OPENFILE.

◆ FILEDIALOG_OPENFOLDER

FileDialogType SDL::FILEDIALOG_OPENFOLDER

constexpr

Initial value:

=

SDL_FILEDIALOG_OPENFOLDER

OPENFOLDER.

◆ FILEDIALOG_SAVEFILE

FileDialogType SDL::FILEDIALOG_SAVEFILE

constexpr

Initial value:

=

SDL_FILEDIALOG_SAVEFILE

SAVEFILE.

Namespaces

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ DialogFileCallback

◆ DialogFileCB

◆ DialogFileFilter

◆ FileDialogType

Function Documentation

◆ ShowFileDialogWithProperties() [1/2]

◆ ShowFileDialogWithProperties() [2/2]

◆ ShowOpenFileDialog() [1/2]

◆ ShowOpenFileDialog() [2/2]

◆ ShowOpenFolderDialog() [1/2]

◆ ShowOpenFolderDialog() [2/2]

◆ ShowSaveFileDialog() [1/2]

◆ ShowSaveFileDialog() [2/2]

Variable Documentation

◆ FILEDIALOG_OPENFILE

◆ FILEDIALOG_OPENFOLDER

◆ FILEDIALOG_SAVEFILE