// 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 glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute};

glib::wrapper! {
    /// [`ListModel`][crate::ListModel] is an interface that represents a mutable list of
    /// `GObjects`. 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 [`ListModel`][crate::ListModel] 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 [`ListModel`][crate::ListModel] 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
    /// `g_list_model_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
    /// `g_list_model_get_item()` until it returns [`None`].
    ///
    /// 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][g-main-context-push-thread-default]
    /// in effect at the time that the model was created.
    ///
    /// Over time, it has established itself as good practice for listmodel
    /// 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", "", "", G_TYPE_OBJECT,
    ///                       G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    /// properties[PROP_N_ITEMS] =
    ///   g_param_spec_uint ("n-items", "", "", 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;
}

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

/// Trait containing all [`struct@ListModel`] methods.
///
/// # Implementors
///
/// [`ListModel`][struct@crate::ListModel], [`ListStore`][struct@crate::ListStore]
pub trait ListModelExt: IsA<ListModel> + sealed::Sealed + '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 [`ListModel`][crate::ListModel] 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: [`n_items()`][Self::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 [`items-changed`][struct@crate::ListModel#items-changed] signal on `self`.
    ///
    /// This function should only be called by classes implementing
    /// [`ListModel`][crate::ListModel]. 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 [`ListStore`][crate::ListStore]), 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 [`ListModel`][crate::ListModel]
    /// 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: libc::c_uint,
            removed: libc::c_uint,
            added: libc::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 _,
                b"items-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    items_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

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

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