gtk4/auto/

filter.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::{ffi, FilterChange, FilterMatch};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// A [`Filter`][crate::Filter] object describes the filtering to be performed by a
    /// [`FilterListModel`][crate::FilterListModel].
    ///
    /// The model will use the filter to determine if it should include items
    /// or not by calling [`FilterExt::match_()`][crate::prelude::FilterExt::match_()] for each item and only
    /// keeping the ones that the function returns [`true`] for.
    ///
    /// Filters may change what items they match through their lifetime. In that
    /// case, they will emit the [`changed`][struct@crate::Filter#changed] signal to notify
    /// that previous filter results are no longer valid and that items should
    /// be checked again via [`FilterExt::match_()`][crate::prelude::FilterExt::match_()].
    ///
    /// GTK provides various pre-made filter implementations for common filtering
    /// operations. These filters often include properties that can be linked to
    /// various widgets to easily allow searches.
    ///
    /// However, in particular for large lists or complex search methods, it is
    /// also possible to subclass [`Filter`][crate::Filter] and provide one's own filter.
    ///
    /// ## Signals
    ///
    ///
    /// #### `changed`
    ///  Emitted whenever the filter changed.
    ///
    /// Users of the filter should then check items again via
    /// [`FilterExt::match_()`][crate::prelude::FilterExt::match_()].
    ///
    /// [`FilterListModel`][crate::FilterListModel] handles this signal automatically.
    ///
    /// Depending on the @change parameter, not all items need
    /// to be checked, but only some. Refer to the [`FilterChange`][crate::FilterChange]
    /// documentation for details.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`FilterExt`][trait@crate::prelude::FilterExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkFilter")]
    pub struct Filter(Object<ffi::GtkFilter, ffi::GtkFilterClass>);

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

impl Filter {
    pub const NONE: Option<&'static Filter> = None;
}

/// Trait containing all [`struct@Filter`] methods.
///
/// # Implementors
///
/// [`BoolFilter`][struct@crate::BoolFilter], [`CustomFilter`][struct@crate::CustomFilter], [`FileFilter`][struct@crate::FileFilter], [`Filter`][struct@crate::Filter], [`MultiFilter`][struct@crate::MultiFilter], [`StringFilter`][struct@crate::StringFilter]
pub trait FilterExt: IsA<Filter> + 'static {
    /// Notifies all users of the filter that it has changed.
    ///
    /// This emits the [`changed`][struct@crate::Filter#changed] signal. Users
    /// of the filter should then check items again via
    /// [`match_()`][Self::match_()].
    ///
    /// Depending on the @change parameter, not all items need to
    /// be changed, but only some. Refer to the [`FilterChange`][crate::FilterChange]
    /// documentation for details.
    ///
    /// This function is intended for implementers of [`Filter`][crate::Filter]
    /// subclasses and should not be called from other functions.
    /// ## `change`
    /// How the filter changed
    #[doc(alias = "gtk_filter_changed")]
    fn changed(&self, change: FilterChange) {
        unsafe {
            ffi::gtk_filter_changed(self.as_ref().to_glib_none().0, change.into_glib());
        }
    }

    /// Gets the known strictness of @filters.
    ///
    /// If the strictness is not known, [`FilterMatch::Some`][crate::FilterMatch::Some] is returned.
    ///
    /// This value may change after emission of the [`changed`][struct@crate::Filter#changed]
    /// signal.
    ///
    /// This function is meant purely for optimization purposes, filters can
    /// choose to omit implementing it, but [`FilterListModel`][crate::FilterListModel] uses it.
    ///
    /// # Returns
    ///
    /// the strictness of @self
    #[doc(alias = "gtk_filter_get_strictness")]
    #[doc(alias = "get_strictness")]
    fn strictness(&self) -> FilterMatch {
        unsafe {
            from_glib(ffi::gtk_filter_get_strictness(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if the given @item is matched by the filter or not.
    /// ## `item`
    /// The item to check
    ///
    /// # Returns
    ///
    /// [`true`] if the filter matches the item and a filter model should
    ///   keep it, [`false`] if not.
    #[doc(alias = "gtk_filter_match")]
    #[doc(alias = "match")]
    fn match_(&self, item: &impl IsA<glib::Object>) -> bool {
        unsafe {
            from_glib(ffi::gtk_filter_match(
                self.as_ref().to_glib_none().0,
                item.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Emitted whenever the filter changed.
    ///
    /// Users of the filter should then check items again via
    /// [`match_()`][Self::match_()].
    ///
    /// [`FilterListModel`][crate::FilterListModel] handles this signal automatically.
    ///
    /// Depending on the @change parameter, not all items need
    /// to be checked, but only some. Refer to the [`FilterChange`][crate::FilterChange]
    /// documentation for details.
    /// ## `change`
    /// how the filter changed
    #[doc(alias = "changed")]
    fn connect_changed<F: Fn(&Self, FilterChange) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn changed_trampoline<
            P: IsA<Filter>,
            F: Fn(&P, FilterChange) + 'static,
        >(
            this: *mut ffi::GtkFilter,
            change: ffi::GtkFilterChange,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Filter::from_glib_borrow(this).unsafe_cast_ref(),
                from_glib(change),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"changed\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Filter>> FilterExt for O {}