Struct gtk::FileChooserNative

#[repr(transparent)]
pub struct FileChooserNative { /* private fields */ }

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 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), 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 FileChooserNative closely mirrors FileChooserDialog, the main difference is that there is no access to any Window or 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 NativeDialog functions.

Typical usage ## {gtkfilechoosernative-typical-usage}

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

Response Codes ## {gtkfilechooserdialognative-responses}

FileChooserNative inherits from NativeDialog, which means it will return ResponseType::Accept if the user accepted, and ResponseType::Cancel if he pressed cancel. It can also return ResponseType::DeleteEvent if the window was unexpectedly closed.

Differences from FileChooserDialog ## {gtkfilechooserdialognative-differences}

There are a few things in the GtkFileChooser API that are not possible to use with 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:

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

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

• FileChooserExt::unselect_filename()
• FileChooserExt::select_all()
• FileChooserExt::unselect_all()

If you need any of the above you will have to use 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 ## {gtkfilechooserdialognative-win32}

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

• Extra widgets added with FileChooserExt::set_extra_widget().

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

• Any FileFilter added using a mimetype or custom filter.

If any of these features are used the regular FileChooserDialog 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 FileChooserExt::set_extra_widget().

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

• Any FileFilter 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 FileChooserDialog are not supported:

• Extra widgets added with FileChooserExt::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 signal::FileChooser::update-preview.

• Any FileFilter added with a custom filter.

• Shortcut folders.

Implements

NativeDialogExt, glib::ObjectExt, FileChooserExt, NativeDialogExtManual

Implementations

impl FileChooserNative

pub fn new(
    title: Option<&str>,
    parent: Option<&impl IsA<Window>>,
    action: FileChooserAction,
    accept_label: Option<&str>,
    cancel_label: Option<&str>
) -> FileChooserNative

Available on crate feature v3_20 only.

Creates a new FileChooserNative.

title

Title of the native, or None

parent

Transient parent of the native, or None

action

Open or save mode for the dialog

accept_label

text to go in the accept button, or None for the default

cancel_label

text to go in the cancel button, or None for the default

Returns

a new FileChooserNative

pub fn builder() -> FileChooserNativeBuilder

Available on crate feature v3_20 only.

Creates a new builder-pattern struct instance to construct FileChooserNative objects.

This method returns an instance of FileChooserNativeBuilder which can be used to create FileChooserNative objects.

pub fn accept_label(&self) -> Option<GString>

Available on crate feature v3_20 only.

Retrieves the custom label text for the accept button.

Returns

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

pub fn cancel_label(&self) -> Option<GString>

Available on crate feature v3_20 only.

Retrieves the custom label text for the cancel button.

Returns

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

pub fn set_accept_label(&self, accept_label: Option<&str>)

Available on crate feature v3_20 only.

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.

accept_label

custom label or None for the default

pub fn set_cancel_label(&self, cancel_label: Option<&str>)

Available on crate feature v3_20 only.

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.

cancel_label

custom label or None for the default

pub fn get_property_accept_label(&self) -> Option<GString>

Available on crate feature v3_20 only.

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

pub fn set_property_accept_label(&self, accept_label: Option<&str>)

Available on crate feature v3_20 only.

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

pub fn get_property_cancel_label(&self) -> Option<GString>

Available on crate feature v3_20 only.

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

pub fn set_property_cancel_label(&self, cancel_label: Option<&str>)

Available on crate feature v3_20 only.

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

pub fn connect_accept_label_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_20 only.

pub fn connect_cancel_label_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_20 only.

Trait Implementations

impl Clone for FileChooserNative

Available on crate feature v3_20 only.

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FileChooserNative

Available on crate feature v3_20 only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FileChooserNative

Available on crate feature v3_20 only.

fn default() -> Self

Returns the “default value” for a type.

impl Display for FileChooserNative

Available on crate feature v3_20 only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for FileChooserNative

Available on crate feature v3_20 only.

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for FileChooserNative

Available on crate feature v3_20 only.

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl ParentClassIs for FileChooserNative

Available on crate feature v3_20 only.

type Parent = NativeDialog

impl<OT: ObjectType> PartialEq<OT> for FileChooserNative

Available on crate feature v3_20 only.

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<OT: ObjectType> PartialOrd<OT> for FileChooserNative

Available on crate feature v3_20 only.

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for FileChooserNative

Available on crate feature v3_20 only.

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for FileChooserNative

Available on crate feature v3_20 only.

impl IsA<FileChooser> for FileChooserNative

Available on crate feature v3_20 only.

impl IsA<NativeDialog> for FileChooserNative

Available on crate feature v3_20 only.