`GtkFileChooserNative` is an abstraction of a dialog suitable for use with “File Open” or “File Save as” commands.
By default, this just uses a `GtkFileChooserDialog` to implement the actual dialog. However, on some platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), `GtkFileChooserNative` may call the proper APIs (portals) to let the user choose a file and make it available to the application.
While the API of `GtkFileChooserNative` closely mirrors `GtkFileChooserDialog`, the main difference is that there is no access to any `GtkWindow` or `GtkWidget` for the dialog. This is required, as there may not be one in the case of a platform native dialog.
Showing, hiding and running the dialog is handled by the [[email protected]] functions.
Note that unlike `GtkFileChooserDialog`, `GtkFileChooserNative` objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object.
In the simplest of cases, you can the following code to use `GtkFileChooserNative` to select a file for opening:
```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser);
open_file (file);
g_object_unref (file); }
g_object_unref (native); }
// ... GtkFileChooserNative *native; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
native = gtk_file_chooser_native_new ("Open File", parent_window, action, "_Open", "_Cancel");
g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ```
To use a `GtkFileChooserNative` for saving, you can use this:
```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser);
save_to_file (file);
g_object_unref (file); }
g_object_unref (native); }
// ... GtkFileChooserNative *native; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
native = gtk_file_chooser_native_new ("Save File", parent_window, action, "_Save", "_Cancel"); chooser = GTK_FILE_CHOOSER (native);
if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file ( chooser, existing_file, NULL);
g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ```
For more information on how to best set up a file dialog, see the [[email protected]] documentation.
`GtkFileChooserNative` inherits from [[email protected]], which means it will return gtk_response_accept if the user accepted, and gtk_response_cancel if he pressed cancel. It can also return gtk_response_delete_event if the window was unexpectedly closed.
There are a few things in the [[email protected]] interface that are not possible to use with `GtkFileChooserNative`, as such use would prohibit the use of a native dialog.
No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.
On windows the `IFileDialog` implementation (added in Windows Vista) is used. It supports many of the features that `GtkFileChooser` has, but there are some things it does not handle:
* Any [[email protected]] added using a mimetype
If any of these features are used the regular `GtkFileChooserDialog` will be used in place of the native one.
When the `org.freedesktop.portal.FileChooser` portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK file chooser.
On macOS the `NSSavePanel` and `NSOpenPanel` classes are used to provide native file chooser dialogs. Some features provided by `GtkFileChooser` are not supported:
* Shortcut folders.