gtk4/auto/

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

use crate::{ffi, TreeDragSource, TreeIter, TreeModel, TreePath};
use glib::{prelude::*, translate::*};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Use [`FilterListModel`][crate::FilterListModel] instead.
    /// A [`TreeModel`][crate::TreeModel] which hides parts of an underlying tree model
    ///
    /// A [`TreeModelFilter`][crate::TreeModelFilter] is a tree model which wraps another tree model,
    /// and can do the following things:
    ///
    /// - Filter specific rows, based on data from a “visible column”, a column
    ///   storing booleans indicating whether the row should be filtered or not,
    ///   or based on the return value of a “visible function”, which gets a
    ///   model, iter and user_data and returns a boolean indicating whether the
    ///   row should be filtered or not.
    ///
    /// - Modify the “appearance” of the model, using a modify function.
    ///   This is extremely powerful and allows for just changing some
    ///   values and also for creating a completely different model based
    ///   on the given child model.
    ///
    /// - Set a different root node, also known as a “virtual root”. You can pass
    ///   in a [`TreePath`][crate::TreePath] indicating the root node for the filter at construction
    ///   time.
    ///
    /// The basic API is similar to [`TreeModelSort`][crate::TreeModelSort]. For an example on its usage,
    /// see the section on [`TreeModelSort`][crate::TreeModelSort].
    ///
    /// When using [`TreeModelFilter`][crate::TreeModelFilter], it is important to realize that
    /// [`TreeModelFilter`][crate::TreeModelFilter] maintains an internal cache of all nodes which are
    /// visible in its clients. The cache is likely to be a subtree of the tree
    /// exposed by the child model. [`TreeModelFilter`][crate::TreeModelFilter] will not cache the entire
    /// child model when unnecessary to not compromise the caching mechanism
    /// that is exposed by the reference counting scheme. If the child model
    /// implements reference counting, unnecessary signals may not be emitted
    /// because of reference counting rule 3, see the [`TreeModel`][crate::TreeModel]
    /// documentation. (Note that e.g. [`TreeStore`][crate::TreeStore] does not implement
    /// reference counting and will always emit all signals, even when
    /// the receiving node is not visible).
    ///
    /// Because of this, limitations for possible visible functions do apply.
    /// In general, visible functions should only use data or properties from
    /// the node for which the visibility state must be determined, its siblings
    /// or its parents. Usually, having a dependency on the state of any child
    /// node is not possible, unless references are taken on these explicitly.
    /// When no such reference exists, no signals may be received for these child
    /// nodes (see reference counting rule number 3 in the [`TreeModel`][crate::TreeModel] section).
    ///
    /// Determining the visibility state of a given node based on the state
    /// of its child nodes is a frequently occurring use case. Therefore,
    /// [`TreeModelFilter`][crate::TreeModelFilter] explicitly supports this. For example, when a node
    /// does not have any children, you might not want the node to be visible.
    /// As soon as the first row is added to the node’s child level (or the
    /// last row removed), the node’s visibility should be updated.
    ///
    /// This introduces a dependency from the node on its child nodes. In order
    /// to accommodate this, [`TreeModelFilter`][crate::TreeModelFilter] must make sure the necessary
    /// signals are received from the child model. This is achieved by building,
    /// for all nodes which are exposed as visible nodes to [`TreeModelFilter`][crate::TreeModelFilter]'s
    /// clients, the child level (if any) and take a reference on the first node
    /// in this level. Furthermore, for every row-inserted, row-changed or
    /// row-deleted signal (also these which were not handled because the node
    /// was not cached), [`TreeModelFilter`][crate::TreeModelFilter] will check if the visibility state
    /// of any parent node has changed.
    ///
    /// Beware, however, that this explicit support is limited to these two
    /// cases. For example, if you want a node to be visible only if two nodes
    /// in a child’s child level (2 levels deeper) are visible, you are on your
    /// own. In this case, either rely on [`TreeStore`][crate::TreeStore] to emit all signals
    /// because it does not implement reference counting, or for models that
    /// do implement reference counting, obtain references on these child levels
    /// yourself.
    ///
    /// ## Properties
    ///
    ///
    /// #### `child-model`
    ///  The child model of the tree model filter.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `virtual-root`
    ///  The virtual root of the tree model filter.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`TreeModelFilterExt`][trait@crate::prelude::TreeModelFilterExt], [`trait@glib::ObjectExt`], [`TreeDragSourceExt`][trait@crate::prelude::TreeDragSourceExt], [`TreeModelExt`][trait@crate::prelude::TreeModelExt], [`TreeModelFilterExtManual`][trait@crate::prelude::TreeModelFilterExtManual], [`TreeModelExtManual`][trait@crate::prelude::TreeModelExtManual]
    #[doc(alias = "GtkTreeModelFilter")]
    pub struct TreeModelFilter(Object<ffi::GtkTreeModelFilter, ffi::GtkTreeModelFilterClass>) @implements TreeDragSource, TreeModel;

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

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

/// Trait containing all [`struct@TreeModelFilter`] methods.
///
/// # Implementors
///
/// [`TreeModelFilter`][struct@crate::TreeModelFilter]
pub trait TreeModelFilterExt: IsA<TreeModelFilter> + 'static {
    /// This function should almost never be called. It clears the @self
    /// of any cached iterators that haven’t been reffed with
    /// gtk_tree_model_ref_node(). This might be useful if the child model
    /// being filtered is static (and doesn’t change often) and there has been
    /// a lot of unreffed access to nodes. As a side effect of this function,
    /// all unreffed iters will be invalid.
    ///
    /// # Deprecated since 4.10
    ///
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_clear_cache")]
    fn clear_cache(&self) {
        unsafe {
            ffi::gtk_tree_model_filter_clear_cache(self.as_ref().to_glib_none().0);
        }
    }

    /// Sets @filter_iter to point to the row in @self that corresponds to the
    /// row pointed at by @child_iter.  If @filter_iter was not set, [`false`] is
    /// returned.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `child_iter`
    /// A valid [`TreeIter`][crate::TreeIter] pointing to a row on the child model.
    ///
    /// # Returns
    ///
    /// [`true`], if @filter_iter was set, i.e. if @child_iter is a
    /// valid iterator pointing to a visible row in child model.
    ///
    /// ## `filter_iter`
    /// An uninitialized [`TreeIter`][crate::TreeIter]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_convert_child_iter_to_iter")]
    fn convert_child_iter_to_iter(&self, child_iter: &TreeIter) -> Option<TreeIter> {
        unsafe {
            let mut filter_iter = TreeIter::uninitialized();
            let ret = from_glib(ffi::gtk_tree_model_filter_convert_child_iter_to_iter(
                self.as_ref().to_glib_none().0,
                filter_iter.to_glib_none_mut().0,
                mut_override(child_iter.to_glib_none().0),
            ));
            if ret {
                Some(filter_iter)
            } else {
                None
            }
        }
    }

    /// Converts @child_path to a path relative to @self. That is, @child_path
    /// points to a path in the child model. The rerturned path will point to the
    /// same row in the filtered model. If @child_path isn’t a valid path on the
    /// child model or points to a row which is not visible in @self, then [`None`]
    /// is returned.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `child_path`
    /// A [`TreePath`][crate::TreePath] to convert.
    ///
    /// # Returns
    ///
    /// A newly allocated [`TreePath`][crate::TreePath]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_convert_child_path_to_path")]
    fn convert_child_path_to_path(&self, child_path: &TreePath) -> Option<TreePath> {
        unsafe {
            from_glib_full(ffi::gtk_tree_model_filter_convert_child_path_to_path(
                self.as_ref().to_glib_none().0,
                mut_override(child_path.to_glib_none().0),
            ))
        }
    }

    /// Sets @child_iter to point to the row pointed to by @filter_iter.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `filter_iter`
    /// A valid [`TreeIter`][crate::TreeIter] pointing to a row on @self.
    ///
    /// # Returns
    ///
    ///
    /// ## `child_iter`
    /// An uninitialized [`TreeIter`][crate::TreeIter]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_convert_iter_to_child_iter")]
    fn convert_iter_to_child_iter(&self, filter_iter: &TreeIter) -> TreeIter {
        unsafe {
            let mut child_iter = TreeIter::uninitialized();
            ffi::gtk_tree_model_filter_convert_iter_to_child_iter(
                self.as_ref().to_glib_none().0,
                child_iter.to_glib_none_mut().0,
                mut_override(filter_iter.to_glib_none().0),
            );
            child_iter
        }
    }

    /// Converts @filter_path to a path on the child model of @self. That is,
    /// @filter_path points to a location in @self. The returned path will
    /// point to the same location in the model not being filtered. If @filter_path
    /// does not point to a location in the child model, [`None`] is returned.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `filter_path`
    /// A [`TreePath`][crate::TreePath] to convert.
    ///
    /// # Returns
    ///
    /// A newly allocated [`TreePath`][crate::TreePath]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_convert_path_to_child_path")]
    fn convert_path_to_child_path(&self, filter_path: &TreePath) -> Option<TreePath> {
        unsafe {
            from_glib_full(ffi::gtk_tree_model_filter_convert_path_to_child_path(
                self.as_ref().to_glib_none().0,
                mut_override(filter_path.to_glib_none().0),
            ))
        }
    }

    /// Returns a pointer to the child model of @self.
    ///
    /// # Deprecated since 4.10
    ///
    ///
    /// # Returns
    ///
    /// A pointer to a [`TreeModel`][crate::TreeModel]
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_get_model")]
    #[doc(alias = "get_model")]
    fn model(&self) -> TreeModel {
        unsafe {
            from_glib_none(ffi::gtk_tree_model_filter_get_model(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Emits ::row_changed for each row in the child model, which causes
    /// the filter to re-evaluate whether a row is visible or not.
    ///
    /// # Deprecated since 4.10
    ///
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_refilter")]
    fn refilter(&self) {
        unsafe {
            ffi::gtk_tree_model_filter_refilter(self.as_ref().to_glib_none().0);
        }
    }

    /// Sets @column of the child_model to be the column where @self should
    /// look for visibility information. @columns should be a column of type
    /// `G_TYPE_BOOLEAN`, where [`true`] means that a row is visible, and [`false`]
    /// if not.
    ///
    /// Note that gtk_tree_model_filter_set_visible_func() or
    /// gtk_tree_model_filter_set_visible_column() can only be called
    /// once for a given filter model.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `column`
    /// A `int` which is the column containing the visible information
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_set_visible_column")]
    fn set_visible_column(&self, column: i32) {
        unsafe {
            ffi::gtk_tree_model_filter_set_visible_column(self.as_ref().to_glib_none().0, column);
        }
    }

    /// Sets the visible function used when filtering the @self to be @func.
    /// The function should return [`true`] if the given row should be visible and
    /// [`false`] otherwise.
    ///
    /// If the condition calculated by the function changes over time (e.g.
    /// because it depends on some global parameters), you must call
    /// gtk_tree_model_filter_refilter() to keep the visibility information
    /// of the model up-to-date.
    ///
    /// Note that @func is called whenever a row is inserted, when it may still
    /// be empty. The visible function should therefore take special care of empty
    /// rows, like in the example below.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    /// visible_func (GtkTreeModel *model,
    ///               GtkTreeIter  *iter,
    ///               gpointer      data)
    /// {
    ///   // Visible if row is non-empty and first column is “HI”
    ///   char *str;
    ///   gboolean visible = FALSE;
    ///
    ///   gtk_tree_model_get (model, iter, 0, &str, -1);
    ///   if (str && strcmp (str, "HI") == 0)
    ///     visible = TRUE;
    ///   g_free (str);
    ///
    ///   return visible;
    /// }
    /// ```
    ///
    /// Note that gtk_tree_model_filter_set_visible_func() or
    /// gtk_tree_model_filter_set_visible_column() can only be called
    /// once for a given filter model.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `func`
    /// A `GtkTreeModelFilterVisibleFunc`, the visible function
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_tree_model_filter_set_visible_func")]
    fn set_visible_func<P: Fn(&TreeModel, &TreeIter) -> bool + 'static>(&self, func: P) {
        let func_data: Box_<P> = Box_::new(func);
        unsafe extern "C" fn func_func<P: Fn(&TreeModel, &TreeIter) -> bool + 'static>(
            model: *mut ffi::GtkTreeModel,
            iter: *mut ffi::GtkTreeIter,
            data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let model = from_glib_borrow(model);
            let iter = from_glib_borrow(iter);
            let callback = &*(data as *mut P);
            (*callback)(&model, &iter).into_glib()
        }
        let func = Some(func_func::<P> as _);
        unsafe extern "C" fn destroy_func<P: Fn(&TreeModel, &TreeIter) -> bool + 'static>(
            data: glib::ffi::gpointer,
        ) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(destroy_func::<P> as _);
        let super_callback0: Box_<P> = func_data;
        unsafe {
            ffi::gtk_tree_model_filter_set_visible_func(
                self.as_ref().to_glib_none().0,
                func,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    /// The child model of the tree model filter.
    #[doc(alias = "child-model")]
    fn child_model(&self) -> Option<TreeModel> {
        ObjectExt::property(self.as_ref(), "child-model")
    }
}

impl<O: IsA<TreeModelFilter>> TreeModelFilterExt for O {}