FileChooserNative

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 [class@Gtk.NativeDialog] 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.

Typical usage

In the simplest of cases, you can the following code to use GtkFileChooserNative 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 GtkFileChooserNative 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 [class@Gtk.FileChooserDialog] documentation.

Response Codes

GtkFileChooserNative inherits from [class@Gtk.NativeDialog], 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.

Differences from #GtkFileChooserDialog

There are a few things in the [iface@Gtk.FileChooser] 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.

Win32 details

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 [class@Gtk.FileFilter] added using a mimetype

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.

macOS details

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.

class FileChooserNative : NativeDialog , FileChooserIF {

protected

GtkFileChooserNative* gtkFileChooserNative;

GtkFileChooserNative* getFileChooserNativeStruct(bool transferOwnership);

void* getStruct();

this(GtkFileChooserNative* gtkFileChooserNative, bool ownedRef);

mixin FileChooserT!(GtkFileChooserNative) ;

static GType getType();

this(string title, Window parent, GtkFileChooserAction action, string acceptLabel, string cancelLabel);

string getAcceptLabel();

string getCancelLabel();

void setAcceptLabel(string acceptLabel);

void setCancelLabel(string cancelLabel);

}

Constructors

this this(GtkFileChooserNative* gtkFileChooserNative, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string title, Window parent, GtkFileChooserAction action, string acceptLabel, string cancelLabel): Creates a new GtkFileChooserNative.

Members

Functions

getAcceptLabel string getAcceptLabel(): Retrieves the custom label text for the accept button.
getCancelLabel string getCancelLabel(): Retrieves the custom label text for the cancel button.
getFileChooserNativeStruct GtkFileChooserNative* getFileChooserNativeStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
setAcceptLabel void setAcceptLabel(string acceptLabel): Sets the custom label text for the accept button.
setCancelLabel void setCancelLabel(string cancelLabel): Sets the custom label text for the cancel button.

Mixins

__anonymous mixin FileChooserT!(GtkFileChooserNative): Undocumented in source.

Static functions

getType GType getType()

Variables

gtkFileChooserNative GtkFileChooserNative* gtkFileChooserNative;: the main Gtk struct

Inherited Members

From NativeDialog

gtkNativeDialog GtkNativeDialog* gtkNativeDialog;: the main Gtk struct
getNativeDialogStruct GtkNativeDialog* getNativeDialogStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
getType GType getType()
destroy void destroy(): Destroys a dialog.
getModal bool getModal(): Returns whether the dialog is modal.
getTitle string getTitle(): Gets the title of the GtkNativeDialog.
getTransientFor Window getTransientFor(): Fetches the transient parent for this window.
getVisible bool getVisible(): Determines whether the dialog is visible.
hide void hide(): Hides the dialog if it is visible, aborting any interaction.
setModal void setModal(bool modal): Sets a dialog modal or non-modal.
setTitle void setTitle(string title): Sets the title of the GtkNativeDialog.
setTransientFor void setTransientFor(Window parent): Dialog windows should be set transient for the main application window they were spawned from.
show void show(): Shows the dialog on the display.
addOnResponse gulong addOnResponse(void delegate(int, NativeDialog) dlg, ConnectFlags connectFlags): Emitted when the user responds to the dialog.

From FileChooserIF

getFileChooserStruct GtkFileChooser* getFileChooserStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
getType GType getType()
addChoice void addChoice(string id, string label, string[] options, string[] optionLabels): Adds a 'choice' to the file chooser.
addFilter void addFilter(FileFilter filter): Adds @filter to the list of filters that the user can select between.
addShortcutFolder bool addShortcutFolder(FileIF folder): Adds a folder to be displayed with the shortcut folders in a file chooser.
getAction GtkFileChooserAction getAction(): Gets the type of operation that the file chooser is performing.
getChoice string getChoice(string id): Gets the currently selected option in the 'choice' with the given ID.
getCreateFolders bool getCreateFolders(): Gets whether file chooser will offer to create new folders.
getCurrentFolder FileIF getCurrentFolder(): Gets the current folder of @chooser as #GFile.
getCurrentName string getCurrentName(): Gets the current name in the file selector, as entered by the user.
getFile FileIF getFile(): Gets the GFile for the currently selected file in the file selector.
getFiles ListModelIF getFiles(): Lists all the selected files and subfolders in the current folder of @chooser as #GFile.
getFilter FileFilter getFilter(): Gets the current filter.
getFilters ListModelIF getFilters(): Gets the current set of user-selectable filters, as a list model.
getSelectMultiple bool getSelectMultiple(): Gets whether multiple files can be selected in the file chooser.
getShortcutFolders ListModelIF getShortcutFolders(): Queries the list of shortcut folders in the file chooser.
removeChoice void removeChoice(string id): Removes a 'choice' that has been added with gtk_file_chooser_add_choice().
removeFilter void removeFilter(FileFilter filter): Removes @filter from the list of filters that the user can select between.
removeShortcutFolder bool removeShortcutFolder(FileIF folder): Removes a folder from the shortcut folders in a file chooser.
setAction void setAction(GtkFileChooserAction action): Sets the type of operation that the chooser is performing.
setChoice void setChoice(string id, string option): Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice().
setCreateFolders void setCreateFolders(bool createFolders): Sets whether file chooser will offer to create new folders.
setCurrentFolder bool setCurrentFolder(FileIF file): Sets the current folder for @chooser from a #GFile.
setCurrentName void setCurrentName(string name): Sets the current name in the file selector, as if entered by the user.
setFile bool setFile(FileIF file): Sets @file as the current filename for the file chooser.
setFilter void setFilter(FileFilter filter): Sets the current filter.
setSelectMultiple void setSelectMultiple(bool selectMultiple): Sets whether multiple files can be selected in the file chooser.