Gtk.FileChooserNative

Subclasses:None

Methods

Inherited:Gtk.NativeDialog (11), GObject.Object (37), Gtk.FileChooser (63) Structs:GObject.ObjectClass (5)

class	new (title, parent, action, accept_label, cancel_label)
	get_accept_label ()
	get_cancel_label ()
	set_accept_label (accept_label)
	set_cancel_label (cancel_label)

Virtual Methods

Inherited:Gtk.NativeDialog (3), GObject.Object (7)

Properties

Inherited:Gtk.NativeDialog (4), Gtk.FileChooser (11)

Name	Type	Flags	Short Description
accept-label	str	r/w	The label on the accept button
cancel-label	str	r/w	The label on the cancel button

Signals

Inherited:Gtk.NativeDialog (1), GObject.Object (1), Gtk.FileChooser (5)

Fields

Inherited:Gtk.NativeDialog (1), GObject.Object (1), Gtk.FileChooser (5)

Class Details

class Gtk.FileChooserNative(**kwargs)

Bases:Gtk.NativeDialog, Gtk.FileChooser Abstract:No Structure:Gtk.FileChooserNativeClass

Gtk.FileChooserNative is an abstraction of a dialog box suitable for use with “File/Open” or “File/Save as” commands. By default, this just uses a Gtk.FileChooserDialog 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), Gtk.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.FileChooserNative closely mirrors Gtk.FileChooserDialog, the main difference is that there is no access to any Gtk.Window or Gtk.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.NativeDialog functions.

Typical usage

In the simplest of cases, you can the following code to use Gtk.FileChooserDialog 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 Gtk.FileChooserDialog.

Response Codes

Gtk.FileChooserNative inherits from Gtk.NativeDialog, which means it will return Gtk.ResponseType.ACCEPT if the user accepted, and Gtk.ResponseType.CANCEL if he pressed cancel. It can also return Gtk.ResponseType.DELETE_EVENT if the window was unexpectedly closed.

Differences from Gtk.FileChooserDialog

There are a few things in the Gtk.FileChooser API that are not possible to use with Gtk.FileChooserNative, 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:

• Gtk.FileChooser ::current-folder-changed
• Gtk.FileChooser ::selection-changed
• Gtk.FileChooser ::file-activated
• Gtk.FileChooser ::confirm-overwrite

You can also not use the methods that directly control user navigation:

• Gtk.FileChooser.unselect_filename()
• Gtk.FileChooser.select_all()
• Gtk.FileChooser.unselect_all()

If you need any of the above you will have to use Gtk.FileChooserDialog 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

On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that Gtk.FileChooserDialog does, but there are some things it does not handle:

• Extra widgets added with Gtk.FileChooser.set_extra_widget().
• Use of custom previews by connecting to Gtk.FileChooser ::update-preview.
• Any Gtk.FileFilter added using a mimetype or custom filter.

If any of these features are used the regular Gtk.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. In this situation, the following things are not supported and will be silently ignored:

• Extra widgets added with Gtk.FileChooser.set_extra_widget().
• Use of custom previews by connecting to Gtk.FileChooser ::update-preview.
• Any Gtk.FileFilter added with a custom filter.

macOS details

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by Gtk.FileChooserDialog are not supported:

• Extra widgets added with Gtk.FileChooser.set_extra_widget(), unless the widget is an instance of Gtk.Label, in which case the label text will be used to set the NSSavePanel message instance property.
• Use of custom previews by connecting to Gtk.FileChooser ::update-preview.
• Any Gtk.FileFilter added with a custom filter.
• Shortcut folders.

classmethod new(title, parent, action, accept_label, cancel_label)

Parameters:

• title (str or None) – Title of the native, or None
• parent (Gtk.Window or None) – Transient parent of the native, or None
• action (Gtk.FileChooserAction) – Open or save mode for the dialog
• accept_label (str or None) – text to go in the accept button, or None for the default
• cancel_label (str or None) – text to go in the cancel button, or None for the default

Returns:

a new Gtk.FileChooserNative

Return type:

Gtk.FileChooserNative

Creates a new Gtk.FileChooserNative.

New in version 3.20.

get_accept_label()

Returns:The custom label, or None for the default. This string is owned by GTK+ and should not be modified or freed Return type:str or None

Retrieves the custom label text for the accept button.

New in version 3.20.

get_cancel_label()

Returns:The custom label, or None for the default. This string is owned by GTK+ and should not be modified or freed Return type:str or None

Retrieves the custom label text for the cancel button.

New in version 3.20.

set_accept_label(accept_label)

Parameters:accept_label (str or None) – custom label or None for the default

Sets the custom label text for the accept button.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

New in version 3.20.

set_cancel_label(cancel_label)

Parameters:cancel_label (str or None) – custom label or None for the default

Sets the custom label text for the cancel button.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

New in version 3.20.

Property Details

Gtk.FileChooserNative.props.accept_label

Name:accept-label Type:str Default Value:None Flags:READABLE, WRITABLE

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

Gtk.FileChooserNative.props.cancel_label

Name:cancel-label Type:str Default Value:None Flags:READABLE, WRITABLE

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