gtk4/auto/

filter_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, Filter};
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 filters the elements of another model.
    ///
    /// It hides some elements from the underlying model according to
    /// criteria given by a [`Filter`][crate::Filter].
    ///
    /// The model can be set up to do incremental filtering, so that
    /// filtering long lists doesn't block the UI. See
    /// [`set_incremental()`][Self::set_incremental()] for details.
    ///
    /// [`FilterListModel`][crate::FilterListModel] passes through sections from the underlying model.
    ///
    /// ## Properties
    ///
    ///
    /// #### `filter`
    ///  The filter for this model.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `incremental`
    ///  If the model should filter 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 filtered.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `n-items`
    ///  The number of items. See [`ListModelExtManual::n_items()`][crate::gio::prelude::ListModelExtManual::n_items()].
    ///
    /// Readable
    ///
    ///
    /// #### `pending`
    ///  Number of items not yet filtered.
    ///
    /// Readable
    ///
    ///
    /// #### `watch-items`
    ///  Monitor the list items for changes. It may impact performance.
    ///
    /// Readable | Writeable
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`trait@gio::prelude::ListModelExt`], [`SectionModelExt`][trait@crate::prelude::SectionModelExt]
    #[doc(alias = "GtkFilterListModel")]
    pub struct FilterListModel(Object<ffi::GtkFilterListModel, ffi::GtkFilterListModelClass>) @implements gio::ListModel, SectionModel;

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

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

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

impl FilterListModel {
    /// Creates a new [`FilterListModel`][crate::FilterListModel] that will filter @model using the given
    /// @filter.
    /// ## `model`
    /// the model to sort
    /// ## `filter`
    /// filter
    ///
    /// # Returns
    ///
    /// a new [`FilterListModel`][crate::FilterListModel]
    #[doc(alias = "gtk_filter_list_model_new")]
    pub fn new(
        model: Option<impl IsA<gio::ListModel>>,
        filter: Option<impl IsA<Filter>>,
    ) -> FilterListModel {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_filter_list_model_new(
                model.map(|p| p.upcast()).into_glib_ptr(),
                filter.map(|p| p.upcast()).into_glib_ptr(),
            ))
        }
    }

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

    /// Gets the [`Filter`][crate::Filter] currently set on @self.
    ///
    /// # Returns
    ///
    /// The filter currently in use
    #[doc(alias = "gtk_filter_list_model_get_filter")]
    #[doc(alias = "get_filter")]
    pub fn filter(&self) -> Option<Filter> {
        unsafe { from_glib_none(ffi::gtk_filter_list_model_get_filter(self.to_glib_none().0)) }
    }

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

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

    /// Returns the number of items that have not been filtered yet.
    ///
    /// You can use this value to check if @self is busy filtering by
    /// comparing the return value to 0 or you can compute the percentage
    /// of the filter remaining by dividing the return value by the total
    /// number of items in the underlying model:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// pending = gtk_filter_list_model_get_pending (self);
    /// model = gtk_filter_list_model_get_model (self);
    /// percentage = pending / (double) g_list_model_get_n_items (model);
    /// ```
    ///
    /// If no filter operation is ongoing - in particular when
    /// [`incremental`][struct@crate::FilterListModel#incremental] is [`false`] - this
    /// function returns 0.
    ///
    /// # Returns
    ///
    /// The number of items not yet filtered
    #[doc(alias = "gtk_filter_list_model_get_pending")]
    #[doc(alias = "get_pending")]
    pub fn pending(&self) -> u32 {
        unsafe { ffi::gtk_filter_list_model_get_pending(self.to_glib_none().0) }
    }

    /// Returns whether watching items is enabled.
    ///
    /// See [`set_watch_items()`][Self::set_watch_items()].
    ///
    /// # Returns
    ///
    /// [`true`] if watching items is enabled
    #[cfg(feature = "v4_20")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_20")))]
    #[doc(alias = "gtk_filter_list_model_get_watch_items")]
    #[doc(alias = "get_watch_items")]
    #[doc(alias = "watch-items")]
    pub fn is_watch_items(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_filter_list_model_get_watch_items(
                self.to_glib_none().0,
            ))
        }
    }

    /// Sets the filter used to filter items.
    /// ## `filter`
    /// filter to use
    #[doc(alias = "gtk_filter_list_model_set_filter")]
    #[doc(alias = "filter")]
    pub fn set_filter(&self, filter: Option<&impl IsA<Filter>>) {
        unsafe {
            ffi::gtk_filter_list_model_set_filter(
                self.to_glib_none().0,
                filter.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the filter model to do an incremental sort.
    ///
    /// When incremental filtering is enabled, the [`FilterListModel`][crate::FilterListModel] will not
    /// run filters immediately, but will instead queue an idle handler that
    /// incrementally filters the items and adds them to the list. This of course
    /// means that items are not instantly added to the list, but only appear
    /// incrementally.
    ///
    /// When your filter blocks the UI while filtering, you might consider
    /// turning this on. Depending on your model and filters, this may become
    /// interesting around 10,000 to 100,000 items.
    ///
    /// By default, incremental filtering is disabled.
    ///
    /// See [`pending()`][Self::pending()] for progress information
    /// about an ongoing incremental filtering operation.
    /// ## `incremental`
    /// [`true`] to enable incremental filtering
    #[doc(alias = "gtk_filter_list_model_set_incremental")]
    #[doc(alias = "incremental")]
    pub fn set_incremental(&self, incremental: bool) {
        unsafe {
            ffi::gtk_filter_list_model_set_incremental(
                self.to_glib_none().0,
                incremental.into_glib(),
            );
        }
    }

    /// Sets the model to be filtered.
    ///
    /// Note that GTK makes no effort to ensure that @model conforms to
    /// the item type of @self. It assumes that the caller knows what they
    /// are doing and have set up an appropriate filter to ensure that item
    /// types match.
    /// ## `model`
    /// The model to be filtered
    #[doc(alias = "gtk_filter_list_model_set_model")]
    #[doc(alias = "model")]
    pub fn set_model(&self, model: Option<&impl IsA<gio::ListModel>>) {
        unsafe {
            ffi::gtk_filter_list_model_set_model(
                self.to_glib_none().0,
                model.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the filter model to monitor properties of its items.
    ///
    /// This allows implementations of [`Filter`][crate::Filter] that support expression
    /// watching to react to property changes. This property has no effect if the
    /// current filter doesn't support watching items.
    ///
    /// By default, watching items is disabled.
    /// ## `watch_items`
    /// [`true`] to watch items for property changes
    #[cfg(feature = "v4_20")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_20")))]
    #[doc(alias = "gtk_filter_list_model_set_watch_items")]
    #[doc(alias = "watch-items")]
    pub fn set_watch_items(&self, watch_items: bool) {
        unsafe {
            ffi::gtk_filter_list_model_set_watch_items(
                self.to_glib_none().0,
                watch_items.into_glib(),
            );
        }
    }

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

    #[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(&FilterListModel) + 'static>(
            this: *mut ffi::GtkFilterListModel,
            _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(&FilterListModel) + 'static>(
            this: *mut ffi::GtkFilterListModel,
            _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(&FilterListModel) + 'static>(
            this: *mut ffi::GtkFilterListModel,
            _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_20")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_20")))]
    #[doc(alias = "watch-items")]
    pub fn connect_watch_items_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_watch_items_trampoline<F: Fn(&FilterListModel) + 'static>(
            this: *mut ffi::GtkFilterListModel,
            _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::watch-items".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_watch_items_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

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

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

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

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

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

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

    /// Monitor the list items for changes. It may impact performance.
    #[cfg(feature = "v4_20")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_20")))]
    pub fn watch_items(self, watch_items: bool) -> Self {
        Self {
            builder: self.builder.property("watch-items", watch_items),
        }
    }

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