gtk4/auto/

sort_list_model.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

#[cfg(feature = "v4_12")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
use crate::SectionModel;
use crate::{ffi, Sorter};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

#[cfg(feature = "v4_12")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
glib::wrapper! {
    /// A list model that sorts the elements of another model.
    ///
    /// The elements are sorted according to a [`Sorter`][crate::Sorter].
    ///
    /// The model is a stable sort. If two items compare equal according
    /// to the sorter, the one that appears first in the original model will
    /// also appear first after sorting.
    ///
    /// Note that if you change the sorter, the previous order will have no
    /// influence on the new order. If you want that, consider using a
    /// [`MultiSorter`][crate::MultiSorter] and appending the previous sorter to it.
    ///
    /// The model can be set up to do incremental sorting, so that
    /// sorting long lists doesn't block the UI. See
    /// [`set_incremental()`][Self::set_incremental()] for details.
    ///
    /// [`SortListModel`][crate::SortListModel] is a generic model and because of that it
    /// cannot take advantage of any external knowledge when sorting.
    /// If you run into performance issues with [`SortListModel`][crate::SortListModel],
    /// it is strongly recommended that you write your own sorting list
    /// model.
    ///
    /// [`SortListModel`][crate::SortListModel] allows sorting the items into sections. It
    /// implements [`SectionModel`][crate::SectionModel] and when [`section-sorter`][struct@crate::SortListModel#section-sorter]
    /// is set, it will sort all items with that sorter and items comparing
    /// equal with it will be put into the same section.
    /// The [`sorter`][struct@crate::SortListModel#sorter] will then be used to sort items
    /// inside their sections.
    ///
    /// ## Properties
    ///
    ///
    /// #### `incremental`
    ///  If the model should sort items incrementally.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `item-type`
    ///  The type of items. See [`ListModelExtManual::item_type()`][crate::gio::prelude::ListModelExtManual::item_type()].
    ///
    /// Readable
    ///
    ///
    /// #### `model`
    ///  The model being sorted.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `n-items`
    ///  The number of items. See [`ListModelExtManual::n_items()`][crate::gio::prelude::ListModelExtManual::n_items()].
    ///
    /// Readable
    ///
    ///
    /// #### `pending`
    ///  Estimate of unsorted items remaining.
    ///
    /// Readable
    ///
    ///
    /// #### `section-sorter`
    ///  The section sorter for this model, if one is set.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `sorter`
    ///  The sorter for this model.
    ///
    /// Readable | Writeable
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`trait@gio::prelude::ListModelExt`], [`SectionModelExt`][trait@crate::prelude::SectionModelExt]
    #[doc(alias = "GtkSortListModel")]
    pub struct SortListModel(Object<ffi::GtkSortListModel, ffi::GtkSortListModelClass>) @implements gio::ListModel, SectionModel;

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

#[cfg(not(any(feature = "v4_12")))]
glib::wrapper! {
    #[doc(alias = "GtkSortListModel")]
    pub struct SortListModel(Object<ffi::GtkSortListModel, ffi::GtkSortListModelClass>) @implements gio::ListModel;

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

impl SortListModel {
    /// Creates a new sort list model that uses the @sorter to sort @model.
    /// ## `model`
    /// the model to sort
    /// ## `sorter`
    /// the [`Sorter`][crate::Sorter] to sort @model with,
    ///
    /// # Returns
    ///
    /// a new [`SortListModel`][crate::SortListModel]
    #[doc(alias = "gtk_sort_list_model_new")]
    pub fn new(
        model: Option<impl IsA<gio::ListModel>>,
        sorter: Option<impl IsA<Sorter>>,
    ) -> SortListModel {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_sort_list_model_new(
                model.map(|p| p.upcast()).into_glib_ptr(),
                sorter.map(|p| p.upcast()).into_glib_ptr(),
            ))
        }
    }

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

    /// Returns whether incremental sorting is enabled.
    ///
    /// See [`set_incremental()`][Self::set_incremental()].
    ///
    /// # Returns
    ///
    /// [`true`] if incremental sorting is enabled
    #[doc(alias = "gtk_sort_list_model_get_incremental")]
    #[doc(alias = "get_incremental")]
    #[doc(alias = "incremental")]
    pub fn is_incremental(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_sort_list_model_get_incremental(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the model currently sorted or [`None`] if none.
    ///
    /// # Returns
    ///
    /// The model that gets sorted
    #[doc(alias = "gtk_sort_list_model_get_model")]
    #[doc(alias = "get_model")]
    pub fn model(&self) -> Option<gio::ListModel> {
        unsafe { from_glib_none(ffi::gtk_sort_list_model_get_model(self.to_glib_none().0)) }
    }

    /// Estimates progress of an ongoing sorting operation.
    ///
    /// The estimate is the number of items that would still need to be
    /// sorted to finish the sorting operation if this was a linear
    /// algorithm. So this number is not related to how many items are
    /// already correctly sorted.
    ///
    /// If you want to estimate the progress, you can use code like this:
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// pending = gtk_sort_list_model_get_pending (self);
    /// model = gtk_sort_list_model_get_model (self);
    /// progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
    /// ```
    ///
    /// If no sort operation is ongoing - in particular when
    /// [`incremental`][struct@crate::SortListModel#incremental] is [`false`] - this
    /// function returns 0.
    ///
    /// # Returns
    ///
    /// a progress estimate of remaining items to sort
    #[doc(alias = "gtk_sort_list_model_get_pending")]
    #[doc(alias = "get_pending")]
    pub fn pending(&self) -> u32 {
        unsafe { ffi::gtk_sort_list_model_get_pending(self.to_glib_none().0) }
    }

    /// Gets the section sorter that is used to sort items of @self into
    /// sections.
    ///
    /// # Returns
    ///
    /// the sorter of #self
    #[cfg(feature = "v4_12")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
    #[doc(alias = "gtk_sort_list_model_get_section_sorter")]
    #[doc(alias = "get_section_sorter")]
    #[doc(alias = "section-sorter")]
    pub fn section_sorter(&self) -> Option<Sorter> {
        unsafe {
            from_glib_none(ffi::gtk_sort_list_model_get_section_sorter(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the sorter that is used to sort @self.
    ///
    /// # Returns
    ///
    /// the sorter of #self
    #[doc(alias = "gtk_sort_list_model_get_sorter")]
    #[doc(alias = "get_sorter")]
    pub fn sorter(&self) -> Option<Sorter> {
        unsafe { from_glib_none(ffi::gtk_sort_list_model_get_sorter(self.to_glib_none().0)) }
    }

    /// Sets the sort model to do an incremental sort.
    ///
    /// When incremental sorting is enabled, the [`SortListModel`][crate::SortListModel] will not do
    /// a complete sort immediately, but will instead queue an idle handler that
    /// incrementally sorts the items towards their correct position. This of
    /// course means that items do not instantly appear in the right place. It
    /// also means that the total sorting time is a lot slower.
    ///
    /// When your filter blocks the UI while sorting, you might consider
    /// turning this on. Depending on your model and sorters, this may become
    /// interesting around 10,000 to 100,000 items.
    ///
    /// By default, incremental sorting is disabled.
    ///
    /// See [`pending()`][Self::pending()] for progress information
    /// about an ongoing incremental sorting operation.
    /// ## `incremental`
    /// [`true`] to sort incrementally
    #[doc(alias = "gtk_sort_list_model_set_incremental")]
    #[doc(alias = "incremental")]
    pub fn set_incremental(&self, incremental: bool) {
        unsafe {
            ffi::gtk_sort_list_model_set_incremental(
                self.to_glib_none().0,
                incremental.into_glib(),
            );
        }
    }

    /// Sets the model to be sorted.
    ///
    /// The @model's item type must conform to the item type of @self.
    /// ## `model`
    /// The model to be sorted
    #[doc(alias = "gtk_sort_list_model_set_model")]
    #[doc(alias = "model")]
    pub fn set_model(&self, model: Option<&impl IsA<gio::ListModel>>) {
        unsafe {
            ffi::gtk_sort_list_model_set_model(
                self.to_glib_none().0,
                model.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets a new section sorter on @self.
    /// ## `sorter`
    /// the [`Sorter`][crate::Sorter] to sort @model with
    #[cfg(feature = "v4_12")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
    #[doc(alias = "gtk_sort_list_model_set_section_sorter")]
    #[doc(alias = "section-sorter")]
    pub fn set_section_sorter(&self, sorter: Option<&impl IsA<Sorter>>) {
        unsafe {
            ffi::gtk_sort_list_model_set_section_sorter(
                self.to_glib_none().0,
                sorter.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets a new sorter on @self.
    /// ## `sorter`
    /// the [`Sorter`][crate::Sorter] to sort @model with
    #[doc(alias = "gtk_sort_list_model_set_sorter")]
    #[doc(alias = "sorter")]
    pub fn set_sorter(&self, sorter: Option<&impl IsA<Sorter>>) {
        unsafe {
            ffi::gtk_sort_list_model_set_sorter(
                self.to_glib_none().0,
                sorter.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    #[doc(alias = "incremental")]
    pub fn connect_incremental_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_incremental_trampoline<F: Fn(&SortListModel) + 'static>(
            this: *mut ffi::GtkSortListModel,
            _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 _,
                c"notify::incremental".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_incremental_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "model")]
    pub fn connect_model_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_model_trampoline<F: Fn(&SortListModel) + 'static>(
            this: *mut ffi::GtkSortListModel,
            _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 _,
                c"notify::model".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_model_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "pending")]
    pub fn connect_pending_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_pending_trampoline<F: Fn(&SortListModel) + 'static>(
            this: *mut ffi::GtkSortListModel,
            _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 _,
                c"notify::pending".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_pending_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v4_12")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
    #[doc(alias = "section-sorter")]
    pub fn connect_section_sorter_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_section_sorter_trampoline<F: Fn(&SortListModel) + 'static>(
            this: *mut ffi::GtkSortListModel,
            _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 _,
                c"notify::section-sorter".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_section_sorter_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "sorter")]
    pub fn connect_sorter_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_sorter_trampoline<F: Fn(&SortListModel) + 'static>(
            this: *mut ffi::GtkSortListModel,
            _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 _,
                c"notify::sorter".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_sorter_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

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

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`SortListModel`] 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 SortListModelBuilder {
    builder: glib::object::ObjectBuilder<'static, SortListModel>,
}

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

    /// If the model should sort items incrementally.
    pub fn incremental(self, incremental: bool) -> Self {
        Self {
            builder: self.builder.property("incremental", incremental),
        }
    }

    /// The model being sorted.
    pub fn model(self, model: &impl IsA<gio::ListModel>) -> Self {
        Self {
            builder: self.builder.property("model", model.clone().upcast()),
        }
    }

    /// The section sorter for this model, if one is set.
    #[cfg(feature = "v4_12")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
    pub fn section_sorter(self, section_sorter: &impl IsA<Sorter>) -> Self {
        Self {
            builder: self
                .builder
                .property("section-sorter", section_sorter.clone().upcast()),
        }
    }

    /// The sorter for this model.
    pub fn sorter(self, sorter: &impl IsA<Sorter>) -> Self {
        Self {
            builder: self.builder.property("sorter", sorter.clone().upcast()),
        }
    }

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