gtk4/org.gtkkn.bindings.gtk/FileChooserNative

FileChooserNative

open class FileChooserNative(pointer: <Error class: unknown class><<Error class: unknown class>>) : NativeDialog, FileChooser

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.

Constructors

FileChooserNative

constructor(title: String? = null, parent: Window? = null, action: FileChooserAction, acceptLabel: String? = null, cancelLabel: String? = null)

Creates a new GtkFileChooserNative.

constructor(pointer: <Error class: unknown class><<Error class: unknown class>>)

Types

Companion

object Companion

Properties

acceptLabel

open var acceptLabel: String?

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

action

open var action: FileChooserAction

The type of operation that the file chooser is performing.

cancelLabel

open var cancelLabel: String?

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

createFolders

open var createFolders: Boolean

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

filters

open val filters: <Error class: unknown class>

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

gtkFileChooserNativePointer

val gtkFileChooserNativePointer: <Error class: unknown class><<Error class: unknown class>>

gtkFileChooserPointer

open override val gtkFileChooserPointer: <Error class: unknown class><<Error class: unknown class>>

gtkNativeDialogPointer

val gtkNativeDialogPointer: <Error class: unknown class><<Error class: unknown class>>

modal

open var modal: Boolean

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

selectMultiple

open var selectMultiple: Boolean

Whether to allow multiple files to be selected.

shortcutFolders

open val shortcutFolders: <Error class: unknown class>

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

transientFor

open var transientFor: Window?

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

visible

open val visible: Boolean

Whether the window is currently visible.

Functions

addChoice

open fun addChoice(id: String, label: String, options: List<String>? = null, optionLabels: List<String>? = null)

Adds a 'choice' to the file chooser.

addFilter

open fun addFilter(filter: FileFilter)

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

addShortcutFolder

open fun addShortcutFolder(folder: <Error class: unknown class>): <Error class: unknown class><Boolean>

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

connectResponse

fun connectResponse(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (responseId: Int) -> Unit): <Error class: unknown class>

Emitted when the user responds to the dialog.

destroy

open fun destroy()

Destroys a dialog.

getAcceptLabel

open fun getAcceptLabel(): String?

Retrieves the custom label text for the accept button.

getAction

open fun getAction(): FileChooserAction

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

getCancelLabel

open fun getCancelLabel(): String?

Retrieves the custom label text for the cancel button.

getChoice

open fun getChoice(id: String): String?

Gets the currently selected option in the 'choice' with the given ID.

getCreateFolders

open fun getCreateFolders(): Boolean

Gets whether file chooser will offer to create new folders.

getCurrentFolder

open fun getCurrentFolder(): <Error class: unknown class>?

Gets the current folder of @chooser as GFile.

getCurrentName

open fun getCurrentName(): String?

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

getFile

open fun getFile(): <Error class: unknown class>?

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

getFiles

open fun getFiles(): <Error class: unknown class>

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

getFilter

open fun getFilter(): FileFilter?

Gets the current filter.

getFilters

open fun getFilters(): <Error class: unknown class>

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

getModal

open fun getModal(): Boolean

Returns whether the dialog is modal.

getSelectMultiple

open fun getSelectMultiple(): Boolean

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

getShortcutFolders

open fun getShortcutFolders(): <Error class: unknown class>

Queries the list of shortcut folders in the file chooser.

getTitle

open fun getTitle(): String?

Gets the title of the GtkNativeDialog.

getTransientFor

open fun getTransientFor(): Window?

Fetches the transient parent for this window.

getVisible

open fun getVisible(): Boolean

Determines whether the dialog is visible.

hide

open fun hide()

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

removeChoice

open fun removeChoice(id: String)

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

removeFilter

open fun removeFilter(filter: FileFilter)

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

removeShortcutFolder

open fun removeShortcutFolder(folder: <Error class: unknown class>): <Error class: unknown class><Boolean>

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

setAcceptLabel

open fun setAcceptLabel(acceptLabel: String? = null)

Sets the custom label text for the accept button.

setAction

open fun setAction(action: FileChooserAction)

Sets the type of operation that the chooser is performing.

setCancelLabel

open fun setCancelLabel(cancelLabel: String? = null)

Sets the custom label text for the cancel button.

setChoice

open fun setChoice(id: String, option: String)

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

setCreateFolders

open fun setCreateFolders(createFolders: Boolean)

Sets whether file chooser will offer to create new folders.

setCurrentFolder

open fun setCurrentFolder(file: <Error class: unknown class>? = null): <Error class: unknown class><Boolean>

Sets the current folder for @chooser from a GFile.

setCurrentName

open fun setCurrentName(name: String)

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

setFile

open fun setFile(file: <Error class: unknown class>): <Error class: unknown class><Boolean>

Sets @file as the current filename for the file chooser.

setFilter

open fun setFilter(filter: FileFilter)

Sets the current filter.

setModal

open fun setModal(modal: Boolean)

Sets a dialog modal or non-modal.

setSelectMultiple

open fun setSelectMultiple(selectMultiple: Boolean)

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

setTitle

open fun setTitle(title: String)

Sets the title of the GtkNativeDialog.

setTransientFor

open fun setTransientFor(parent: Window? = null)

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

show

open fun show()

Shows the dialog on the display.

FileChooserNative

Typical usage

Response Codes

Differences from GtkFileChooserDialog

Win32 details

Portal details

macOS details

Constructors

Types

Properties

Functions

Differences from `GtkFileChooserDialog`