gtk4/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
#![allow(deprecated)]

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

glib::wrapper! {
    /// Use [`FileDialog`][crate::FileDialog] instead
    /// [`FileChooserNative`][crate::FileChooserNative] is an abstraction of a dialog 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 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), [`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.
    ///
    /// Note that unlike [`FileChooserDialog`][crate::FileChooserDialog], [`FileChooserNative`][crate::FileChooserNative] 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
    /// [`FileChooserNative`][crate::FileChooserNative] to select a file for opening:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// 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 [`FileChooserNative`][crate::FileChooserNative] for saving, you can use this:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// 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 [`FileChooserDialog`][crate::FileChooserDialog] documentation.
    ///
    /// ## Response Codes
    ///
    /// [`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]
    ///
    /// There are a few things in the [`FileChooser`][crate::FileChooser] interface that
    /// are not possible to use with [`FileChooserNative`][crate::FileChooserNative], 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 [`FileChooser`][crate::FileChooser] has, but
    /// there are some things it does not handle:
    ///
    /// * Any [`FileFilter`][crate::FileFilter] added using a mimetype
    ///
    /// If any of these features are used the regular [`FileChooserDialog`][crate::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.
    ///
    /// ## macOS details
    ///
    /// On macOS the `NSSavePanel` and `NSOpenPanel` classes are used to provide
    /// native file chooser dialogs. Some features provided by [`FileChooser`][crate::FileChooser]
    /// are not supported:
    ///
    /// * 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 currently visible.
    ///
    /// Readable | Writeable
    /// </details>
    /// <details><summary><h4>FileChooser</h4></summary>
    ///
    ///
    /// #### `action`
    ///  The type of operation that the file chooser is performing.
    ///
    /// 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
    ///
    ///
    /// #### `filter`
    ///  The current filter for selecting files that are displayed.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `filters`
    ///  A `GListModel` containing the filters that have been
    /// added with gtk_file_chooser_add_filter().
    ///
    /// The returned object should not be modified. It may
    /// or may not be updated for later changes.
    ///
    /// Readable
    ///
    ///
    /// #### `select-multiple`
    ///  Whether to allow multiple files to be selected.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `shortcut-folders`
    ///  A `GListModel` containing the shortcut folders that have been
    /// added with gtk_file_chooser_add_shortcut_folder().
    ///
    /// The returned object should not be modified. It may
    /// or may not be updated for later changes.
    ///
    /// Readable
    /// </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].
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`FileDialog`][crate::FileDialog] instead
    /// ## `title`
    /// Title of the native
    /// ## `parent`
    /// Transient parent of the native
    /// ## `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]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[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.
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`FileDialog`][crate::FileDialog] instead
    ///
    /// # Returns
    ///
    /// The custom label
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_file_chooser_native_get_accept_label")]
    #[doc(alias = "get_accept_label")]
    #[doc(alias = "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.
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`FileDialog`][crate::FileDialog] instead
    ///
    /// # Returns
    ///
    /// The custom label
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_file_chooser_native_get_cancel_label")]
    #[doc(alias = "get_cancel_label")]
    #[doc(alias = "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 should activate the button.
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`FileDialog`][crate::FileDialog] instead
    /// ## `accept_label`
    /// custom label
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_file_chooser_native_set_accept_label")]
    #[doc(alias = "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 should activate the button.
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`FileDialog`][crate::FileDialog] instead
    /// ## `cancel_label`
    /// custom label
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_file_chooser_native_set_cancel_label")]
    #[doc(alias = "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(std::mem::transmute::<*const (), 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(std::mem::transmute::<*const (), 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 currently visible.
    pub fn visible(self, visible: bool) -> Self {
        Self {
            builder: self.builder.property("visible", visible),
        }
    }

    /// The type of operation that the file chooser is performing.
    /// Use [`FileDialog`][crate::FileDialog] instead
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    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.
    /// Use [`FileDialog`][crate::FileDialog] instead
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    pub fn create_folders(self, create_folders: bool) -> Self {
        Self {
            builder: self.builder.property("create-folders", create_folders),
        }
    }

    /// The current filter for selecting files that are displayed.
    /// Use [`FileDialog`][crate::FileDialog] instead
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    pub fn filter(self, filter: &FileFilter) -> Self {
        Self {
            builder: self.builder.property("filter", filter.clone()),
        }
    }

    /// Whether to allow multiple files to be selected.
    /// Use [`FileDialog`][crate::FileDialog] instead
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    pub fn select_multiple(self, select_multiple: bool) -> Self {
        Self {
            builder: self.builder.property("select-multiple", select_multiple),
        }
    }

    // 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 {
        assert_initialized_main_thread!();
        self.builder.build()
    }
}