FileChooserNative

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:

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.

Constructors

this
this(string title, gtk.window.Window parent, gtk.types.FileChooserAction action, string acceptLabel, string cancelLabel)

Creates a new gtk.file_chooser_native.FileChooserNative.

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.

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.

Mixed In Members

From mixin FileChooserT!()

addChoice
void addChoice(string id, string label, string[] options, string[] optionLabels)

Adds a 'choice' to the file chooser.

addFilter
void addFilter(gtk.file_filter.FileFilter filter)

Adds filter to the list of filters that the user can select between.

addShortcutFolder
bool addShortcutFolder(gio.file.File folder)

Adds a folder to be displayed with the shortcut folders in a file chooser.

getAction
gtk.types.FileChooserAction 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
gio.file.File getCurrentFolder()

Gets the current folder of chooser as gio.file.File.

getCurrentName
string getCurrentName()

Gets the current name in the file selector, as entered by the user.

getFile
gio.file.File getFile()

Gets the gio.file.File for the currently selected file in the file selector.

getFiles
gio.list_model.ListModel getFiles()

Lists all the selected files and subfolders in the current folder of chooser as gio.file.File.

getFilter
gtk.file_filter.FileFilter getFilter()

Gets the current filter.

getFilters
gio.list_model.ListModel 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
gio.list_model.ListModel 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.FileChooser.addChoice.

removeFilter
void removeFilter(gtk.file_filter.FileFilter filter)

Removes filter from the list of filters that the user can select between.

removeShortcutFolder
bool removeShortcutFolder(gio.file.File folder)

Removes a folder from the shortcut folders in a file chooser.

setAction
void setAction(gtk.types.FileChooserAction 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.FileChooser.addChoice.

setCreateFolders
void setCreateFolders(bool createFolders)

Sets whether file chooser will offer to create new folders.

setCurrentFolder
bool setCurrentFolder(gio.file.File file)

Sets the current folder for chooser from a gio.file.File.

setCurrentName
void setCurrentName(string name)

Sets the current name in the file selector, as if entered by the user.

setFile
bool setFile(gio.file.File file)

Sets file as the current filename for the file chooser.

setFilter
void setFilter(gtk.file_filter.FileFilter filter)

Sets the current filter.

setSelectMultiple
void setSelectMultiple(bool selectMultiple)

Sets whether multiple files can be selected in the file chooser.

Inherited Members

From NativeDialog

destroy
void destroy()

Destroys a dialog.

getModal
bool getModal()

Returns whether the dialog is modal.

getTitle
string getTitle()

Gets the title of the gtk.native_dialog.NativeDialog.

getTransientFor
gtk.window.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(gtk.window.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.

connectResponse
ulong connectResponse(T callback, Flag!"After" after)

Connect to Response signal.

From FileChooser

addChoice
void addChoice(string id, string label, string[] options, string[] optionLabels)

Adds a 'choice' to the file chooser.

addFilter
void addFilter(gtk.file_filter.FileFilter filter)

Adds filter to the list of filters that the user can select between.

addShortcutFolder
bool addShortcutFolder(gio.file.File folder)

Adds a folder to be displayed with the shortcut folders in a file chooser.

getAction
gtk.types.FileChooserAction 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
gio.file.File getCurrentFolder()

Gets the current folder of chooser as gio.file.File.

getCurrentName
string getCurrentName()

Gets the current name in the file selector, as entered by the user.

getFile
gio.file.File getFile()

Gets the gio.file.File for the currently selected file in the file selector.

getFiles
gio.list_model.ListModel getFiles()

Lists all the selected files and subfolders in the current folder of chooser as gio.file.File.

getFilter
gtk.file_filter.FileFilter getFilter()

Gets the current filter.

getFilters
gio.list_model.ListModel 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
gio.list_model.ListModel 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.FileChooser.addChoice.

removeFilter
void removeFilter(gtk.file_filter.FileFilter filter)

Removes filter from the list of filters that the user can select between.

removeShortcutFolder
bool removeShortcutFolder(gio.file.File folder)

Removes a folder from the shortcut folders in a file chooser.

setAction
void setAction(gtk.types.FileChooserAction 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.FileChooser.addChoice.

setCreateFolders
void setCreateFolders(bool createFolders)

Sets whether file chooser will offer to create new folders.

setCurrentFolder
bool setCurrentFolder(gio.file.File file)

Sets the current folder for chooser from a gio.file.File.

setCurrentName
void setCurrentName(string name)

Sets the current name in the file selector, as if entered by the user.

setFile
bool setFile(gio.file.File file)

Sets file as the current filename for the file chooser.

setFilter
void setFilter(gtk.file_filter.FileFilter filter)

Sets the current filter.

setSelectMultiple
void setSelectMultiple(bool selectMultiple)

Sets whether multiple files can be selected in the file chooser.

Detailed Description

Deprecated: Use gtk.file_dialog.FileDialog instead