README.md
1# Native File Dialog #
2
3A tiny, neat C library that portably invokes native file open and 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.
4
5Features:
6
7 - Lean C API, static library -- no ObjC, no C++, no STL.
8 - Zlib licensed.
9 - Consistent UTF-8 support on all platforms.
10 - Simple universal file filter syntax.
11 - Paid support available.
12 - Multiple file selection support.
13 - 64-bit and 32-bit friendly.
14 - GCC, Clang and Visual Studio supported.
15 - No third party dependencies.
16 - Support for Vista's modern `IFileDialog` on Windows.
17 - Support for non-deprecated Cocoa APIs on OS X.
18 - GTK+3 dialog on Linux.
19 - Tested, works alongside [http://www.libsdl.org](SDL2) on all platforms, for the game developers out there.
20
21# Example Usage #
22
23```C
24#include <nfd.h>
25#include <stdio.h>
26#include <stdlib.h>
27
28int main( void )
29{
30 nfdchar_t *outPath = NULL;
31 nfdresult_t result = NFD_OpenDialog( NULL, NULL, &outPath );
32
33 if ( result == NFD_OKAY ) {
34 puts("Success!");
35 puts(outPath);
36 free(outPath);
37 }
38 else if ( result == NFD_CANCEL ) {
39 puts("User pressed cancel.");
40 }
41 else {
42 printf("Error: %s\n", NFD_GetError() );
43 }
44
45 return 0;
46}
47```
48
49See [NFD.h](src/include/nfd.h) for more options.
50
51# Screenshots #
52
53
54
55
56
57
58## Building ##
59
60NFD uses [SCons](http://www.scons.org) for cross-platform builds. After installing SCons, build it with:
61
62 cd src
63 scons debug=[0,1]
64
65Alternatively, you can avoid Scons by just including NFD files to your existing project:
66
67 1. Add all header files in `src/` and `src/include` to your project.
68 2. Add `src/include` to your include search path or copy it into your existing search path.
69 3. Add `src/nfd_common.c` to your project.
70 4. Add `src/nfd_<platform>` to your project, where `<platform>` is the NFD backend for the platform you are fixing to build.
71 5. On Visual Studio, define `_CRT_SECURE_NO_WARNINGS` to avoid warnings.
72
73### Compiling Your Programs ###
74
75 1. Add `src/include` to your include search path.
76 2. Add `nfd.lib` to the list of list of static libraries to link against.
77 3. Add `src/` to the library search path.
78
79On Linux, you must compile and link against GTK+. Recommend use of `pkg-config --cflags --libs gtk+-3.0`.
80
81On Mac OS X, add `AppKit` to the list of frameworks.
82
83On Windows, ensure you are building against `comctl32.lib`.
84
85## Usage ##
86
87See `NFD.h` for API calls. See `tests/*.c` for example code.
88
89See `tests/SConstruct` for a working build script that compiles on all platforms.
90
91## File Filter Syntax ##
92
93There is a form of file filtering in every file dialog, but no consistent means of supporting it. NFD provides support for filtering files by groups of extensions, providing its own descriptions (where applicable) for the extensions.
94
95A wildcard filter is always added to every dialog.
96
97### Separators ###
98
99 - `;` Begin a new filter.
100 - `,` Add a separate type to the filter.
101
102#### Examples ####
103
104`txt` The default filter is for text files. There is a wildcard option in a dropdown.
105
106`png,jpg;psd` The default filter is for png and jpg files. A second filter is available for psd files. There is a wildcard option in a dropdown.
107
108`NULL` Wildcard only.
109
110## Iterating Over PathSets ##
111
112See [test_opendialogmultiple.c](test/test_opendialogmultiple.c).
113
114# Known Limitations #
115
116I accept quality code patches, or will resolve these and other matters through support.
117
118 - No support for Windows XP's legacy dialogs such as `GetOpenFileName`.
119 - No support for file filter names -- ex: "Image Files" (*.png, *.jpg). Nameless filters are supported, though.
120 - No support for selecting folders instead of files.
121 - On Linux, GTK+ cannot be uninitialized to save memory. Launching a file dialog costs memory. I am open to accepting an alternative `nfd_zenity.c` implementation which uses Zenity and pipes.
122
123# Copyright and Credit #
124
125Copyright © 2014 [Frogtoss Games](http://www.frogtoss.com), Inc.
126File [LICENSE](LICENSE) covers all files in this repo.
127
128Native File Dialog by Michael Labbe
129<mike@frogtoss.com>
130
131Tomasz Konojacki for [microutf8](http://puszcza.gnu.org.ua/software/microutf8/)
132
133## Support ##
134
135Directed support for this work is available from the original author under a paid agreement.
136
137[Contact Frogtoss Games](http://www.frogtoss.com/pages/contact.html).
138
