gtk/auto/

tree_model_sort.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::{TreeDragSource, TreeIter, TreeModel, TreePath, TreeSortable};
use glib::{prelude::*, translate::*};
use std::fmt;

glib::wrapper! {
    /// The [`TreeModelSort`][crate::TreeModelSort] is a model which implements the [`TreeSortable`][crate::TreeSortable]
    /// interface. It does not hold any data itself, but rather is created with
    /// a child model and proxies its data. It has identical column types to
    /// this child model, and the changes in the child are propagated. The
    /// primary purpose of this model is to provide a way to sort a different
    /// model without modifying it. Note that the sort function used by
    /// [`TreeModelSort`][crate::TreeModelSort] is not guaranteed to be stable.
    ///
    /// The use of this is best demonstrated through an example. In the
    /// following sample code we create two [`TreeView`][crate::TreeView] widgets each with a
    /// view of the same data. As the model is wrapped here by a
    /// [`TreeModelSort`][crate::TreeModelSort], the two `GtkTreeViews` can each sort their
    /// view of the data without affecting the other. By contrast, if we
    /// simply put the same model in each widget, then sorting the first would
    /// sort the second.
    ///
    /// ## Using a [`TreeModelSort`][crate::TreeModelSort]
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// {
    ///   GtkTreeView *tree_view1;
    ///   GtkTreeView *tree_view2;
    ///   GtkTreeModel *sort_model1;
    ///   GtkTreeModel *sort_model2;
    ///   GtkTreeModel *child_model;
    ///
    ///   // get the child model
    ///   child_model = get_my_model ();
    ///
    ///   // Create the first tree
    ///   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
    ///   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
    ///
    ///   // Create the second tree
    ///   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
    ///   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
    ///
    ///   // Now we can sort the two models independently
    ///   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
    ///                                         COLUMN_1, GTK_SORT_ASCENDING);
    ///   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
    ///                                         COLUMN_1, GTK_SORT_DESCENDING);
    /// }
    /// ```
    ///
    /// To demonstrate how to access the underlying child model from the sort
    /// model, the next example will be a callback for the [`TreeSelection`][crate::TreeSelection]
    /// [`changed`][struct@crate::TreeSelection#changed] signal. In this callback, we get a string
    /// from COLUMN_1 of the model. We then modify the string, find the same
    /// selected row on the child model, and change the row there.
    ///
    /// ## Accessing the child model of in a selection changed callback
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// void
    /// selection_changed (GtkTreeSelection *selection, gpointer data)
    /// {
    ///   GtkTreeModel *sort_model = NULL;
    ///   GtkTreeModel *child_model;
    ///   GtkTreeIter sort_iter;
    ///   GtkTreeIter child_iter;
    ///   char *some_data = NULL;
    ///   char *modified_data;
    ///
    ///   // Get the current selected row and the model.
    ///   if (! gtk_tree_selection_get_selected (selection,
    ///                                          &sort_model,
    ///                                          &sort_iter))
    ///     return;
    ///
    ///   // Look up the current value on the selected row and get
    ///   // a new value to change it to.
    ///   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
    ///                       COLUMN_1, &some_data,
    ///                       -1);
    ///
    ///   modified_data = change_the_data (some_data);
    ///   g_free (some_data);
    ///
    ///   // Get an iterator on the child model, instead of the sort model.
    ///   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
    ///                                                   &child_iter,
    ///                                                   &sort_iter);
    ///
    ///   // Get the child model and change the value of the row. In this
    ///   // example, the child model is a GtkListStore. It could be any other
    ///   // type of model, though.
    ///   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
    ///   gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
    ///                       COLUMN_1, &modified_data,
    ///                       -1);
    ///   g_free (modified_data);
    /// }
    /// ```
    ///
    /// ## Properties
    ///
    ///
    /// #### `model`
    ///  Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`TreeModelSortExt`][trait@crate::prelude::TreeModelSortExt], [`trait@glib::ObjectExt`], [`TreeDragSourceExt`][trait@crate::prelude::TreeDragSourceExt], [`TreeModelExt`][trait@crate::prelude::TreeModelExt], [`TreeSortableExt`][trait@crate::prelude::TreeSortableExt], [`TreeSortableExtManual`][trait@crate::prelude::TreeSortableExtManual]
    #[doc(alias = "GtkTreeModelSort")]
    pub struct TreeModelSort(Object<ffi::GtkTreeModelSort, ffi::GtkTreeModelSortClass>) @implements TreeDragSource, TreeModel, TreeSortable;

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

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

    /// Creates a new [`TreeModelSort`][crate::TreeModelSort], with `child_model` as the child model.
    /// ## `child_model`
    /// A [`TreeModel`][crate::TreeModel]
    ///
    /// # Returns
    ///
    /// A new [`TreeModelSort`][crate::TreeModelSort].
    #[doc(alias = "gtk_tree_model_sort_new_with_model")]
    #[doc(alias = "new_with_model")]
    pub fn new(child_model: &impl IsA<TreeModel>) -> TreeModelSort {
        skip_assert_initialized!();
        unsafe {
            from_glib_full(ffi::gtk_tree_model_sort_new_with_model(
                child_model.as_ref().to_glib_none().0,
            ))
        }
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::TreeModelSort>> Sealed for T {}
}

/// Trait containing all [`struct@TreeModelSort`] methods.
///
/// # Implementors
///
/// [`TreeModelSort`][struct@crate::TreeModelSort]
pub trait TreeModelSortExt: IsA<TreeModelSort> + sealed::Sealed + '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
    /// sorted 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.
    #[doc(alias = "gtk_tree_model_sort_clear_cache")]
    fn clear_cache(&self) {
        unsafe {
            ffi::gtk_tree_model_sort_clear_cache(self.as_ref().to_glib_none().0);
        }
    }

    /// Sets `sort_iter` to point to the row in `self` that corresponds to
    /// the row pointed at by `child_iter`. If `sort_iter` was not set, [`false`]
    /// is returned. Note: a boolean is only returned since 2.14.
    /// ## `child_iter`
    /// A valid [`TreeIter`][crate::TreeIter] pointing to a row on the child model
    ///
    /// # Returns
    ///
    /// [`true`], if `sort_iter` was set, i.e. if `sort_iter` is a
    /// valid iterator pointer to a visible row in the child model.
    ///
    /// ## `sort_iter`
    /// An uninitialized [`TreeIter`][crate::TreeIter].
    #[doc(alias = "gtk_tree_model_sort_convert_child_iter_to_iter")]
    fn convert_child_iter_to_iter(&self, child_iter: &TreeIter) -> Option<TreeIter> {
        unsafe {
            let mut sort_iter = TreeIter::uninitialized();
            let ret = from_glib(ffi::gtk_tree_model_sort_convert_child_iter_to_iter(
                self.as_ref().to_glib_none().0,
                sort_iter.to_glib_none_mut().0,
                mut_override(child_iter.to_glib_none().0),
            ));
            if ret {
                Some(sort_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 returned path will
    /// point to the same row in the sorted model. If `child_path` isn’t a valid
    /// path on the child model, then [`None`] is returned.
    /// ## `child_path`
    /// A [`TreePath`][crate::TreePath] to convert
    ///
    /// # Returns
    ///
    /// A newly allocated [`TreePath`][crate::TreePath], or [`None`]
    #[doc(alias = "gtk_tree_model_sort_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_sort_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 `sorted_iter`.
    /// ## `sorted_iter`
    /// A valid [`TreeIter`][crate::TreeIter] pointing to a row on `self`.
    ///
    /// # Returns
    ///
    ///
    /// ## `child_iter`
    /// An uninitialized [`TreeIter`][crate::TreeIter]
    #[doc(alias = "gtk_tree_model_sort_convert_iter_to_child_iter")]
    fn convert_iter_to_child_iter(&self, sorted_iter: &TreeIter) -> TreeIter {
        unsafe {
            let mut child_iter = TreeIter::uninitialized();
            ffi::gtk_tree_model_sort_convert_iter_to_child_iter(
                self.as_ref().to_glib_none().0,
                child_iter.to_glib_none_mut().0,
                mut_override(sorted_iter.to_glib_none().0),
            );
            child_iter
        }
    }

    /// Converts `sorted_path` to a path on the child model of `self`.
    /// That is, `sorted_path` points to a location in `self`. The
    /// returned path will point to the same location in the model not being
    /// sorted. If `sorted_path` does not point to a location in the child model,
    /// [`None`] is returned.
    /// ## `sorted_path`
    /// A [`TreePath`][crate::TreePath] to convert
    ///
    /// # Returns
    ///
    /// A newly allocated [`TreePath`][crate::TreePath], or [`None`]
    #[doc(alias = "gtk_tree_model_sort_convert_path_to_child_path")]
    fn convert_path_to_child_path(&self, sorted_path: &TreePath) -> Option<TreePath> {
        unsafe {
            from_glib_full(ffi::gtk_tree_model_sort_convert_path_to_child_path(
                self.as_ref().to_glib_none().0,
                mut_override(sorted_path.to_glib_none().0),
            ))
        }
    }

    /// Returns the model the [`TreeModelSort`][crate::TreeModelSort] is sorting.
    ///
    /// # Returns
    ///
    /// the "child model" being sorted
    #[doc(alias = "gtk_tree_model_sort_get_model")]
    #[doc(alias = "get_model")]
    fn model(&self) -> TreeModel {
        unsafe {
            from_glib_none(ffi::gtk_tree_model_sort_get_model(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// > This function is slow. Only use it for debugging and/or testing
    /// > purposes.
    ///
    /// Checks if the given iter is a valid iter for this [`TreeModelSort`][crate::TreeModelSort].
    /// ## `iter`
    /// A [`TreeIter`][crate::TreeIter].
    ///
    /// # Returns
    ///
    /// [`true`] if the iter is valid, [`false`] if the iter is invalid.
    #[doc(alias = "gtk_tree_model_sort_iter_is_valid")]
    fn iter_is_valid(&self, iter: &TreeIter) -> bool {
        unsafe {
            from_glib(ffi::gtk_tree_model_sort_iter_is_valid(
                self.as_ref().to_glib_none().0,
                mut_override(iter.to_glib_none().0),
            ))
        }
    }

    /// This resets the default sort function to be in the “unsorted” state. That
    /// is, it is in the same order as the child model. It will re-sort the model
    /// to be in the same order as the child model only if the [`TreeModelSort`][crate::TreeModelSort]
    /// is in “unsorted” state.
    #[doc(alias = "gtk_tree_model_sort_reset_default_sort_func")]
    fn reset_default_sort_func(&self) {
        unsafe {
            ffi::gtk_tree_model_sort_reset_default_sort_func(self.as_ref().to_glib_none().0);
        }
    }
}

impl<O: IsA<TreeModelSort>> TreeModelSortExt for O {}

impl fmt::Display for TreeModelSort {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("TreeModelSort")
    }
}