Class

GtkFileChooserNative

Description [src]

final class Gtk.FileChooserNative : Gtk.NativeDialog {
  /* No available fields */
}

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 GtkNativeDialog 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 GtkFileChooserDialog documentation.

Response Codes

GtkFileChooserNative inherits from GtkNativeDialog, 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 GtkFileChooser 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:

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.

Hierarchy

hierarchy this GtkFileChooserNative implements_0 GtkFileChooser this--implements_0 ancestor_0 GtkNativeDialog ancestor_0--this ancestor_1 GObject ancestor_1--ancestor_0

Ancestors

Implements

Constructors

gtk_file_chooser_native_new

Creates a new GtkFileChooserNative.

Instance methods

gtk_file_chooser_native_get_accept_label

Retrieves the custom label text for the accept button.

gtk_file_chooser_native_get_cancel_label

Retrieves the custom label text for the cancel button.

gtk_file_chooser_native_set_accept_label

Sets the custom label text for the accept button.

gtk_file_chooser_native_set_cancel_label

Sets the custom label text for the cancel button.

Methods inherited from GtkNativeDialog (10)
gtk_native_dialog_destroy

Destroys a dialog.

gtk_native_dialog_get_modal

Returns whether the dialog is modal.

gtk_native_dialog_get_title

Gets the title of the GtkNativeDialog.

gtk_native_dialog_get_transient_for

Fetches the transient parent for this window.

gtk_native_dialog_get_visible

Determines whether the dialog is visible.

gtk_native_dialog_hide

Hides the dialog if it is visible, aborting any interaction.

gtk_native_dialog_set_modal

Sets a dialog modal or non-modal.

gtk_native_dialog_set_title

Sets the title of the GtkNativeDialog.

gtk_native_dialog_set_transient_for

Dialog windows should be set transient for the main application window they were spawned from.

gtk_native_dialog_show

Shows the dialog on the display.

Methods inherited from GtkFileChooser (25)
gtk_file_chooser_add_choice

Adds a ‘choice’ to the file chooser.

gtk_file_chooser_add_filter

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

gtk_file_chooser_add_shortcut_folder

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

gtk_file_chooser_get_action

Gets the type of operation that the file chooser is performing.

gtk_file_chooser_get_choice

Gets the currently selected option in the ‘choice’ with the given ID.

gtk_file_chooser_get_create_folders

Gets whether file chooser will offer to create new folders.

gtk_file_chooser_get_current_folder

Gets the current folder of chooser as GFile.

gtk_file_chooser_get_current_name

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

gtk_file_chooser_get_file

Gets the GFile for the currently selected file in the file selector.

gtk_file_chooser_get_files

Lists all the selected files and subfolders in the current folder of chooser as GFile.

gtk_file_chooser_get_filter

Gets the current filter.

gtk_file_chooser_get_filters

Gets the current set of user-selectable filters, as a list model.

gtk_file_chooser_get_select_multiple

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

gtk_file_chooser_get_shortcut_folders

Queries the list of shortcut folders in the file chooser.

gtk_file_chooser_remove_choice

Removes a ‘choice’ that has been added with gtk_file_chooser_add_choice().

gtk_file_chooser_remove_filter

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

gtk_file_chooser_remove_shortcut_folder

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

gtk_file_chooser_set_action

Sets the type of operation that the chooser is performing.

gtk_file_chooser_set_choice

Selects an option in a ‘choice’ that has been added with gtk_file_chooser_add_choice().

gtk_file_chooser_set_create_folders

Sets whether file chooser will offer to create new folders.

gtk_file_chooser_set_current_folder

Sets the current folder for chooser from a GFile.

gtk_file_chooser_set_current_name

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

gtk_file_chooser_set_file

Sets file as the current filename for the file chooser.

Properties

Gtk.FileChooserNative:accept-label

The text used for the label on the accept button in the dialog, or NULL to use the default text.

Gtk.FileChooserNative:cancel-label

The text used for the label on the cancel button in the dialog, or NULL to use the default text.

Properties inherited from GtkNativeDialog (4)
Gtk.NativeDialog:modal

Whether the window should be modal with respect to its transient parent.

Gtk.NativeDialog:title

The title of the dialog window.

Gtk.NativeDialog:transient-for

The transient parent of the dialog, or NULL for none.

Gtk.NativeDialog:visible

Whether the window is currently visible.

Properties inherited from GtkFileChooser (6)
Gtk.FileChooser:action

The type of operation that the file chooser is performing.

Gtk.FileChooser:create-folders

Whether a file chooser not in GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders.

Gtk.FileChooser:filter

The current filter for selecting files that are displayed.

Gtk.FileChooser:filters

A GListModel containing the filters that have been added with gtk_file_chooser_add_filter().

Gtk.FileChooser:select-multiple

Whether to allow multiple files to be selected.

Gtk.FileChooser:shortcut-folders

A GListModel containing the shortcut folders that have been added with gtk_file_chooser_add_shortcut_folder().

Class structure

struct GtkFileChooserNativeClass {
  GtkNativeDialogClass parent_class;
  
}
Class members
parent_class
GtkNativeDialogClass
  No description available.