gtk/auto/

file_chooser_native.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{FileChooser, FileChooserAction, FileFilter, NativeDialog, Widget, Window};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute};

glib::wrapper! {
    /// [`FileChooserNative`][crate::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`][crate::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`][crate::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`][crate::FileChooserNative] closely mirrors [`FileChooserDialog`][crate::FileChooserDialog], the main
    /// difference is that there is no access to any [`Window`][crate::Window] or [`Widget`][crate::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`][crate::NativeDialog] functions.
    ///
    /// ## Typical usage ## {`gtkfilechoosernative`-typical-usage}
    ///
    /// In the simplest of cases, you can the following code to use
    /// [`FileChooserDialog`][crate::FileChooserDialog] to select a file for opening:
    ///
    ///
    /// ```text
    /// 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:
    ///
    ///
    /// ```text
    /// 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`][crate::FileChooserDialog].
    ///
    /// ## Response Codes ## {`gtkfilechooserdialognative`-responses}
    ///
    /// [`FileChooserNative`][crate::FileChooserNative] inherits from [`NativeDialog`][crate::NativeDialog], which means it
    /// will return [`ResponseType::Accept`][crate::ResponseType::Accept] if the user accepted, and
    /// [`ResponseType::Cancel`][crate::ResponseType::Cancel] if he pressed cancel. It can also return
    /// [`ResponseType::DeleteEvent`][crate::ResponseType::DeleteEvent] if the window was unexpectedly closed.
    ///
    /// ## Differences from [`FileChooserDialog`][crate::FileChooserDialog] ## {`gtkfilechooserdialognative`-differences}
    ///
    /// There are a few things in the GtkFileChooser API that are not
    /// possible to use with [`FileChooserNative`][crate::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:
    /// * [`current-folder-changed`][struct@crate::FileChooser#current-folder-changed]
    /// * [`selection-changed`][struct@crate::FileChooser#selection-changed]
    /// * [`file-activated`][struct@crate::FileChooser#file-activated]
    /// * [`confirm-overwrite`][struct@crate::FileChooser#confirm-overwrite]
    ///
    /// You can also not use the methods that directly control user navigation:
    /// * [`FileChooserExt::unselect_filename()`][crate::prelude::FileChooserExt::unselect_filename()]
    /// * [`FileChooserExt::select_all()`][crate::prelude::FileChooserExt::select_all()]
    /// * [`FileChooserExt::unselect_all()`][crate::prelude::FileChooserExt::unselect_all()]
    ///
    /// If you need any of the above you will have to use [`FileChooserDialog`][crate::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`][crate::FileChooserDialog]
    /// does, but there are some things it does not handle:
    ///
    /// * Extra widgets added with [`FileChooserExt::set_extra_widget()`][crate::prelude::FileChooserExt::set_extra_widget()].
    ///
    /// * Use of custom previews by connecting to [`update-preview`][struct@crate::FileChooser#update-preview].
    ///
    /// * Any [`FileFilter`][crate::FileFilter] added using a mimetype or custom filter.
    ///
    /// If any of these features are used the regular [`FileChooserDialog`][crate::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()`][crate::prelude::FileChooserExt::set_extra_widget()].
    ///
    /// * Use of custom previews by connecting to [`update-preview`][struct@crate::FileChooser#update-preview].
    ///
    /// * Any [`FileFilter`][crate::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`][crate::FileChooserDialog] are
    /// not supported:
    ///
    /// * Extra widgets added with [`FileChooserExt::set_extra_widget()`][crate::prelude::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 [`update-preview`][struct@crate::FileChooser#update-preview].
    ///
    /// * Any [`FileFilter`][crate::FileFilter] added with a custom filter.
    ///
    /// * Shortcut folders.
    ///
    /// ## Properties
    ///
    ///
    /// #### `accept-label`
    ///  The text used for the label on the accept button in the dialog, or
    /// [`None`] to use the default text.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `cancel-label`
    ///  The text used for the label on the cancel button in the dialog, or
    /// [`None`] to use the default text.
    ///
    /// Readable | Writeable
    /// <details><summary><h4>NativeDialog</h4></summary>
    ///
    ///
    /// #### `modal`
    ///  Whether the window should be modal with respect to its transient parent.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `title`
    ///  The title of the dialog window
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `transient-for`
    ///  The transient parent of the dialog, or [`None`] for none.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `visible`
    ///  Whether the window is currenlty visible.
    ///
    /// Readable | Writeable
    /// </details>
    /// <details><summary><h4>FileChooser</h4></summary>
    ///
    ///
    /// #### `action`
    ///  Readable | Writeable
    ///
    ///
    /// #### `create-folders`
    ///  Whether a file chooser not in [`FileChooserAction::Open`][crate::FileChooserAction::Open] mode
    /// will offer the user to create new folders.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `do-overwrite-confirmation`
    ///  Whether a file chooser in [`FileChooserAction::Save`][crate::FileChooserAction::Save] mode
    /// will present an overwrite confirmation dialog if the user
    /// selects a file name that already exists.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `extra-widget`
    ///  Readable | Writeable
    ///
    ///
    /// #### `filter`
    ///  Readable | Writeable
    ///
    ///
    /// #### `local-only`
    ///  Readable | Writeable
    ///
    ///
    /// #### `preview-widget`
    ///  Readable | Writeable
    ///
    ///
    /// #### `preview-widget-active`
    ///  Readable | Writeable
    ///
    ///
    /// #### `select-multiple`
    ///  Readable | Writeable
    ///
    ///
    /// #### `show-hidden`
    ///  Readable | Writeable
    ///
    ///
    /// #### `use-preview-label`
    ///  Readable | Writeable
    /// </details>
    ///
    /// # Implements
    ///
    /// [`NativeDialogExt`][trait@crate::prelude::NativeDialogExt], [`trait@glib::ObjectExt`], [`FileChooserExt`][trait@crate::prelude::FileChooserExt], [`NativeDialogExtManual`][trait@crate::prelude::NativeDialogExtManual], [`FileChooserExtManual`][trait@crate::prelude::FileChooserExtManual]
    #[doc(alias = "GtkFileChooserNative")]
    pub struct FileChooserNative(Object<ffi::GtkFileChooserNative, ffi::GtkFileChooserNativeClass>) @extends NativeDialog, @implements FileChooser;

    match fn {
        type_ => || ffi::gtk_file_chooser_native_get_type(),
    }
}

impl FileChooserNative {
    /// Creates a new [`FileChooserNative`][crate::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`][crate::FileChooserNative]
    #[doc(alias = "gtk_file_chooser_native_new")]
    pub fn new(
        title: Option<&str>,
        parent: Option<&impl IsA<Window>>,
        action: FileChooserAction,
        accept_label: Option<&str>,
        cancel_label: Option<&str>,
    ) -> FileChooserNative {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_file_chooser_native_new(
                title.to_glib_none().0,
                parent.map(|p| p.as_ref()).to_glib_none().0,
                action.into_glib(),
                accept_label.to_glib_none().0,
                cancel_label.to_glib_none().0,
            ))
        }
    }

    // rustdoc-stripper-ignore-next
    /// Creates a new builder-pattern struct instance to construct [`FileChooserNative`] objects.
    ///
    /// This method returns an instance of [`FileChooserNativeBuilder`](crate::builders::FileChooserNativeBuilder) which can be used to create [`FileChooserNative`] objects.
    pub fn builder() -> FileChooserNativeBuilder {
        FileChooserNativeBuilder::new()
    }

    /// 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
    #[doc(alias = "gtk_file_chooser_native_get_accept_label")]
    #[doc(alias = "get_accept_label")]
    pub fn accept_label(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_file_chooser_native_get_accept_label(
                self.to_glib_none().0,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_file_chooser_native_get_cancel_label")]
    #[doc(alias = "get_cancel_label")]
    pub fn cancel_label(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_file_chooser_native_get_cancel_label(
                self.to_glib_none().0,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_file_chooser_native_set_accept_label")]
    pub fn set_accept_label(&self, accept_label: Option<&str>) {
        unsafe {
            ffi::gtk_file_chooser_native_set_accept_label(
                self.to_glib_none().0,
                accept_label.to_glib_none().0,
            );
        }
    }

    /// 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
    #[doc(alias = "gtk_file_chooser_native_set_cancel_label")]
    pub fn set_cancel_label(&self, cancel_label: Option<&str>) {
        unsafe {
            ffi::gtk_file_chooser_native_set_cancel_label(
                self.to_glib_none().0,
                cancel_label.to_glib_none().0,
            );
        }
    }

    #[doc(alias = "accept-label")]
    pub fn connect_accept_label_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_accept_label_trampoline<F: Fn(&FileChooserNative) + 'static>(
            this: *mut ffi::GtkFileChooserNative,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::accept-label\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_accept_label_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "cancel-label")]
    pub fn connect_cancel_label_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_cancel_label_trampoline<F: Fn(&FileChooserNative) + 'static>(
            this: *mut ffi::GtkFileChooserNative,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::cancel-label\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_cancel_label_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl Default for FileChooserNative {
    fn default() -> Self {
        glib::object::Object::new::<Self>()
    }
}

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`FileChooserNative`] objects.
///
/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
#[must_use = "The builder must be built to be used"]
pub struct FileChooserNativeBuilder {
    builder: glib::object::ObjectBuilder<'static, FileChooserNative>,
}

impl FileChooserNativeBuilder {
    fn new() -> Self {
        Self {
            builder: glib::object::Object::builder(),
        }
    }

    /// The text used for the label on the accept button in the dialog, or
    /// [`None`] to use the default text.
    pub fn accept_label(self, accept_label: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("accept-label", accept_label.into()),
        }
    }

    /// The text used for the label on the cancel button in the dialog, or
    /// [`None`] to use the default text.
    pub fn cancel_label(self, cancel_label: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("cancel-label", cancel_label.into()),
        }
    }

    /// Whether the window should be modal with respect to its transient parent.
    pub fn modal(self, modal: bool) -> Self {
        Self {
            builder: self.builder.property("modal", modal),
        }
    }

    /// The title of the dialog window
    pub fn title(self, title: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("title", title.into()),
        }
    }

    /// The transient parent of the dialog, or [`None`] for none.
    pub fn transient_for(self, transient_for: &impl IsA<Window>) -> Self {
        Self {
            builder: self
                .builder
                .property("transient-for", transient_for.clone().upcast()),
        }
    }

    /// Whether the window is currenlty visible.
    pub fn visible(self, visible: bool) -> Self {
        Self {
            builder: self.builder.property("visible", visible),
        }
    }

    pub fn action(self, action: FileChooserAction) -> Self {
        Self {
            builder: self.builder.property("action", action),
        }
    }

    /// Whether a file chooser not in [`FileChooserAction::Open`][crate::FileChooserAction::Open] mode
    /// will offer the user to create new folders.
    pub fn create_folders(self, create_folders: bool) -> Self {
        Self {
            builder: self.builder.property("create-folders", create_folders),
        }
    }

    /// Whether a file chooser in [`FileChooserAction::Save`][crate::FileChooserAction::Save] mode
    /// will present an overwrite confirmation dialog if the user
    /// selects a file name that already exists.
    pub fn do_overwrite_confirmation(self, do_overwrite_confirmation: bool) -> Self {
        Self {
            builder: self
                .builder
                .property("do-overwrite-confirmation", do_overwrite_confirmation),
        }
    }

    pub fn extra_widget(self, extra_widget: &impl IsA<Widget>) -> Self {
        Self {
            builder: self
                .builder
                .property("extra-widget", extra_widget.clone().upcast()),
        }
    }

    pub fn filter(self, filter: &FileFilter) -> Self {
        Self {
            builder: self.builder.property("filter", filter.clone()),
        }
    }

    pub fn local_only(self, local_only: bool) -> Self {
        Self {
            builder: self.builder.property("local-only", local_only),
        }
    }

    pub fn preview_widget(self, preview_widget: &impl IsA<Widget>) -> Self {
        Self {
            builder: self
                .builder
                .property("preview-widget", preview_widget.clone().upcast()),
        }
    }

    pub fn preview_widget_active(self, preview_widget_active: bool) -> Self {
        Self {
            builder: self
                .builder
                .property("preview-widget-active", preview_widget_active),
        }
    }

    pub fn select_multiple(self, select_multiple: bool) -> Self {
        Self {
            builder: self.builder.property("select-multiple", select_multiple),
        }
    }

    pub fn show_hidden(self, show_hidden: bool) -> Self {
        Self {
            builder: self.builder.property("show-hidden", show_hidden),
        }
    }

    pub fn use_preview_label(self, use_preview_label: bool) -> Self {
        Self {
            builder: self
                .builder
                .property("use-preview-label", use_preview_label),
        }
    }

    // rustdoc-stripper-ignore-next
    /// Build the [`FileChooserNative`].
    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
    pub fn build(self) -> FileChooserNative {
        self.builder.build()
    }
}

impl fmt::Display for FileChooserNative {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("FileChooserNative")
    }
}