Top Description Fields Constructors Methods
org.lwjgl.util.nfd

public Class NativeFileDialog

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.*, org.lwjgl.system.*
Bindings to 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.

Usage

File Filter Syntax

Files can be filtered by file extension groups:


nfdfilteritem_t filterItem[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. 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(N2) time in total to iterate the entire PathSet, because the underlying platform-specific implementation uses a linked list.

Using an enumerator

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.

Usage with a Platform Abstraction Framework

NFDe is known to work with SDL2 and GLFW, and should also work with other platform abstraction framworks. However, 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. Init is generally very careful not to disrupt the existing configuration unless necessary, and Quit restores the configuration back exactly to what it was before initialization.

Known Limitations

Field Summary

Modifier and TypeField and Description
public static final int
NFD_CANCEL

Result values.

public static final int
NFD_ERROR

Result values.

public static final int
NFD_OKAY

Result values.

Constructor Summary

AccessConstructor and Description
protected
NativeFileDialog()

Method Summary

Modifier and TypeMethod and Description
public static native void
NFD_ClearError()

Clear the error

public static void
NFD_FreePath(ByteBuffer filePath)

Free a file path that was returned by the dialogs.

public static void
NFD_FreePath(long filePath)

Free a file path that was returned by the dialogs.

public static String
NFD_GetError()

Get last error -- set when nfdresult_t returns ERROR.

public static native int
NFD_Init()

Initialize NFD - call this for every thread that might use NFD, before calling any other NFD functions on that thread.

public static int
NFD_OpenDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer
if NULL, the operating system will decide
defaultPath)

Single file open dialog.

public static int
NFD_OpenDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence
if NULL, the operating system will decide
defaultPath)

Single file open dialog.

public static int
NFD_OpenDialogMultiple(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer
if NULL, the operating system will decide
defaultPath)

Multiple file open dialog.

public static int
NFD_OpenDialogMultiple(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence
if NULL, the operating system will decide
defaultPath)

Multiple file open dialog.

public static int
NFD_PathSet_EnumNext(NFDPathSetEnum enumerator, PointerBuffer outPath)

Gets the next item from the path set enumerator.

public static void
NFD_PathSet_Free(long pathSet)

Free the pathSet.

public static void
NFD_PathSet_FreeEnum(NFDPathSetEnum enumerator)

Frees an enumerator of the path set.

public static void
NFD_PathSet_FreePath(ByteBuffer filePath)

Free the path gotten by PathSet_GetPath.

public static void
NFD_PathSet_FreePath(long filePath)

Free the path gotten by PathSet_GetPath.

public static int
NFD_PathSet_GetCount(long pathSet, IntBuffer count)

Gets the number of entries stored in pathSet.

public static int
NFD_PathSet_GetCount(long pathSet, int[] count)

Array version of: PathSet_GetCount

public static int
NFD_PathSet_GetEnum(long pathSet, NFDPathSetEnum outEnumerator)

Gets an enumerator of the path set.

public static int
NFD_PathSet_GetPath(long pathSet, int index, PointerBuffer outPath)

Gets the UTF-8 path at offset index.

public static int
NFD_PickFolder(PointerBuffer outPath, ByteBuffer
if NULL, the operating system will decide
defaultPath)

Select folder dialog.

public static int
NFD_PickFolder(PointerBuffer outPath, CharSequence
if NULL, the operating system will decide
defaultPath)

Select folder dialog.

public static native void
NFD_Quit()

Call this to de-initialize NFD, if Init returned OKAY.

public static int
NFD_SaveDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer
if NULL, the operating system will decide
defaultPath, ByteBuffer defaultName)

Save dialog.

public static int
NFD_SaveDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence
if NULL, the operating system will decide
defaultPath, CharSequence defaultName)

Save dialog.

public static native void
nNFD_FreePath(long filePath)

Unsafe version of: FreePath

public static native long
nNFD_GetError()

Unsafe version of: GetError

public static native int
nNFD_OpenDialog(long outPath, long filterList, int
if zero, filterList is ignored (you can use NULL)
filterCount, long defaultPath)

Unsafe version of: OpenDialog

public static native int
nNFD_OpenDialogMultiple(long outPath, long filterList, int
if zero, filterList is ignored (you can use NULL)
filterCount, long defaultPath)

Unsafe version of: OpenDialogMultiple

public static native int
nNFD_PathSet_EnumNext(long enumerator, long outPath)

Unsafe version of: PathSet_EnumNext

public static native void
nNFD_PathSet_Free(long pathSet)

Unsafe version of: PathSet_Free

public static native void
nNFD_PathSet_FreeEnum(long enumerator)

Unsafe version of: PathSet_FreeEnum

public static native void
nNFD_PathSet_FreePath(long filePath)

Unsafe version of: PathSet_FreePath

public static native int
nNFD_PathSet_GetCount(long pathSet, long count)

Unsafe version of: PathSet_GetCount

public static native int
nNFD_PathSet_GetCount(long pathSet, int[] count)

Array version of: nNFD_PathSet_GetCount

public static native int
nNFD_PathSet_GetEnum(long pathSet, long outEnumerator)

Unsafe version of: PathSet_GetEnum

public static native int
nNFD_PathSet_GetPath(long pathSet, int index, long outPath)

Unsafe version of: PathSet_GetPath

public static native int
nNFD_PickFolder(long outPath, long defaultPath)

Unsafe version of: PickFolder

public static native int
nNFD_SaveDialog(long outPath, long filterList, int
if zero, filterList is ignored (you can use NULL)
filterCount, long defaultPath, long defaultName)

Unsafe version of: SaveDialog

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

NFD_CANCELback to summary
public static final int NFD_CANCEL

Result values. (nfdresult_t)

Enum values:
  • ERROR - Programmatic error.
  • OKAY - User pressed okay, or successful return.
  • CANCEL - User pressed cancel.
NFD_ERRORback to summary
public static final int NFD_ERROR

Result values. (nfdresult_t)

Enum values:
  • ERROR - Programmatic error.
  • OKAY - User pressed okay, or successful return.
  • CANCEL - User pressed cancel.
NFD_OKAYback to summary
public static final int NFD_OKAY

Result values. (nfdresult_t)

Enum values:
  • ERROR - Programmatic error.
  • OKAY - User pressed okay, or successful return.
  • CANCEL - User pressed cancel.

Constructor Detail

NativeFileDialogback to summary
protected NativeFileDialog()

Method Detail

NFD_ClearErrorback to summary
public static native void NFD_ClearError()

Clear the error

NFD_FreePathback to summary
public static void NFD_FreePath(ByteBuffer filePath)

Free a file path that was returned by the dialogs.

NFD_FreePathback to summary
public static void NFD_FreePath(long filePath)

Free a file path that was returned by the dialogs.

NFD_GetErrorback to summary
public static String NFD_GetError()

Get last error -- set when nfdresult_t returns ERROR.

Returns the last error that was set, or NULL if there is no error. The memory is owned by NFD and should not be freed by user code. This is always ASCII printable characters, so it can be interpreted as UTF-8 without any conversion.

Annotations
@Nullable
@NativeType:char const *
NFD_Initback to summary
public static native int NFD_Init()

Initialize NFD - call this for every thread that might use NFD, before calling any other NFD functions on that thread.

Annotations
@NativeType:nfdresult_t
NFD_OpenDialogback to summary
public static int NFD_OpenDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer defaultPath)

Single file open dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:ByteBuffer

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_OpenDialogback to summary
public static int NFD_OpenDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence defaultPath)

Single file open dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:CharSequence

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_OpenDialogMultipleback to summary
public static int NFD_OpenDialogMultiple(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer defaultPath)

Multiple file open dialog.

It is the caller's responsibility to free outPaths via PathSet_Free if this function returns OKAY.

Parameters
defaultPath:ByteBuffer

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_OpenDialogMultipleback to summary
public static int NFD_OpenDialogMultiple(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence defaultPath)

Multiple file open dialog.

It is the caller's responsibility to free outPaths via PathSet_Free if this function returns OKAY.

Parameters
defaultPath:CharSequence

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_PathSet_EnumNextback to summary
public static int NFD_PathSet_EnumNext(NFDPathSetEnum enumerator, PointerBuffer outPath)

Gets the next item from the path set enumerator.

If there are no more items, then *outPaths will be set to NULL.

It is the caller's responsibility to free *outPath via PathSet_FreePath if this function returns OKAY and *outPath is not null.

Annotations
@NativeType:nfdresult_t
NFD_PathSet_Freeback to summary
public static void NFD_PathSet_Free(long pathSet)

Free the pathSet.

NFD_PathSet_FreeEnumback to summary
public static void NFD_PathSet_FreeEnum(NFDPathSetEnum enumerator)

Frees an enumerator of the path set.

NFD_PathSet_FreePathback to summary
public static void NFD_PathSet_FreePath(ByteBuffer filePath)

Free the path gotten by PathSet_GetPath.

NFD_PathSet_FreePathback to summary
public static void NFD_PathSet_FreePath(long filePath)

Free the path gotten by PathSet_GetPath.

NFD_PathSet_GetCountback to summary
public static int NFD_PathSet_GetCount(long pathSet, IntBuffer count)

Gets the number of entries stored in pathSet.

Note that some paths might be invalid (ERROR will be returned by PathSet_GetPath), so we might not actually have this number of usable paths.

Annotations
@NativeType:nfdresult_t
NFD_PathSet_GetCountback to summary
public static int NFD_PathSet_GetCount(long pathSet, int[] count)

Array version of: PathSet_GetCount

Annotations
@NativeType:nfdresult_t
NFD_PathSet_GetEnumback to summary
public static int NFD_PathSet_GetEnum(long pathSet, NFDPathSetEnum outEnumerator)

Gets an enumerator of the path set.

It is the caller's responsibility to free enumerator via PathSet_FreeEnum if this function returns OKAY, and it should be freed before freeing the pathset.

Annotations
@NativeType:nfdresult_t
NFD_PathSet_GetPathback to summary
public static int NFD_PathSet_GetPath(long pathSet, int index, PointerBuffer outPath)

Gets the UTF-8 path at offset index.

It is the caller's responsibility to free outPath via PathSet_FreePath if this function returns OKAY.

Annotations
@NativeType:nfdresult_t
NFD_PickFolderback to summary
public static int NFD_PickFolder(PointerBuffer outPath, ByteBuffer defaultPath)

Select folder dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:ByteBuffer

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_PickFolderback to summary
public static int NFD_PickFolder(PointerBuffer outPath, CharSequence defaultPath)

Select folder dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:CharSequence

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_Quitback to summary
public static native void NFD_Quit()

Call this to de-initialize NFD, if Init returned OKAY.

NFD_SaveDialogback to summary
public static int NFD_SaveDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, ByteBuffer defaultPath, ByteBuffer defaultName)

Save dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:ByteBuffer

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
NFD_SaveDialogback to summary
public static int NFD_SaveDialog(PointerBuffer outPath, NFDFilterItem.Buffer filterList, CharSequence defaultPath, CharSequence defaultName)

Save dialog.

It is the caller's responsibility to free outPath via FreePath if this function returns OKAY.

Parameters
defaultPath:CharSequence

if NULL, the operating system will decide

Annotations
@NativeType:nfdresult_t
nNFD_FreePathback to summary
public static native void nNFD_FreePath(long filePath)

Unsafe version of: FreePath

nNFD_GetErrorback to summary
public static native long nNFD_GetError()

Unsafe version of: GetError

nNFD_OpenDialogback to summary
public static native int nNFD_OpenDialog(long outPath, long filterList, int filterCount, long defaultPath)

Unsafe version of: OpenDialog

Parameters
filterCount:int

if zero, filterList is ignored (you can use NULL)

nNFD_OpenDialogMultipleback to summary
public static native int nNFD_OpenDialogMultiple(long outPath, long filterList, int filterCount, long defaultPath)

Unsafe version of: OpenDialogMultiple

Parameters
filterCount:int

if zero, filterList is ignored (you can use NULL)

nNFD_PathSet_EnumNextback to summary
public static native int nNFD_PathSet_EnumNext(long enumerator, long outPath)

Unsafe version of: PathSet_EnumNext

nNFD_PathSet_Freeback to summary
public static native void nNFD_PathSet_Free(long pathSet)

Unsafe version of: PathSet_Free

nNFD_PathSet_FreeEnumback to summary
public static native void nNFD_PathSet_FreeEnum(long enumerator)

Unsafe version of: PathSet_FreeEnum

nNFD_PathSet_FreePathback to summary
public static native void nNFD_PathSet_FreePath(long filePath)

Unsafe version of: PathSet_FreePath

nNFD_PathSet_GetCountback to summary
public static native int nNFD_PathSet_GetCount(long pathSet, long count)

Unsafe version of: PathSet_GetCount

nNFD_PathSet_GetCountback to summary
public static native int nNFD_PathSet_GetCount(long pathSet, int[] count)

Array version of: nNFD_PathSet_GetCount

nNFD_PathSet_GetEnumback to summary
public static native int nNFD_PathSet_GetEnum(long pathSet, long outEnumerator)

Unsafe version of: PathSet_GetEnum

nNFD_PathSet_GetPathback to summary
public static native int nNFD_PathSet_GetPath(long pathSet, int index, long outPath)

Unsafe version of: PathSet_GetPath

nNFD_PickFolderback to summary
public static native int nNFD_PickFolder(long outPath, long defaultPath)

Unsafe version of: PickFolder

nNFD_SaveDialogback to summary
public static native int nNFD_SaveDialog(long outPath, long filterList, int filterCount, long defaultPath, long defaultName)

Unsafe version of: SaveDialog

Parameters
filterCount:int

if zero, filterList is ignored (you can use NULL)