Description
GtkFileChooserNative is an abstraction of a dialog box 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 certain 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 GtkNativeDialog functions.
Typical usage
In the simplest of cases, you can the following code to use
GtkFileChooserDialog to select a file for opening:
To use a dialog for saving, you can use this:
For more information on how to best set up a file dialog, see GtkFileChooserDialog.
There are a few things in the GtkFileChooser API that are not
possible to use with GtkFileChooserNative, as such use would
prohibit the use of a native dialog.
There is no support for the signals that are emitted when the user
navigates in the dialog, including:
You can also not use the methods that directly control user navigation:
gtk_file_chooser_unselect_filename()
gtk_file_chooser_select_all()
gtk_file_chooser_unselect_all()
If you need any of the above you will have to use GtkFileChooserDialog directly.
No operations that change the 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 GtkFileChooserDialog
does, but there are some things it does not handle:
If any of these features are used the regular GtkFileChooserDialog
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. In this situation, the following things are not
supported and will be silently ignored:
macOS details
On macOS the NSSavePanel and NSOpenPanel classes are used to provide native
file chooser dialogs. Some features provided by GtkFileChooserDialog are
not supported:
Extra widgets added with gtk_file_chooser_set_extra_widget(), unless the
widget is an instance of GtkLabel, in which case the label text will be used
to set the NSSavePanel message instance property.
Use of custom previews by connecting to “update-preview”.
Any GtkFileFilter added with a custom filter.
Shortcut folders.
Functions
gtk_file_chooser_native_new ()
GtkFileChooserNative *
gtk_file_chooser_native_new (const gchar *title,
GtkWindow *parent,
GtkFileChooserAction action,
const gchar *accept_label,
const gchar *cancel_label);
Creates a new GtkFileChooserNative.
Returns
a new GtkFileChooserNative
Since: 3.20
gtk_file_chooser_native_get_accept_label ()
const char *
gtk_file_chooser_native_get_accept_label
(GtkFileChooserNative *self);
Retrieves the custom label text for the accept button.
Returns
The custom label, or NULL for the default. This string
is owned by GTK+ and should not be modified or freed.
[nullable]
Since: 3.20
gtk_file_chooser_native_set_accept_label ()
void
gtk_file_chooser_native_set_accept_label
(GtkFileChooserNative *self,
const char *accept_label);
Sets the custom label text for the accept button.
If characters in label
are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.
Since: 3.20
gtk_file_chooser_native_get_cancel_label ()
const char *
gtk_file_chooser_native_get_cancel_label
(GtkFileChooserNative *self);
Retrieves the custom label text for the cancel button.
Returns
The custom label, or NULL for the default. This string
is owned by GTK+ and should not be modified or freed.
[nullable]
Since: 3.20
gtk_file_chooser_native_set_cancel_label ()
void
gtk_file_chooser_native_set_cancel_label
(GtkFileChooserNative *self,
const char *cancel_label);
Sets the custom label text for the cancel button.
If characters in label
are preceded by an underscore, they are underlined.
If you need a literal underscore character in a label, use “__” (two
underscores). The first underlined character represents a keyboard
accelerator called a mnemonic.
Pressing Alt and that key activates the button.
Since: 3.20