SDL_dialog.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_error.h>`
`#include <SDL3/SDL_properties.h>`
`#include <SDL3/SDL_video.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
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

## Macros

#define | SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters"
#define | SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters"
#define | SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window"
#define | SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location"
#define | SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many"
#define | SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title"
#define | SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept"
#define | SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel"

## Typedefs

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

## Enumerations

enum | SDL_FileDialogType { SDL_FILEDIALOG_OPENFILE , SDL_FILEDIALOG_SAVEFILE , SDL_FILEDIALOG_OPENFOLDER }

## Functions

void | SDL_ShowOpenFileDialog (SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, 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_ShowOpenFolderDialog (SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many)
void | SDL_ShowFileDialogWithProperties (SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props)

## Macro Definition Documentation

## SDL_PROP_FILE_DIALOG_ACCEPT_STRING

#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept"

Definition at line 332 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_CANCEL_STRING

#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel"

Definition at line 333 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_FILTERS_POINTER

#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters"

Definition at line 326 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_LOCATION_STRING

#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location"

Definition at line 329 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_MANY_BOOLEAN

#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many"

Definition at line 330 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER

#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters"

Definition at line 327 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_TITLE_STRING

#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title"

Definition at line 331 of file SDL_dialog.h.

## SDL_PROP_FILE_DIALOG_WINDOW_POINTER

#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window"

Definition at line 328 of file SDL_dialog.h.

## 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 occurred. 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 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 SDL_IOFromFile() 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
  SDL_DialogFileFilter
  SDL_ShowOpenFileDialog
  SDL_ShowSaveFileDialog
  SDL_ShowOpenFolderDialog
  SDL_ShowFileDialogWithProperties

Definition at line 113 of file SDL_dialog.h.

## Enumeration Type Documentation

## SDL_FileDialogType

enum SDL_FileDialogType

Various types of file dialogs.

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

Since
  This enum is available since SDL 3.2.0.

See also
  SDL_ShowFileDialogWithProperties

Enumerator
SDL_FILEDIALOG_OPENFILE |
SDL_FILEDIALOG_SAVEFILE |
SDL_FILEDIALOG_OPENFOLDER |

Definition at line 270 of file SDL_dialog.h.

{
SDL_FILEDIALOG_OPENFILE,
SDL_FILEDIALOG_SAVEFILE,
SDL_FILEDIALOG_OPENFOLDER
} SDL_FileDialogType;
SDL_FileDialogType
SDL_FileDialogType
Definition SDL_dialog.h:271
SDL_FILEDIALOG_SAVEFILE
@ SDL_FILEDIALOG_SAVEFILE
Definition SDL_dialog.h:273
SDL_FILEDIALOG_OPENFILE
@ SDL_FILEDIALOG_OPENFILE
Definition SDL_dialog.h:272
SDL_FILEDIALOG_OPENFOLDER
@ SDL_FILEDIALOG_OPENFOLDER
Definition SDL_dialog.h:274

## Function Documentation

## SDL_ShowFileDialogWithProperties()

void SDL_ShowFileDialogWithProperties | ( | SDL_FileDialogType | type,
|  | SDL_DialogFileCallback | callback,
|  | void * | userdata,
|  | SDL_PropertiesID | props
| ) |  |

extern

Create and launch a file dialog with the specified properties.

These are the supported properties:

- `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of SDL_DialogFileFilter structs, which will be used as filters for file-based selections. Ignored if the dialog is an "Open Folder" dialog. If non-NULL, the array of filters must remain valid at least until the callback is invoked.
- `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the array of filters, if it exists.
- `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should be modal for.
- `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to start the dialog at.
- `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select more than one entry.
- `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog.
- `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button should have.
- `SDL_PROP_FILE_DIALOG_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.

\threadsafety 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
  SDL_FileDialogType
  SDL_DialogFileCallback
  SDL_DialogFileFilter
  SDL_ShowOpenFileDialog
  SDL_ShowSaveFileDialog
  SDL_ShowOpenFolderDialog

## SDL_ShowOpenFileDialog()

void SDL_ShowOpenFileDialog | ( | SDL_DialogFileCallback | callback,
|  | void * | userdata,
|  | SDL_Window * | window,
|  | const SDL_DialogFileFilter * | filters,
|  | int | nfilters,
|  | const char * | default_location,
|  | bool | allow_many
| ) |  |

extern

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 NULL 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 SDL_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 NULL. Not all platforms support this option.
  filters | a list of filters, may be NULL. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-NULL, it must remain valid at least until the callback is invoked.
  nfilters | the number of filters. Ignored if filters is NULL.
  default_location | the default folder or file to start the dialog at, may be NULL. 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.

\threadsafety 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
  SDL_DialogFileCallback
  SDL_DialogFileFilter
  SDL_ShowSaveFileDialog
  SDL_ShowOpenFolderDialog
  SDL_ShowFileDialogWithProperties

## SDL_ShowOpenFolderDialog()

void SDL_ShowOpenFolderDialog | ( | SDL_DialogFileCallback | callback,
|  | void * | userdata,
|  | SDL_Window * | window,
|  | const char * | default_location,
|  | bool | allow_many
| ) |  |

extern

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 NULL 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 SDL_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 NULL. Not all platforms support this option.
  default_location | the default folder or file to start the dialog at, may be NULL. 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.

\threadsafety 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
  SDL_DialogFileCallback
  SDL_ShowOpenFileDialog
  SDL_ShowSaveFileDialog
  SDL_ShowFileDialogWithProperties

## SDL_ShowSaveFileDialog()

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

extern

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 NULL 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 SDL_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 NULL. Not all platforms support this option.
  filters | a list of filters, may be NULL. Not all platforms support this option, and platforms that do support it may allow the user to ignore the filters. If non-NULL, it must remain valid at least until the callback is invoked.
  nfilters | the number of filters. Ignored if filters is NULL.
  default_location | the default folder or file to start the dialog at, may be NULL. Not all platforms support this option.

\threadsafety 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
  SDL_DialogFileCallback
  SDL_DialogFileFilter
  SDL_ShowOpenFileDialog
  SDL_ShowOpenFolderDialog
  SDL_ShowFileDialogWithProperties