New feature: Allow customisation of dialog title, accept label, and cancel label (#180)

This PR makes it possible for clients to customise the dialog title and button labels. This allows clients to be more specific about the kind of file they want the user to select (e.g. "Open Project") or use different languages.
- Windows: All are customisable (if unspecified they fall back to the OS default), except that the cancel label is not customisable before Windows 7
- macOS / Cocoa: Title and accept button are customisable (if unspecified they fall back to the OS default), but the cancel button is not
- Linux / GTK: All are customisable (if unspecified they are hardcoded)
- Linux / Portal: Title and accept button are customisable (title is hardcoded if unspecified, accept button falls back to the OS default if unspecified)

Resolves #99.

Downgrading CMake for Windows Clang is not not possible or necessary, as `windows-latest` is now Windows Server 2025.

Author: btzy

.github/workflows/cmake.yml

@@ -180,8 +180,6 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v4
-    - name: Downgrade CMake # force downgrade CMake as later versions try to use the C++ standard flag to compile C programs, which cause an error.
-      run: choco install cmake --version 3.30.6 --allow-downgrade
     - name: Configure
       run: mkdir build && mkdir install && cd build && cmake -DCMAKE_INSTALL_PREFIX="../install" -T ClangCL -DNFD_BUILD_TESTS=ON ..
     - name: Build

.gitignore

@@ -1,6 +1,7 @@
 # VS CMake default output
 /.vs/
 /out/
+/build/
 /CMakeSettings.json
 
 # Mac OS X rubbish

README.md

@@ -207,6 +207,9 @@ typedef struct {
     nfdfiltersize_t filterCount;
     const nfdu8char_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } nfdopendialogu8args_t;
 ```
 
@@ -218,6 +221,9 @@ typedef struct {
     const nfdu8char_t* defaultPath;
     const nfdu8char_t* defaultName;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } nfdsavedialogu8args_t;
 ```
 
@@ -226,13 +232,19 @@ typedef struct {
 typedef struct {
     const nfdu8char_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } 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 (see the "Platform-specific Quirks" section for more details about the behaviour of this option on Windows).
 - `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.
+- `title`: Set this to customize the title of the dialog window.  If left unset, the operating system's default title (in the user's language) is used on Windows and macOS, while a hardcoded English title (such as "Open File" or "Save File") is used on Linux (GTK and Portal).
+- `acceptLabel`: Set this to customize the text of the accept (confirmation) button, e.g. the "Open" or "Save" button.  If left unset, the operating system's default text (in the user's language) is used, except on Linux (GTK), where a hardcoded English label (such as "Open" or "Save") is used.
+- `cancelLabel`: Set this to customize the text of the cancel button.  If left unset, the operating system's default text (in the user's language) is used, except on Linux (GTK), where the hardcoded English label "Cancel" is used.  *This option is supported on Windows (7 and later) and Linux (GTK); it is ignored on macOS and Linux (Portal), where the cancel button text is not customizable.*
 
 ## Examples
 

src/include/nfd.h

@@ -122,6 +122,9 @@ typedef struct {
     nfdfiltersize_t filterCount;
     const nfdu8char_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } nfdopendialogu8args_t;
 
 #ifdef _WIN32
@@ -130,6 +133,9 @@ typedef struct {
     nfdfiltersize_t filterCount;
     const nfdnchar_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdnchar_t* title;
+    const nfdnchar_t* acceptLabel;
+    const nfdnchar_t* cancelLabel;
 } nfdopendialognargs_t;
 #else
 typedef nfdopendialogu8args_t nfdopendialognargs_t;
@@ -141,6 +147,9 @@ typedef struct {
     const nfdu8char_t* defaultPath;
     const nfdu8char_t* defaultName;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } nfdsavedialogu8args_t;
 
 #ifdef _WIN32
@@ -150,6 +159,9 @@ typedef struct {
     const nfdnchar_t* defaultPath;
     const nfdnchar_t* defaultName;
     nfdwindowhandle_t parentWindow;
+    const nfdnchar_t* title;
+    const nfdnchar_t* acceptLabel;
+    const nfdnchar_t* cancelLabel;
 } nfdsavedialognargs_t;
 #else
 typedef nfdsavedialogu8args_t nfdsavedialognargs_t;
@@ -158,12 +170,18 @@ typedef nfdsavedialogu8args_t nfdsavedialognargs_t;
 typedef struct {
     const nfdu8char_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdu8char_t* title;
+    const nfdu8char_t* acceptLabel;
+    const nfdu8char_t* cancelLabel;
 } nfdpickfolderu8args_t;
 
 #ifdef _WIN32
 typedef struct {
     const nfdnchar_t* defaultPath;
     nfdwindowhandle_t parentWindow;
+    const nfdnchar_t* title;
+    const nfdnchar_t* acceptLabel;
+    const nfdnchar_t* cancelLabel;
 } nfdpickfoldernargs_t;
 #else
 typedef nfdpickfolderu8args_t nfdpickfoldernargs_t;
@@ -172,7 +190,7 @@ typedef nfdpickfolderu8args_t nfdpickfoldernargs_t;
 // This is a unique identifier tagged to all the NFD_*With() function calls, for backward
 // compatibility purposes.  There is usually no need to use this directly, unless you want to use
 // NFD differently depending on the version you're building with.
-#define NFD_INTERFACE_VERSION 1
+#define NFD_INTERFACE_VERSION 2
 
 /** Free a file path that was returned by the dialogs.
  *

src/include/nfd.hpp

@@ -38,17 +38,25 @@ inline nfdresult_t OpenDialog(nfdnchar_t*& outPath,
                               const nfdnfilteritem_t* filterList = nullptr,
                               nfdfiltersize_t filterCount = 0,
                               const nfdnchar_t* defaultPath = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdopendialognargs_t args{filterList, filterCount, defaultPath, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdnchar_t* title = nullptr,
+                              const nfdnchar_t* acceptLabel = nullptr,
+                              const nfdnchar_t* cancelLabel = nullptr) noexcept {
+    const nfdopendialognargs_t args{
+        filterList, filterCount, defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_OpenDialogN_With(&outPath, &args);
 }
 
 inline nfdresult_t OpenDialogMultiple(const nfdpathset_t*& outPaths,
                                       const nfdnfilteritem_t* filterList = nullptr,
                                       nfdfiltersize_t filterCount = 0,
                                       const nfdnchar_t* defaultPath = nullptr,
-                                      nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdopendialognargs_t args{filterList, filterCount, defaultPath, parentWindow};
+                                      nfdwindowhandle_t parentWindow = {},
+                                      const nfdnchar_t* title = nullptr,
+                                      const nfdnchar_t* acceptLabel = nullptr,
+                                      const nfdnchar_t* cancelLabel = nullptr) noexcept {
+    const nfdopendialognargs_t args{
+        filterList, filterCount, defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_OpenDialogMultipleN_With(&outPaths, &args);
 }
 
@@ -57,23 +65,38 @@ inline nfdresult_t SaveDialog(nfdnchar_t*& outPath,
                               nfdfiltersize_t filterCount = 0,
                               const nfdnchar_t* defaultPath = nullptr,
                               const nfdnchar_t* defaultName = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdsavedialognargs_t args{
-        filterList, filterCount, defaultPath, defaultName, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdnchar_t* title = nullptr,
+                              const nfdnchar_t* acceptLabel = nullptr,
+                              const nfdnchar_t* cancelLabel = nullptr) noexcept {
+    const nfdsavedialognargs_t args{filterList,
+                                    filterCount,
+                                    defaultPath,
+                                    defaultName,
+                                    parentWindow,
+                                    title,
+                                    acceptLabel,
+                                    cancelLabel};
     return ::NFD_SaveDialogN_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolder(nfdnchar_t*& outPath,
                               const nfdnchar_t* defaultPath = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdpickfoldernargs_t args{defaultPath, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdnchar_t* title = nullptr,
+                              const nfdnchar_t* acceptLabel = nullptr,
+                              const nfdnchar_t* cancelLabel = nullptr) noexcept {
+    const nfdpickfoldernargs_t args{defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_PickFolderN_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolderMultiple(const nfdpathset_t*& outPaths,
                                       const nfdnchar_t* defaultPath = nullptr,
-                                      nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdpickfoldernargs_t args{defaultPath, parentWindow};
+                                      nfdwindowhandle_t parentWindow = {},
+                                      const nfdnchar_t* title = nullptr,
+                                      const nfdnchar_t* acceptLabel = nullptr,
+                                      const nfdnchar_t* cancelLabel = nullptr) noexcept {
+    const nfdpickfoldernargs_t args{defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_PickFolderMultipleN_With(&outPaths, &args);
 }
 
@@ -117,17 +140,25 @@ inline nfdresult_t OpenDialog(nfdu8char_t*& outPath,
                               const nfdu8filteritem_t* filterList = nullptr,
                               nfdfiltersize_t filterCount = 0,
                               const nfdu8char_t* defaultPath = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdopendialogu8args_t args{filterList, filterCount, defaultPath, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdu8char_t* title = nullptr,
+                              const nfdu8char_t* acceptLabel = nullptr,
+                              const nfdu8char_t* cancelLabel = nullptr) noexcept {
+    const nfdopendialogu8args_t args{
+        filterList, filterCount, defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_OpenDialogU8_With(&outPath, &args);
 }
 
 inline nfdresult_t OpenDialogMultiple(const nfdpathset_t*& outPaths,
                                       const nfdu8filteritem_t* filterList = nullptr,
                                       nfdfiltersize_t filterCount = 0,
                                       const nfdu8char_t* defaultPath = nullptr,
-                                      nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdopendialogu8args_t args{filterList, filterCount, defaultPath, parentWindow};
+                                      nfdwindowhandle_t parentWindow = {},
+                                      const nfdu8char_t* title = nullptr,
+                                      const nfdu8char_t* acceptLabel = nullptr,
+                                      const nfdu8char_t* cancelLabel = nullptr) noexcept {
+    const nfdopendialogu8args_t args{
+        filterList, filterCount, defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_OpenDialogMultipleU8_With(&outPaths, &args);
 }
 
@@ -136,23 +167,38 @@ inline nfdresult_t SaveDialog(nfdu8char_t*& outPath,
                               nfdfiltersize_t filterCount = 0,
                               const nfdu8char_t* defaultPath = nullptr,
                               const nfdu8char_t* defaultName = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdsavedialogu8args_t args{
-        filterList, filterCount, defaultPath, defaultName, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdu8char_t* title = nullptr,
+                              const nfdu8char_t* acceptLabel = nullptr,
+                              const nfdu8char_t* cancelLabel = nullptr) noexcept {
+    const nfdsavedialogu8args_t args{filterList,
+                                     filterCount,
+                                     defaultPath,
+                                     defaultName,
+                                     parentWindow,
+                                     title,
+                                     acceptLabel,
+                                     cancelLabel};
     return ::NFD_SaveDialogU8_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolder(nfdu8char_t*& outPath,
                               const nfdu8char_t* defaultPath = nullptr,
-                              nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdpickfolderu8args_t args{defaultPath, parentWindow};
+                              nfdwindowhandle_t parentWindow = {},
+                              const nfdu8char_t* title = nullptr,
+                              const nfdu8char_t* acceptLabel = nullptr,
+                              const nfdu8char_t* cancelLabel = nullptr) noexcept {
+    const nfdpickfolderu8args_t args{defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_PickFolderU8_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolderMultiple(const nfdpathset_t*& outPaths,
                                       const nfdu8char_t* defaultPath = nullptr,
-                                      nfdwindowhandle_t parentWindow = {}) noexcept {
-    const nfdpickfolderu8args_t args{defaultPath, parentWindow};
+                                      nfdwindowhandle_t parentWindow = {},
+                                      const nfdu8char_t* title = nullptr,
+                                      const nfdu8char_t* acceptLabel = nullptr,
+                                      const nfdu8char_t* cancelLabel = nullptr) noexcept {
+    const nfdpickfolderu8args_t args{defaultPath, parentWindow, title, acceptLabel, cancelLabel};
     return ::NFD_PickFolderMultipleU8_With(&outPaths, &args);
 }