Package org.lwjgl.util.nfd

Class NativeFileDialog

java.lang.Object
org.lwjgl.util.nfd.NativeFileDialog
public class NativeFileDialog extends Object
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

  • No support for Windows XP's legacy dialogs such as GetOpenFileName.
  • 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 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).

  • Field Details

    • NFD_ERROR

      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.
      See Also:

    • NFD_OKAY

      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.
      See Also:

    • NFD_CANCEL

      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.
      See Also:

  • Method Details

    • nNFD_FreePath

      public static void nNFD_FreePath(long filePath)
      Unsafe version of: FreePath

    • NFD_FreePath

      public static void NFD_FreePath(ByteBuffer filePath)
      Free a file path that was returned by the dialogs.

    • NFD_FreePath

      public static void NFD_FreePath(long filePath)
      Free a file path that was returned by the dialogs.

    • NFD_Init

      public static int NFD_Init()
      Initialize NFD - call this for every thread that might use NFD, before calling any other NFD functions on that thread.

    • NFD_Quit

      public static void NFD_Quit()
      Call this to de-initialize NFD, if Init returned OKAY.

    • nNFD_OpenDialog

      public static int nNFD_OpenDialog(long outPath, long filterList, int filterCount, long defaultPath)
      Unsafe version of: OpenDialog
      Parameters:
      filterCount - if zero, filterList is ignored (you can use NULL)

    • NFD_OpenDialog

      public static int NFD_OpenDialog(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable ByteBuffer defaultPath)
      Single file open dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • NFD_OpenDialog

      public static int NFD_OpenDialog(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable CharSequence defaultPath)
      Single file open dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • nNFD_OpenDialogMultiple

      public static int nNFD_OpenDialogMultiple(long outPath, long filterList, int filterCount, long defaultPath)
      Unsafe version of: OpenDialogMultiple
      Parameters:
      filterCount - if zero, filterList is ignored (you can use NULL)

    • NFD_OpenDialogMultiple

      public static int NFD_OpenDialogMultiple(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable 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 - if NULL, the operating system will decide

    • NFD_OpenDialogMultiple

      public static int NFD_OpenDialogMultiple(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable 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 - if NULL, the operating system will decide

    • nNFD_SaveDialog

      public static int nNFD_SaveDialog(long outPath, long filterList, int filterCount, long defaultPath, long defaultName)
      Unsafe version of: SaveDialog
      Parameters:
      filterCount - if zero, filterList is ignored (you can use NULL)

    • NFD_SaveDialog

      public static int NFD_SaveDialog(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable ByteBuffer defaultPath, @Nullable ByteBuffer defaultName)
      Save dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • NFD_SaveDialog

      public static int NFD_SaveDialog(PointerBuffer outPath, @Nullable NFDFilterItem.Buffer filterList, @Nullable CharSequence defaultPath, @Nullable CharSequence defaultName)
      Save dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • nNFD_PickFolder

      public static int nNFD_PickFolder(long outPath, long defaultPath)
      Unsafe version of: PickFolder

    • NFD_PickFolder

      public static int NFD_PickFolder(PointerBuffer outPath, @Nullable ByteBuffer defaultPath)
      Select folder dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • NFD_PickFolder

      public static int NFD_PickFolder(PointerBuffer outPath, @Nullable CharSequence defaultPath)
      Select folder dialog.

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

      Parameters:
      defaultPath - if NULL, the operating system will decide

    • nNFD_GetError

      public static long nNFD_GetError()
      Unsafe version of: GetError

    • NFD_GetError

      @Nullable 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.

    • NFD_ClearError

      public static void NFD_ClearError()
      Clear the error

    • nNFD_PathSet_GetCount

      public static int nNFD_PathSet_GetCount(long pathSet, long count)
      Unsafe version of: PathSet_GetCount

    • NFD_PathSet_GetCount

      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.

    • nNFD_PathSet_GetPath

      public static int nNFD_PathSet_GetPath(long pathSet, int index, long outPath)
      Unsafe version of: PathSet_GetPath

    • NFD_PathSet_GetPath

      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.

    • nNFD_PathSet_FreePath

      public static void nNFD_PathSet_FreePath(long filePath)
      Unsafe version of: PathSet_FreePath

    • NFD_PathSet_FreePath

      public static void NFD_PathSet_FreePath(ByteBuffer filePath)
      Free the path gotten by PathSet_GetPath.

    • NFD_PathSet_FreePath

      public static void NFD_PathSet_FreePath(long filePath)
      Free the path gotten by PathSet_GetPath.

    • nNFD_PathSet_GetEnum

      public static int nNFD_PathSet_GetEnum(long pathSet, long outEnumerator)
      Unsafe version of: PathSet_GetEnum

    • NFD_PathSet_GetEnum

      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.

    • nNFD_PathSet_FreeEnum

      public static void nNFD_PathSet_FreeEnum(long enumerator)
      Unsafe version of: PathSet_FreeEnum

    • NFD_PathSet_FreeEnum

      public static void NFD_PathSet_FreeEnum(NFDPathSetEnum enumerator)
      Frees an enumerator of the path set.

    • nNFD_PathSet_EnumNext

      public static int nNFD_PathSet_EnumNext(long enumerator, long outPath)
      Unsafe version of: PathSet_EnumNext

    • NFD_PathSet_EnumNext

      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.

    • nNFD_PathSet_Free

      public static void nNFD_PathSet_Free(long pathSet)
      Unsafe version of: PathSet_Free

    • NFD_PathSet_Free

      public static void NFD_PathSet_Free(long pathSet)
      Free the pathSet.

    • nNFD_PathSet_GetCount

      public static int nNFD_PathSet_GetCount(long pathSet, int[] count)
      Array version of: nNFD_PathSet_GetCount(long, long)

    • NFD_PathSet_GetCount

      public static int NFD_PathSet_GetCount(long pathSet, int[] count)
      Array version of: PathSet_GetCount