gio/auto/

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

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

glib::wrapper! {
    /// `GListModel` is an interface that represents a mutable list of
    /// [`glib::Object`][crate::glib::Object]. Its main intention is as a model for various widgets
    /// in user interfaces, such as list views, but it can also be used as a
    /// convenient method of returning lists of data, with support for
    /// updates.
    ///
    /// Each object in the list may also report changes in itself via some
    /// mechanism (normally the [`notify`][struct@crate::glib::Object#notify] signal).  Taken
    /// together with the [`items-changed`][struct@crate::ListModel#items-changed] signal, this provides
    /// for a list that can change its membership, and in which the members can
    /// change their individual properties.
    ///
    /// A good example would be the list of visible wireless network access
    /// points, where each access point can report dynamic properties such as
    /// signal strength.
    ///
    /// It is important to note that the `GListModel` itself does not report
    /// changes to the individual items.  It only reports changes to the list
    /// membership.  If you want to observe changes to the objects themselves
    /// then you need to connect signals to the objects that you are
    /// interested in.
    ///
    /// All items in a `GListModel` are of (or derived from) the same type.
    /// [`ListModelExt::item_type()`][crate::prelude::ListModelExt::item_type()] returns that type.  The type may be an
    /// interface, in which case all objects in the list must implement it.
    ///
    /// The semantics are close to that of an array:
    /// [`ListModelExt::n_items()`][crate::prelude::ListModelExt::n_items()] returns the number of items in the list
    /// and `Gio::ListModel::get_item()` returns an item at a (0-based) position.
    /// In order to allow implementations to calculate the list length lazily,
    /// you can also iterate over items: starting from 0, repeatedly call
    /// `Gio::ListModel::get_item()` until it returns `NULL`.
    ///
    /// An implementation may create objects lazily, but must take care to
    /// return the same object for a given position until all references to
    /// it are gone.
    ///
    /// On the other side, a consumer is expected only to hold references on
    /// objects that are currently ‘user visible’, in order to facilitate the
    /// maximum level of laziness in the implementation of the list and to
    /// reduce the required number of signal connections at a given time.
    ///
    /// This interface is intended only to be used from a single thread.  The
    /// thread in which it is appropriate to use it depends on the particular
    /// implementation, but typically it will be from the thread that owns
    /// the thread-default main context (see
    /// [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()]) in effect at the time that the
    /// model was created.
    ///
    /// Over time, it has established itself as good practice for list model
    /// implementations to provide properties `item-type` and `n-items` to
    /// ease working with them. While it is not required, it is recommended
    /// that implementations provide these two properties. They should return
    /// the values of [`ListModelExt::item_type()`][crate::prelude::ListModelExt::item_type()] and
    /// [`ListModelExt::n_items()`][crate::prelude::ListModelExt::n_items()] respectively and be defined as such:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// properties[PROP_ITEM_TYPE] =
    ///   g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT,
    ///                       G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    /// properties[PROP_N_ITEMS] =
    ///   g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0,
    ///                      G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
    /// ```
    ///
    /// ## Signals
    ///
    ///
    /// #### `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.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`ListModelExt`][trait@crate::prelude::ListModelExt], [`ListModelExtManual`][trait@crate::prelude::ListModelExtManual]
    #[doc(alias = "GListModel")]
    pub struct ListModel(Interface<ffi::GListModel, ffi::GListModelInterface>);

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

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

/// Trait containing all [`struct@ListModel`] methods.
///
/// # Implementors
///
/// [`ListModel`][struct@crate::ListModel], [`ListStore`][struct@crate::ListStore]
pub trait ListModelExt: IsA<ListModel> + 'static {
    /// Gets the type of the items in @self.
    ///
    /// All items returned from g_list_model_get_item() are of the type
    /// returned by this function, or a subtype, or if the type is an
    /// interface, they are an implementation of that interface.
    ///
    /// The item type of a #GListModel can not change during the life of the
    /// model.
    ///
    /// # Returns
    ///
    /// the #GType of the items contained in @self.
    #[doc(alias = "g_list_model_get_item_type")]
    #[doc(alias = "get_item_type")]
    fn item_type(&self) -> glib::types::Type {
        unsafe {
            from_glib(ffi::g_list_model_get_item_type(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the number of items in @self.
    ///
    /// Depending on the model implementation, calling this function may be
    /// less efficient than iterating the list with increasing values for
    /// @position until g_list_model_get_item() returns [`None`].
    ///
    /// # Returns
    ///
    /// the number of items in @self.
    #[doc(alias = "g_list_model_get_n_items")]
    #[doc(alias = "get_n_items")]
    fn n_items(&self) -> u32 {
        unsafe { ffi::g_list_model_get_n_items(self.as_ref().to_glib_none().0) }
    }

    /// Get the item at @position.
    ///
    /// If @position is greater than the number of items in @self, [`None`] is
    /// returned.
    ///
    /// [`None`] is never returned for an index that is smaller than the length
    /// of the list.
    ///
    /// This function is meant to be used by language bindings in place
    /// of g_list_model_get_item().
    ///
    /// See also: g_list_model_get_n_items()
    /// ## `position`
    /// the position of the item to fetch
    ///
    /// # Returns
    ///
    /// the object at @position.
    #[doc(alias = "g_list_model_get_object")]
    #[doc(alias = "get_object")]
    fn item(&self, position: u32) -> Option<glib::Object> {
        unsafe {
            from_glib_full(ffi::g_list_model_get_object(
                self.as_ref().to_glib_none().0,
                position,
            ))
        }
    }

    /// Emits the #GListModel::items-changed signal on @self.
    ///
    /// This function should only be called by classes implementing
    /// #GListModel. It has to be called after the internal representation
    /// of @self has been updated, because handlers connected to this signal
    /// might query the new state of the list.
    ///
    /// Implementations must only make changes to the model (as visible to
    /// its consumer) in places that will not cause problems for that
    /// consumer.  For models that are driven directly by a write API (such
    /// as #GListStore), changes can be reported in response to uses of that
    /// API.  For models that represent remote data, changes should only be
    /// made from a fresh mainloop dispatch.  It is particularly not
    /// permitted to make changes in response to a call to the #GListModel
    /// consumer API.
    ///
    /// Stated another way: in general, it is assumed that code making a
    /// series of accesses to the model via the API, without returning to the
    /// mainloop, and without calling other code, will continue to view the
    /// same contents of the model.
    /// ## `position`
    /// the position at which @self changed
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "g_list_model_items_changed")]
    fn items_changed(&self, position: u32, removed: u32, added: u32) {
        unsafe {
            ffi::g_list_model_items_changed(
                self.as_ref().to_glib_none().0,
                position,
                removed,
                added,
            );
        }
    }

    /// 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.
    /// ## `position`
    /// the position at which @list changed
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "items-changed")]
    fn connect_items_changed<F: Fn(&Self, u32, u32, u32) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn items_changed_trampoline<
            P: IsA<ListModel>,
            F: Fn(&P, u32, u32, u32) + 'static,
        >(
            this: *mut ffi::GListModel,
            position: std::ffi::c_uint,
            removed: std::ffi::c_uint,
            added: std::ffi::c_uint,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                ListModel::from_glib_borrow(this).unsafe_cast_ref(),
                position,
                removed,
                added,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"items-changed".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    items_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<ListModel>> ListModelExt for O {}