gtk.file_chooser_native

[gtk.file_chooser_native.FileChooserNative] is an abstraction of a dialog suitable for use with “File Open” or “File Save as” commands.

By default, this just uses a [gtk.file_chooser_dialog.FileChooserDialog] 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), [gtk.file_chooser_native.FileChooserNative] may call the proper APIs (portals) to let the user choose a file and make it available to the application.

While the API of [gtk.file_chooser_native.FileChooserNative] closely mirrors [gtk.file_chooser_dialog.FileChooserDialog], the main difference is that there is no access to any [gtk.window.Window] or [gtk.widget.Widget] 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 [gtk.native_dialog.NativeDialog] functions.

Note that unlike [gtk.file_chooser_dialog.FileChooserDialog], [gtk.file_chooser_native.FileChooserNative] 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.

Typical usage

In the simplest of cases, you can the following code to use [gtk.file_chooser_native.FileChooserNative] to select a file for opening:

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 [gtk.file_chooser_native.FileChooserNative] for saving, you can use this:

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 [gtk.file_chooser_dialog.FileChooserDialog] documentation.

Response Codes

[gtk.file_chooser_native.FileChooserNative] inherits from [gtk.native_dialog.NativeDialog], which means it will return [gtk.types.ResponseType.Accept] if the user accepted, and [gtk.types.ResponseType.Cancel] if he pressed cancel. It can also return [gtk.types.ResponseType.DeleteEvent] if the window was unexpectedly closed.

Differences from [gtk.file_chooser_dialog.FileChooserDialog]

There are a few things in the [gtk.file_chooser.FileChooser] interface that are not possible to use with [gtk.file_chooser_native.FileChooserNative], 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.

Win32 details

On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that [gtk.file_chooser.FileChooser] has, but there are some things it does not handle:

• Any [gtk.file_filter.FileFilter] added using a mimetype

If any of these features are used the regular [gtk.file_chooser_dialog.FileChooserDialog] will be used in place of the native one.

Portal details

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.

macOS details

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by [gtk.file_chooser.FileChooser] are not supported:

• Shortcut folders.

Fluent builder for [gtk.file_chooser_native.FileChooserNative]