Native File Dialog (NFD)

To integrate NFD into your C/C++ project, follow these steps:

1. Include Path: Add src/include to your compiler's include search path.
2. Library Path: Add the directory containing the built library (e.g., build/release/x64) to your library search path.
3. Linking: Link against nfd.lib (for release) or nfd_d.lib (for debug).

Platform-specific requirements:

• Linux (GTK3): Install libgtk-3-dev. When compiling, include the flags from pkg-config --cflags --libs gtk+-3.0.
• Linux (Zenity): Use the Zenity backend by running the Makefile in build/gmake_linux_zenity. This requires Zenity to be installed on the system.
• MacOS: Link against the AppKit framework.
• Windows: Ensure you link against comctl32.lib.

NFD uses Premake5 to generate build files. You can build the library using make with different configuration options for architecture and build type. The default is release_x64.

Available configurations:

• make config=release_x86
• make config=release_x64
• make config=debug_x86
• make config=debug_x64

Build outputs:

• Release builds: nfd.a (or nfd.lib on Windows)
• Debug builds: nfd_d.a (or nfd_d.lib on Windows)

To build Native File Dialog using the Mingw toolchain on Windows, use the Makefile located in build/gmake_windows. It is recommended to use mingw64 rather than mingw32.

Follow these steps:

1. Install mingw64 (including the basic compiler and g++).
2. Add the Mingw bin directory to your system PATH.
3. Set the compiler environment variable: set CC=g++.
4. Navigate to build/gmake_windows.
5. Run mingw32-make config=release_x64 clean to prevent conflicts with Visual Studio build products.
6. Run mingw32-make config=release_x64 to build.

If you encounter issues, run make with verbose=1 to see the full command output for debugging.

set CC=g++
cd build/gmake_windows
mingw32-make config=release_x64 clean
mingw32-make config=release_x64

When using NFD, be aware of the following constraints:

• Windows: No support for legacy Windows XP dialogs (e.g., GetOpenFileName).
• Filters: Does not support custom filter names (e.g., you cannot specify "Image Files" as a label; only the extensions are used).
• Linux (Zenity): The Zenity backend's error handling for process execution is not graceful and may abort the process instead of returning an error code.
• Linux (GTK3): One warning is emitted per dialog created.

To open a standard file open dialog, use NFD_OpenDialog. This function returns an nfdresult_t indicating success, cancellation, or error. If successful, it populates a pointer to an nfdchar_t containing the selected file path.

Important: You must manually free() the outPath pointer if the result is NFD_OKAY to avoid memory leaks.

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

int main( void )
{
    nfdchar_t *outPath = NULL;
    nfdresult_t result = NFD_OpenDialog( NULL, NULL, &outPath );
        
    if ( result == NFD_OKAY ) {
        puts("Success!");
        puts(outPath);
        free(outPath);
    }
    else if ( result == NFD_CANCEL ) {
        puts("User pressed cancel.");
    }
    else {
        printf("Error: %s\n", NFD_GetError() );
    }

    return 0;
}

NFD uses a simple syntax to define file filters. A wildcard filter is always included by default. You can group extensions and create multiple filter options using specific separators:

• ; (Semicolon): Begins a new filter group.
• , (Comma): Adds a separate file type to the current filter group.

Examples:

• txt: Only text files (plus wildcard).
• png,jpg;psd: First filter group is png and jpg; second filter group is psd.
• NULL: Only the wildcard option is available.