On at least Windows and Linux (both GTK and Portal), the dialog misbehaves in a noticeable way when the parent window handle is not passed to the underlying platform-specific API. The macOS (Cocoa) backend guesses the parent from the key window (the window receiving keyboard events). The parent window handle, however, is platform-specific (and on Linux, also specific to the windowing system) (e.g. HWND on Windows, NSWindow* on macOS, Window on X11, wl_surface* on Wayland), which means that NFDe necessarily needs to expose an API that is not fully platform-agnostic, if it is to allow users to pass it the parent window handle.
This is acceptable if the user is not using any platform abstraction framework (e.g. SDL2 or GLFW), since the user must already be writing platform-specific code.
However, a significant benefit of NFDe is realised when the user also uses a platform abstraction framework, as it allows them to write code in a platform-agnostic manner throughout their codebase. It would be unwieldy if they had to write platform-specific code to glue NFDe to their framework.
Platform abstraction frameworks typically define their own type to represent a window handle (e.g SDL_Window* on SDL2, GLFWwindow* on GLFW), and it is possible to get the native window handle from it (via platform-specific APIs). By implementing the conversions from the window type as an optional component of NFDe, it frees the user from having to write their own glue code.
This PR adds a new argument to all the main APIs (OpenFile, OpenFileMultiple, SaveFile, PickFolder, PickFolderMultiple) to take a native window handle, which can be a Windows, macOS, or X11 handle. Wayland is not yet supported as it looks complicated and documentation is scant, though it will probably be implemented in the future. This PR also implements framework-specific window handle conversion functions in optional separate headers.
On at least Windows and Linux (both GTK and Portal), the dialog misbehaves in a noticeable way when the parent window handle is not passed to the underlying platform-specific API. The macOS (Cocoa) backend guesses the parent from the key window (the window receiving keyboard events). The parent window handle, however, is platform-specific (and on Linux, also specific to the windowing system) (e.g.
HWNDon Windows,NSWindow*on macOS,Windowon X11,wl_surface*on Wayland), which means that NFDe necessarily needs to expose an API that is not fully platform-agnostic, if it is to allow users to pass it the parent window handle.This is acceptable if the user is not using any platform abstraction framework (e.g. SDL2 or GLFW), since the user must already be writing platform-specific code.
However, a significant benefit of NFDe is realised when the user also uses a platform abstraction framework, as it allows them to write code in a platform-agnostic manner throughout their codebase. It would be unwieldy if they had to write platform-specific code to glue NFDe to their framework.
Platform abstraction frameworks typically define their own type to represent a window handle (e.g
SDL_Window*on SDL2,GLFWwindow*on GLFW), and it is possible to get the native window handle from it (via platform-specific APIs). By implementing the conversions from the window type as an optional component of NFDe, it frees the user from having to write their own glue code.This PR adds a new argument to all the main APIs (OpenFile, OpenFileMultiple, SaveFile, PickFolder, PickFolderMultiple) to take a native window handle, which can be a Windows, macOS, or X11 handle. Wayland is not yet supported as it looks complicated and documentation is scant, though it will probably be implemented in the future. This PR also implements framework-specific window handle conversion functions in optional separate headers.
Resolves #90. Resolves #126.