Class

GtkFileChooserNative

Description [src]

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

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 ## {#gtkfilechoosernative-typical-usage}

In the simplest of cases, you can the following code to use GtkFileChooserDialog to select a file for opening:

GtkFileChooserNative *native;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

native = gtk_file_chooser_native_new ("Open File",
                                      parent_window,
                                      action,
                                      "_Open",
                                      "_Cancel");

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

g_object_unref (native);

To use a dialog for saving, you can use this:

GtkFileChooserNative *native;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

native = gtk_file_chooser_native_new ("Save File",
                                      parent_window,
                                      action,
                                      "_Save",
                                      "_Cancel");
chooser = GTK_FILE_CHOOSER (native);

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  gtk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  gtk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

g_object_unref (native);

For more information on how to best set up a file dialog, see GtkFileChooserDialog.

Response Codes ## {#gtkfilechooserdialognative-responses}

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 ## {#gtkfilechooserdialognative-differences}

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: * GtkFileChooser::current-folder-changed * GtkFileChooser::selection-changed * GtkFileChooser::file-activated * GtkFileChooser::confirm-overwrite

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 ## {#gtkfilechooserdialognative-win32}

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:

  • Extra widgets added with gtk_file_chooser_set_extra_widget().

  • Use of custom previews by connecting to GtkFileChooser::update-preview.

  • Any GtkFileFilter added using a mimetype or custom filter.

If any of these features are used the regular GtkFileChooserDialog will be used in place of the native one.

Portal details ## {#gtkfilechooserdialognative-portal}

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:

  • Extra widgets added with gtk_file_chooser_set_extra_widget().

  • Use of custom previews by connecting to GtkFileChooser::update-preview.

  • Any GtkFileFilter added with a custom filter.

macOS details ## {#gtkfilechooserdialognative-macos}

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 GtkFileChooser::update-preview.

  • Any GtkFileFilter added with a custom filter.

  • 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

Implements

Constructors

gtk_file_chooser_native_new

Creates a new GtkFileChooserNative.

Available since: 3.20

Instance methods

gtk_file_chooser_native_get_accept_label

Retrieves the custom label text for the accept button.

Available since: 3.20

gtk_file_chooser_native_get_cancel_label

Retrieves the custom label text for the cancel button.

Available since: 3.20

gtk_file_chooser_native_set_accept_label

Sets the custom label text for the accept button.

Available since: 3.20

gtk_file_chooser_native_set_cancel_label

Sets the custom label text for the cancel button.

Available since: 3.20

Methods inherited from GtkNativeDialog (11)
gtk_native_dialog_destroy

Destroys a dialog.

Available since: 3.20

gtk_native_dialog_get_modal

Returns whether the dialog is modal. See gtk_native_dialog_set_modal().

Available since: 3.20

gtk_native_dialog_get_title

Gets the title of the GtkNativeDialog.

Available since: 3.20

gtk_native_dialog_get_transient_for

Fetches the transient parent for this window. See gtk_native_dialog_set_transient_for().

Available since: 3.20

gtk_native_dialog_get_visible

Determines whether the dialog is visible.

Available since: 3.20

gtk_native_dialog_hide

Hides the dialog if it is visilbe, aborting any interaction. Once this is called the GtkNativeDialog::response signal will not be emitted until after the next call to gtk_native_dialog_show().

Available since: 3.20

gtk_native_dialog_run

Blocks in a recursive main loop until self emits the GtkNativeDialog::response signal. It then returns the response ID from the ::response signal emission.

Available since: 3.20

gtk_native_dialog_set_modal

Sets a dialog modal or non-modal. Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use gtk_native_dialog_set_transient_for() to make the dialog transient for the parent; most [window managers][gtk-X11-arch] will then disallow lowering the dialog below the parent.

Available since: 3.20

gtk_native_dialog_set_title

Sets the title of the GtkNativeDialog.

Available since: 3.20

gtk_native_dialog_set_transient_for

Dialog windows should be set transient for the main application window they were spawned from. This allows [window managers][gtk-X11-arch] to e.g. keep the dialog on top of the main window, or center the dialog over the main window.

Available since: 3.20

gtk_native_dialog_show

Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the GtkNativeDialog::response signal will be emitted.

Available since: 3.20

Methods inherited from GObject (42)
Methods inherited from GtkFileChooser (63)
gtk_file_chooser_add_choice

Adds a ‘choice’ to the file chooser. This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using gtk_file_chooser_set_choice() before the dialog is shown, and you can obtain the user-selected value in the ::response signal handler using gtk_file_chooser_get_choice().

Available since: 3.22

gtk_file_chooser_add_filter

Adds filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed.

Available since: 2.4

gtk_file_chooser_add_shortcut_folder

Adds a folder to be displayed with the shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a “/usr/share/mydrawprogram/Clipart” folder to the volume list.

Available since: 2.4

gtk_file_chooser_add_shortcut_folder_uri

Adds a folder URI to be displayed with the shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a “file:///usr/share/mydrawprogram/Clipart” folder to the volume list.

Available since: 2.4

gtk_file_chooser_get_action

Gets the type of operation that the file chooser is performing; see gtk_file_chooser_set_action().

Available since: 2.4

gtk_file_chooser_get_choice

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

Available since: 3.22

gtk_file_chooser_get_create_folders

Gets whether file choser will offer to create new folders. See gtk_file_chooser_set_create_folders().

Available since: 2.18

gtk_file_chooser_get_current_folder

Gets the current folder of chooser as a local filename. See gtk_file_chooser_set_current_folder().

Available since: 2.4

gtk_file_chooser_get_current_folder_file

Gets the current folder of chooser as GFile. See gtk_file_chooser_get_current_folder_uri().

Available since: 2.14

gtk_file_chooser_get_current_folder_uri

Gets the current folder of chooser as an URI. See gtk_file_chooser_set_current_folder_uri().

Available since: 2.4

gtk_file_chooser_get_current_name

Gets the current name in the file selector, as entered by the user in the text entry for “Name”.

Available since: 3.10

gtk_file_chooser_get_do_overwrite_confirmation

Queries whether a file chooser is set to confirm for overwriting when the user types a file name that already exists.

Available since: 2.8

gtk_file_chooser_get_extra_widget

Gets the current extra widget; see gtk_file_chooser_set_extra_widget().

Available since: 2.4

gtk_file_chooser_get_file

Gets the GFile for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random.

Available since: 2.14

gtk_file_chooser_get_filename

Gets the filename for the currently selected file in the file selector. The filename is returned as an absolute path. If multiple files are selected, one of the filenames will be returned at random.

Available since: 2.4

gtk_file_chooser_get_filenames

Lists all the selected files and subfolders in the current folder of chooser. The returned names are full absolute paths. If files in the current folder cannot be represented as local filenames they will be ignored. (See gtk_file_chooser_get_uris())

Available since: 2.4

gtk_file_chooser_get_files

Lists all the selected files and subfolders in the current folder of chooser as GFile. An internal function, see gtk_file_chooser_get_uris().

Available since: 2.14

gtk_file_chooser_get_filter

Gets the current filter; see gtk_file_chooser_set_filter().

Available since: 2.4

gtk_file_chooser_get_local_only

Gets whether only local files can be selected in the file selector. See gtk_file_chooser_set_local_only()

Available since: 2.4

gtk_file_chooser_get_preview_file

Gets the GFile that should be previewed in a custom preview Internal function, see gtk_file_chooser_get_preview_uri().

Available since: 2.14

gtk_file_chooser_get_preview_filename

Gets the filename that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget().

Available since: 2.4

gtk_file_chooser_get_preview_uri

Gets the URI that should be previewed in a custom preview widget. See gtk_file_chooser_set_preview_widget().

Available since: 2.4

gtk_file_chooser_get_preview_widget

Gets the current preview widget; see gtk_file_chooser_set_preview_widget().

Available since: 2.4

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.

Available since: 3.20

Gtk.NativeDialog:title

The title of the dialog window.

Available since: 3.20

Gtk.NativeDialog:transient-for

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

Available since: 3.20

Gtk.NativeDialog:visible

Whether the window is currenlty visible.

Available since: 3.20

Properties inherited from GtkFileChooser (11)
Gtk.FileChooser:action
No description available.
Gtk.FileChooser:create-folders

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

Available since: 2.18

Gtk.FileChooser:do-overwrite-confirmation

Whether a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE mode will present an overwrite confirmation dialog if the user selects a file name that already exists.

Available since: 2.8

Gtk.FileChooser:extra-widget
No description available.
Gtk.FileChooser:filter
No description available.
Gtk.FileChooser:local-only
No description available.
Gtk.FileChooser:preview-widget
No description available.
Gtk.FileChooser:preview-widget-active
No description available.
Gtk.FileChooser:select-multiple
No description available.
Gtk.FileChooser:show-hidden
No description available.
Gtk.FileChooser:use-preview-label
No description available.

Signals

Signals inherited from GtkNativeDialog (1)
Gtk.NativeDialog::response

Emitted when the user responds to the dialog.

Available since: 3.20

Signals inherited from GObject (1)
Signals inherited from GtkFileChooser (5)
Gtk.FileChooser::confirm-overwrite

This signal gets emitted whenever it is appropriate to present a confirmation dialog when the user has selected a file name that already exists. The signal only gets emitted when the file chooser is in GTK_FILE_CHOOSER_ACTION_SAVE mode.

Available since: 2.8

Gtk.FileChooser::current-folder-changed

This signal is emitted when the current folder in a GtkFileChooser changes. This can happen due to the user performing some action that changes folders, such as selecting a bookmark or visiting a folder on the file list. It can also happen as a result of calling a function to explicitly change the current folder in a file chooser.

Gtk.FileChooser::file-activated

This signal is emitted when the user “activates” a file in the file chooser. This can happen by double-clicking on a file in the file list, or by pressing Enter.

Gtk.FileChooser::selection-changed

This signal is emitted when there is a change in the set of selected files in a GtkFileChooser. This can happen when the user modifies the selection with the mouse or the keyboard, or when explicitly calling functions to change the selection.

Gtk.FileChooser::update-preview

This signal is emitted when the preview in a file chooser should be regenerated. For example, this can happen when the currently selected file changes. You should use this signal if you want your file chooser to have a preview widget.

Class structure

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