gtk4/auto/

selection_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

use crate::{Bitset, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// An interface that adds support for selection to list models.
    ///
    /// This support is then used by widgets using list models to add the ability
    /// to select and unselect various items.
    ///
    /// GTK provides default implementations of the most common selection modes such
    /// as [`SingleSelection`][crate::SingleSelection], so you will only need to implement this
    /// interface if you want detailed control about how selections should be handled.
    ///
    /// A [`SelectionModel`][crate::SelectionModel] supports a single boolean per item indicating if an item is
    /// selected or not. This can be queried via [`SelectionModelExt::is_selected()`][crate::prelude::SelectionModelExt::is_selected()].
    /// When the selected state of one or more items changes, the model will emit the
    /// [`selection-changed`][struct@crate::SelectionModel#selection-changed] signal by calling the
    /// [`SelectionModelExt::selection_changed()`][crate::prelude::SelectionModelExt::selection_changed()] function. The positions given
    /// in that signal may have their selection state changed, though that is not a
    /// requirement. If new items added to the model via the
    /// [`items-changed`][struct@crate::gio::ListModel#items-changed] signal are selected or not is up to the
    /// implementation.
    ///
    /// Note that items added via [`items-changed`][struct@crate::gio::ListModel#items-changed] may already
    /// be selected and no [`selection-changed`][struct@crate::SelectionModel#selection-changed] will be
    /// emitted for them. So to track which items are selected, it is necessary to
    /// listen to both signals.
    ///
    /// Additionally, the interface can expose functionality to select and unselect
    /// items. If these functions are implemented, GTK's list widgets will allow users
    /// to select and unselect items. However, [`SelectionModel`][crate::SelectionModel]s are free to only
    /// implement them partially or not at all. In that case the widgets will not
    /// support the unimplemented operations.
    ///
    /// When selecting or unselecting is supported by a model, the return values of
    /// the selection functions do *not* indicate if selection or unselection happened.
    /// They are only meant to indicate complete failure, like when this mode of
    /// selecting is not supported by the model.
    ///
    /// Selections may happen asynchronously, so the only reliable way to find out
    /// when an item was selected is to listen to the signals that indicate selection.
    ///
    /// ## Signals
    ///
    ///
    /// #### `selection-changed`
    ///  Emitted when the selection state of some of the items in @model changes.
    ///
    /// Note that this signal does not specify the new selection state of the
    /// items, they need to be queried manually. It is also not necessary for
    /// a model to change the selection state of any of the items in the selection
    /// model, though it would be rather useless to emit such a signal.
    ///
    /// ::: warning
    ///     Note that you have to be careful when modifying the model in signal
    ///     handlers, as it may cause reentrancy problems. This is also the
    ///     case when you modify base models underneath the selection model.
    ///     When in doubt, defer changes to an idle.
    ///
    ///
    /// <details><summary><h4>ListModel</h4></summary>
    ///
    ///
    /// #### `items-changed`
    ///  This signal is emitted whenever items were added to or removed
    /// from @list. At @position, @removed items were removed and @added
    /// items were added in their place.
    ///
    /// Note: If `removed != added`, the positions of all later items
    /// in the model change.
    ///
    ///
    /// </details>
    ///
    /// # Implements
    ///
    /// [`SelectionModelExt`][trait@crate::prelude::SelectionModelExt], [`trait@gio::prelude::ListModelExt`]
    #[doc(alias = "GtkSelectionModel")]
    pub struct SelectionModel(Interface<ffi::GtkSelectionModel, ffi::GtkSelectionModelInterface>) @requires gio::ListModel;

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

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

/// Trait containing all [`struct@SelectionModel`] methods.
///
/// # Implementors
///
/// [`MultiSelection`][struct@crate::MultiSelection], [`NoSelection`][struct@crate::NoSelection], [`SelectionModel`][struct@crate::SelectionModel], [`SingleSelection`][struct@crate::SingleSelection]
pub trait SelectionModelExt: IsA<SelectionModel> + 'static {
    /// Gets the set containing all currently selected items in the model.
    ///
    /// This function may be slow, so if you are only interested in single item,
    /// consider using [`is_selected()`][Self::is_selected()] or if you are only
    /// interested in a few, consider [`selection_in_range()`][Self::selection_in_range()].
    ///
    /// # Returns
    ///
    /// a [`Bitset`][crate::Bitset] containing all the values currently
    ///   selected in @self. If no items are selected, the bitset is empty.
    ///   The bitset must not be modified.
    #[doc(alias = "gtk_selection_model_get_selection")]
    #[doc(alias = "get_selection")]
    fn selection(&self) -> Bitset {
        unsafe {
            from_glib_full(ffi::gtk_selection_model_get_selection(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the set of selected items in a range.
    ///
    /// This function is an optimization for
    /// [`selection()`][Self::selection()] when you are only
    /// interested in part of the model's selected state. A common use
    /// case is in response to the [`selection-changed`][struct@crate::SelectionModel#selection-changed]
    /// signal.
    /// ## `position`
    /// start of the queried range
    /// ## `n_items`
    /// number of items in the queried range
    ///
    /// # Returns
    ///
    /// A [`Bitset`][crate::Bitset] that matches the selection state
    ///   for the given range with all other values being undefined.
    ///   The bitset must not be modified.
    #[doc(alias = "gtk_selection_model_get_selection_in_range")]
    #[doc(alias = "get_selection_in_range")]
    fn selection_in_range(&self, position: u32, n_items: u32) -> Bitset {
        unsafe {
            from_glib_full(ffi::gtk_selection_model_get_selection_in_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            ))
        }
    }

    /// Checks if the given item is selected.
    /// ## `position`
    /// the position of the item to query
    ///
    /// # Returns
    ///
    /// [`true`] if the item is selected
    #[doc(alias = "gtk_selection_model_is_selected")]
    fn is_selected(&self, position: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_is_selected(
                self.as_ref().to_glib_none().0,
                position,
            ))
        }
    }

    /// Requests to select all items in the model.
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items are now selected.
    #[doc(alias = "gtk_selection_model_select_all")]
    fn select_all(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_all(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Requests to select an item in the model.
    /// ## `position`
    /// the position of the item to select
    /// ## `unselect_rest`
    /// whether previously selected items should be unselected
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the item was selected.
    #[doc(alias = "gtk_selection_model_select_item")]
    fn select_item(&self, position: u32, unselect_rest: bool) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_item(
                self.as_ref().to_glib_none().0,
                position,
                unselect_rest.into_glib(),
            ))
        }
    }

    /// Requests to select a range of items in the model.
    /// ## `position`
    /// the first item to select
    /// ## `n_items`
    /// the number of items to select
    /// ## `unselect_rest`
    /// whether previously selected items should be unselected
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the range was selected.
    #[doc(alias = "gtk_selection_model_select_range")]
    fn select_range(&self, position: u32, n_items: u32, unselect_rest: bool) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
                unselect_rest.into_glib(),
            ))
        }
    }

    /// Helper function for implementations of [`SelectionModel`][crate::SelectionModel].
    ///
    /// Call this when the selection changes to emit the
    /// [`selection-changed`][struct@crate::SelectionModel#selection-changed] signal.
    /// ## `position`
    /// the first changed item
    /// ## `n_items`
    /// the number of changed items
    #[doc(alias = "gtk_selection_model_selection_changed")]
    fn selection_changed(&self, position: u32, n_items: u32) {
        unsafe {
            ffi::gtk_selection_model_selection_changed(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            );
        }
    }

    /// Make selection changes.
    ///
    /// This is the most advanced selection updating method that allows
    /// the most fine-grained control over selection changes. If you can,
    /// you should try the simpler versions, as implementations are more
    /// likely to implement support for those.
    ///
    /// Requests that the selection state of all positions set in @mask
    /// be updated to the respective value in the @selected bitmask.
    ///
    /// In pseudocode, it would look something like this:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// for (i = 0; i < n_items; i++)
    ///   {
    ///     // don't change values not in the mask
    ///     if (!gtk_bitset_contains (mask, i))
    ///       continue;
    ///
    ///     if (gtk_bitset_contains (selected, i))
    ///       select_item (i);
    ///     else
    ///       unselect_item (i);
    ///   }
    ///
    /// gtk_selection_model_selection_changed (model,
    ///                                        first_changed_item,
    ///                                        n_changed_items);
    /// ```
    ///
    /// @mask and @selected must not be modified. They may refer to the
    /// same bitset, which would mean that every item in the set should
    /// be selected.
    /// ## `selected`
    /// bitmask specifying if items should be selected or unselected
    /// ## `mask`
    /// bitmask specifying which items should be updated
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items were updated according
    ///   to the inputs.
    #[doc(alias = "gtk_selection_model_set_selection")]
    fn set_selection(&self, selected: &Bitset, mask: &Bitset) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_set_selection(
                self.as_ref().to_glib_none().0,
                selected.to_glib_none().0,
                mask.to_glib_none().0,
            ))
        }
    }

    /// Requests to unselect all items in the model.
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items are now unselected.
    #[doc(alias = "gtk_selection_model_unselect_all")]
    fn unselect_all(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_all(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Requests to unselect an item in the model.
    /// ## `position`
    /// the position of the item to unselect
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the item was unselected.
    #[doc(alias = "gtk_selection_model_unselect_item")]
    fn unselect_item(&self, position: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_item(
                self.as_ref().to_glib_none().0,
                position,
            ))
        }
    }

    /// Requests to unselect a range of items in the model.
    /// ## `position`
    /// the first item to unselect
    /// ## `n_items`
    /// the number of items to unselect
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the range was unselected.
    #[doc(alias = "gtk_selection_model_unselect_range")]
    fn unselect_range(&self, position: u32, n_items: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            ))
        }
    }

    /// Emitted when the selection state of some of the items in @model changes.
    ///
    /// Note that this signal does not specify the new selection state of the
    /// items, they need to be queried manually. It is also not necessary for
    /// a model to change the selection state of any of the items in the selection
    /// model, though it would be rather useless to emit such a signal.
    ///
    /// ::: warning
    ///     Note that you have to be careful when modifying the model in signal
    ///     handlers, as it may cause reentrancy problems. This is also the
    ///     case when you modify base models underneath the selection model.
    ///     When in doubt, defer changes to an idle.
    /// ## `position`
    /// The first item that may have changed
    /// ## `n_items`
    /// number of items with changes
    #[doc(alias = "selection-changed")]
    fn connect_selection_changed<F: Fn(&Self, u32, u32) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn selection_changed_trampoline<
            P: IsA<SelectionModel>,
            F: Fn(&P, u32, u32) + 'static,
        >(
            this: *mut ffi::GtkSelectionModel,
            position: std::ffi::c_uint,
            n_items: std::ffi::c_uint,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    SelectionModel::from_glib_borrow(this).unsafe_cast_ref(),
                    position,
                    n_items,
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"selection-changed".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    selection_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<SelectionModel>> SelectionModelExt for O {}