SDL_DialogFileCallback

Callback used by file dialog functions.

Header File

Syntax

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

Function 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.

Remarks

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.

Version

This datatype is available since SDL 3.2.0.

Code Examples

#include <SDL3/SDL.h>

static const SDL_DialogFileFilter filters[] = {
    { "PNG images",  "png" },
    { "JPEG images", "jpg;jpeg" },
    { "All images",  "png;jpg;jpeg" },
    { "All files",   "*" }
};

static void SDLCALL callback(void* userdata, const char* const* filelist, int filter)
{
    if (!filelist) {
        SDL_Log("An error occured: %s", SDL_GetError());
        return;
    } else if (!*filelist) {
        SDL_Log("The user did not select any file.");
        SDL_Log("Most likely, the dialog was canceled.");
        return;
    }

    while (*filelist) {
        SDL_Log("Full path to selected file: '%s'", *filelist);
        filelist++;
    }

    if (filter < 0) {
        SDL_Log("The current platform does not support fetching "
                "the selected filter, or the user did not select"
                " any filter.");
    } else if (filter < SDL_arraysize(filters)) {
        SDL_Log("The filter selected by the user is '%s' (%s).",
                filters[filter].pattern, filters[filter].name);
    }
}