Native File Dialog Extended

A small C library that portably invokes native file open, folder select and file save dialogs. Write dialog code once and have it pop up native dialogs on all supported platforms. Avoid linking large dependencies like wxWidgets and Qt.

This library is based on Michael Labbe's Native File Dialog (mlabbe/nativefiledialog).

Features:

Lean C API, static library — no C++/ObjC runtime needed
Supports Windows (MSVC, MinGW, Clang), macOS (Clang), and Linux (GTK, portal) (GCC, Clang)
Zlib licensed
Friendly names for filters (e.g. C/C++ Source files (*.c;*.cpp) instead of (*.c;*.cpp)) on platforms that support it
Automatically append file extension on platforms where users expect it
Support for setting a default folder path
Support for setting a default file name (e.g. Untitled.c)
Consistent UTF-8 support on all platforms
Native character set (UTF-16 wchar_t) support on Windows
Initialization and de-initialization of platform library (e.g. COM (Windows) / GTK (Linux GTK) / D-Bus (Linux portal)) decoupled from dialog functions, so applications can choose when to initialize/de-initialize
Multiple selection support (for file open and folder select dialogs)
Support for Vista's modern IFileDialog on Windows
No third party dependencies
Modern CMake build system
Works alongside SDL2 on all platforms
Optional C++ wrapper with unique_ptr auto-freeing semantics and optional parameters, for those using this library from C++

Comparison with original Native File Dialog:

The friendly names feature is the primary reason for breaking API compatibility with Michael Labbe's library (and hence this library probably will never be merged with it). There are also a number of tweaks that cause observable differences in this library.

Features added in Native File Dialog Extended:

Friendly names for filters
Automatically appending file extensions
Support for setting a default file name
Native character set (UTF-16 wchar_t) support on Windows
xdg-desktop-portal support on Linux that opens the "native" file chooser (see "Usage" section below)
Multiple folder selection support
Initialization and de-initialization of platform library decoupled from file dialog functions
Modern CMake build system
Optional C++ wrapper with unique_ptr auto-freeing semantics and optional parameters

There is also significant code refractoring, especially for the Windows implementation.

The wiki keeps track of known language bindings and known popular projects that depend on this library.

Basic Usage

#include <nfd.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    
    NFD_Init();

    nfdu8char_t *outPath;
    nfdu8filteritem_t filters[2] = { { "Source code", "c,cpp,cc" }, { "Headers", "h,hpp" } };
    nfdopendialogu8args_t args = {0};
    args.filterList = filters;
    args.filterCount = 2;
    nfdresult_t result = NFD_OpenDialogU8_With(&outPath, &args);
    if (result == NFD_OKAY)
    {
        puts("Success!");
        puts(outPath);
        NFD_FreePathU8(outPath);
    }
    else if (result == NFD_CANCEL)
    {
        puts("User pressed cancel.");
    }
    else 
    {
        printf("Error: %s\n", NFD_GetError());
    }

    NFD_Quit();
    return 0;
}

The U8/u8 in NFDe refer to the API for UTF-8 characters (char), which most consumers probably want. An N/n version is also available, which uses the native character type (wchar_t on Windows and char on other platforms).

For the full list of arguments that you can set on the args struct, see the "All Options" section below.

If you are using a platform abstraction framework such as SDL or GLFW, also see the "Usage with a Platform Abstraction Framework" section below.

Screenshots

Building

CMake Projects

If your project uses CMake, simply add the following lines to your CMakeLists.txt:

add_subdirectory(path/to/nativefiledialog-extended)
target_link_libraries(MyProgram PRIVATE nfd)

Make sure that you also have the needed dependencies.

When included as a subproject, sample programs are not built and the install target is disabled by default. Add -DNFD_BUILD_TESTS=ON to build sample programs and -DNFD_INSTALL=ON to enable the install target.

Standalone Library

If you want to build the standalone static library, execute the following commands (starting from the project root directory):

For GCC and Clang:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

For MSVC:

mkdir build
cd build
cmake ..
cmake --build . --config Release

The above commands will make a build directory, and build the project (in release mode) there. If you are developing NFDe, you may want to do -DCMAKE_BUILD_TYPE=Debug/--config Debug to build a debug version of the library instead.

When building as a standalone library, sample programs are built and the install target is enabled by default. Add -DNFD_BUILD_TESTS=OFF to disable building sample programs and -DNFD_INSTALL=OFF to disable the install target.

On Linux, if you want to use the Flatpak desktop portal instead of GTK, add -DNFD_PORTAL=ON. (Otherwise, GTK will be used.) See the "Usage" section below for more information.

See the CI build file for some example build commands.

Visual Studio on Windows

Recent versions of Visual Studio have CMake support built into the IDE. You should be able to "Open Folder" in the project root directory, and Visual Studio will recognize and configure the project appropriately. From there, you will be able to set configurations for Debug vs Release, and for x86 vs x64. For more information, see the Microsoft Docs page. This has been tested to work on Visual Studio 2019, and it probably works on Visual Studio 2017 too.

Compiling Your Programs

Add src/include to your include search path.
Add nfd.lib or nfd_d.lib to the list of static libraries to link against (for release or debug, respectively).
Add build/<debug|release>/<arch> to the library search path.

Dependencies

Linux

GTK (default)

Make sure libgtk-3-dev is installed on your system.

Portal

Make sure libdbus-1-dev is installed on your system.

macOS

On macOS, add AppKit and UniformTypeIdentifiers to the list of frameworks.

Windows

On Windows (both MSVC and MinGW), ensure you are building against ole32.lib, uuid.lib, and shell32.lib.

Usage

All Options

To open a dialog, you set options on a struct and then pass that struct to an NFDe function, e.g.:

nfdopendialogu8args_t args = {0};
args.filterList = filters;
args.filterCount = 2;
nfdresult_t result = NFD_OpenDialogU8_With(&outPath, &args);

All options are optional and may be set individually (zero initialization sets all options to reasonable defaults), except for filterList and filterCount which must be either both set or both left unset.

Future versions of NFDe may add additional options to the end of the arguments struct without bumping the major version number, so to ensure backward API compatibility, you should not assume that the struct has a specific length or number of fields. You may assume that zero-initialization of the struct will continue to set all options to reasonable defaults, so assigning {0} to the struct is acceptable. For those building shared libraries of NFDe, backward ABI compatibility is ensured by an internal version index (NFD_INTERFACE_VERSION), which is expected to be transparent to consumers.

OpenDialog/OpenDialogMultiple:

typedef struct {
    const nfdu8filteritem_t* filterList;
    nfdfiltersize_t filterCount;
    const nfdu8char_t* defaultPath;
    nfdwindowhandle_t parentWindow;
} nfdopendialogu8args_t;

SaveDialog:

typedef struct {
    const nfdu8filteritem_t* filterList;
    nfdfiltersize_t filterCount;
    const nfdu8char_t* defaultPath;
    const nfdu8char_t* defaultName;
    nfdwindowhandle_t parentWindow;
} nfdsavedialogu8args_t;

PickFolder/PickFolderMultiple:

typedef struct {
    const nfdu8char_t* defaultPath;
    nfdwindowhandle_t parentWindow;
} nfdpickfolderu8args_t;

filterList and filterCount: Set these to customize the file filter (it appears as a dropdown menu on Windows and Linux, but simply hides files on macOS). Set filterList to a pointer to the start of the array of filter items and filterCount to the number of filter items in that array. See the "File Filter Syntax" section below for details.
defaultPath: Set this to the default folder that the dialog should open to (on Windows, if there is a recently used folder, it opens to that folder instead of the folder you pass, unless the NFD_OVERRIDE_RECENT_WITH_DEFAULT build option is set to ON).
defaultName: (For SaveDialog only) Set this to the file name that should be pre-filled on the dialog.
parentWindow: Set this to the native window handle of the parent of this dialog. See the "Usage with a Platform Abstraction Framework" section for details. It is also possible to pass a handle even if you do not use a platform abstraction framework.

Examples

See the test directory for example code (both C and C++).

If you turned on the option to build the test directory (-DNFD_BUILD_TESTS=ON), then build/bin will contain the compiled test programs.

There is also an SDL2 example, which needs to be enabled separately with -DNFD_BUILD_SDL2_TESTS=ON. It requires SDL2 to be installed on your machine.

Compiled examples (including the SDL2 example) are also uploaded as artefacts to GitHub Actions, and may be downloaded from there.

File Filter Syntax

Files can be filtered by file extension groups:

nfdu8filteritem_t filters[2] = { { "Source code", "c,cpp,cc" }, { "Headers", "h,hpp" } };

A file filter is a pair of strings comprising the friendly name and the specification (multiple file extensions are comma-separated).

A list of file filters can be passed as an argument when invoking the library.

A wildcard filter is always added to every dialog.

Note: On macOS, the file dialogs do not have friendly names and there is no way to switch between filters, so the filter specifications are combined (e.g. "c,cpp,cc,h,hpp"). The filter specification is also never explicitly shown to the user. This is usual macOS behaviour and users expect it.

Note 2: You must ensure that the specification string is non-empty and that every file extension has at least one character. Otherwise, bad things might ensue (i.e. undefined behaviour).

Note 3: On Linux, the file extension is appended (if missing) when the user presses down the "Save" button. The appended file extension will remain visible to the user, even if an overwrite prompt is shown and the user then presses "Cancel".

Note 4: On Windows, the default folder parameter is only used if there is no recently used folder available, unless the NFD_OVERRIDE_RECENT_WITH_DEFAULT build option is set to ON. Otherwise, the default folder will be the folder that was last used. Internally, the Windows implementation calls IFileDialog::SetDefaultFolder(IShellItem). This is usual Windows behaviour and users expect it.

Iterating Over PathSets

A file open dialog that supports multiple selection produces a PathSet, which is a thin abstraction over the platform-specific collection. There are two ways to iterate over a PathSet:

Accessing by index

This method does array-like access on the PathSet, and is the easiest to use. However, on certain platforms (Linux, and possibly Windows), it takes O(N²) time in total to iterate the entire PathSet, because the underlying platform-specific implementation uses a linked list.

See test_opendialogmultiple.c.

Using an enumerator (experimental)

This method uses an enumerator object to iterate the paths in the PathSet. It is guaranteed to take O(N) time in total to iterate the entire PathSet.

See test_opendialogmultiple_enum.c.

This API is experimental, and subject to change.

Customization Macros

You can define the following macros before including nfd.h/nfd.hpp:

NFD_NATIVE: Define this before including nfd.h to make non-suffixed function names and typedefs (e.g. NFD_OpenDialog) aliases for the native functions (e.g. NFD_OpenDialogN) instead of aliases for the UTF-8 functions (e.g. NFD_OpenDialogU8). This macro does not affect the C++ wrapper nfd.hpp.
NFD_THROWS_EXCEPTIONS: (C++ only) Define this before including nfd.hpp to make NFD::Guard construction throw std::runtime_error if NFD_Init fails. Otherwise, there is no way to detect failure in NFD::Guard construction.

Macros that might be defined by nfd.h:

NFD_DIFFERENT_NATIVE_FUNCTIONS: Defined if the native and UTF-8 versions of functions are different (i.e. compiling for Windows); not defined otherwise. If NFD_DIFFERENT_NATIVE_FUNCTIONS is not defined, then the UTF-8 versions of functions are aliases for the native versions. This might be useful if you are writing a function that wants to provide overloads depending on whether the native functions and UTF-8 functions are the same. (Native is UTF-16 (wchar_t) for Windows and UTF-8 (char) for Mac/Linux.)

Usage with a Platform Abstraction Framework

NFDe is known to work with SDL2 and GLFW, and should also work with other platform abstraction framworks. This section explains how to use NFDe properly with such frameworks.

Parent window handle

The parentWindow argument allows the user to give the dialog a parent.

If using SDL2, include <nfd_sdl2.h> and call the following function to set the parent window handle:

NFD_GetNativeWindowFromSDLWindow(sdlWindow /* SDL_Window* */, &args.parentWindow);

If using GLFW3, define the appropriate GLFW_EXPOSE_NATIVE_* macros described on the GLFW native access page, and then include <nfd_glfw3.h> and call the following function to set the parent window handle:

NFD_GetNativeWindowFromGLFWWindow(glfwWindow /* GLFWwindow* */, &args.parentWindow);

If you are using another platform abstraction framework, or not using any such framework, you can set args.parentWindow manually.

Win32 (Windows), Cocoa (macOS), and X11 (Linux) windows are supported. Passing a Wayland (Linux) window currently does nothing (i.e. the dialog acts as if it has no parent), but support is likely to be added in the future.

Why pass a parent window handle?

To make a window (in this case the file dialog) stay above another window, we need to declare the bottom window as the parent of the top window. This keeps the dialog window from disappearing behind the parent window if the user clicks on the parent window while the dialog is open. Keeping the dialog above the window that invoked it is the expected behaviour on all supported operating systems, and so passing the parent window handle is recommended if possible.

Initialization order

You should initialize NFDe after initializing the framework, and probably should deinitialize NFDe before deinitializing the framework. This is because some frameworks expect to be initialized on a "clean slate", and they may configure the system in a different way from NFDe. NFD_Init is generally very careful not to disrupt the existing configuration unless necessary, and NFD_Quit restores the configuration back exactly to what it was before initialization.

An example with SDL2:

// Initialize SDL2 first
if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_AUDIO) != 0) {
    // display some error here
}

// Then initialize NFDe
if (NFD_Init() != NFD_OKAY) {
    // display some error here
}

/*
Your main program goes here
*/

NFD_Quit(); // deinitialize NFDe first

SDL_Quit(); // Then deinitialize SDL2

Using xdg-desktop-portal on Linux

On Linux, you can use the portal implementation instead of GTK, which will open the "native" file chooser selected by the OS or customized by the user. The user must have xdg-desktop-portal and a suitable backend installed (this comes pre-installed with most common desktop distros), otherwise NFD_ERROR will be returned.

To use the portal implementation, add -DNFD_PORTAL=ON to the build command.

*Note: The folder picker is only supported on org.freedesktop.portal.FileChooser interface version >= 3, which corresponds to xdg-desktop-portal version >= 1.7.1. NFD_PickFolder() will query the interface version at runtime, and return NFD_ERROR if the version is too low.

What is a portal?

Unlike Windows and macOS, Linux does not have a file chooser baked into the operating system. Linux applications that want a file chooser usually link with a library that provides one (such as GTK, as in the Linux screenshot above). This is a mostly acceptable solution that many applications use, but may make the file chooser look foreign on non-GTK distros.

Flatpak was introduced in 2015, and with it came a standardized interface to open a file chooser. Applications using this interface did not need to come with a file chooser, and could use the one provided by Flatpak. This interface became known as the desktop portal, and its use expanded to non-Flatpak applications. Now, most major desktop Linux distros come with the desktop portal installed, with file choosers that fit the theme of the distro. Users can also install a different portal backend if desired. There are currently three known backends with file chooser support: GTK, KDE, and LXQt; Gnome and Xapp backends depend on the GTK one for this functionality. The Xapp backend has been designed for Cinnamon, MATE, and XFCE. Other desktop environments do not seem to currently have a portal backend.

Platform-specific Quirks

macOS

If the macOS deployment target is ≥ 11.0, the allowedContentTypes property of NSSavePanel is used instead of the deprecated allowedFileTypes property for file filters. Thus, if you are filtering by a custom file extension specific to your application, you will need to define the data type in your Info.plist file as per the Apple documentation. (It is possible to force NFDe to use allowedFileTypes by adding -DNFD_USE_ALLOWEDCONTENTTYPES_IF_AVAILABLE=OFF to your CMake build command, but this is not recommended. If you need to support older macOS versions, you should be setting the correct deployment target instead.)

Known Limitations

No support for Windows XP's legacy dialogs such as GetOpenFileName. (There are no plans to support this; you shouldn't be still using Windows XP anyway.)
No Emscripten (WebAssembly) bindings. (This might get implemented if I decide to port Circuit Sandbox for the web, but I don't think there is any way to implement a web-based folder picker.)
GTK dialogs don't set the existing window as parent, so if users click the existing window while the dialog is open then the dialog will go behind it. GTK writes a warning to stdout or stderr about this.
This library is not compatible with the original Native File Dialog library. Things might break if you use both in the same project. (There are no plans to support this; you have to use one or the other.)
This library does not explicitly dispatch calls to the UI thread. This may lead to crashes if you call functions from other threads when the platform does not support it (e.g. macOS). Users are generally expected to call NFDe from an appropriate UI thread (i.e. the thread performing the UI event loop).

Reporting Bugs

Please use the GitHub issue tracker to report bugs or to contribute to this repository. Feel free to submit bug reports of any kind.

Credit

Bernard Teo (me) and other contributors for everything that wasn't from Michael Labbe's Native File Dialog.

Michael Labbe for his awesome Native File Dialog library, and the other contributors to that library.

Much of this README has also been copied from the README of original Native File Dialog repository.

License

Everything in this repository is distributed under the ZLib license, as is the original Native File Dialog library.

Support

I don't provide any paid support. Michael Labbe appears to provide paid support for his library at the time of writing.

btzy/nativefiledialog-extended

Native File Dialog Extended

Basic Usage

Screenshots

Building

CMake Projects

Standalone Library

Visual Studio on Windows

Compiling Your Programs

Dependencies

Linux

GTK (default)

Portal

macOS

Windows

Usage

All Options

Examples

File Filter Syntax

Iterating Over PathSets

Accessing by index

Using an enumerator (experimental)

Customization Macros

Usage with a Platform Abstraction Framework

Parent window handle

Why pass a parent window handle?

Initialization order

Using xdg-desktop-portal on Linux

What is a portal?

Platform-specific Quirks

macOS

Known Limitations

Reporting Bugs

Credit

License

Support