gio/auto/
list_model.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::ffi;
6use glib::{
7    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// `GListModel` is an interface that represents a mutable list of
16    /// [`glib::Object`][crate::glib::Object]. Its main intention is as a model for various widgets
17    /// in user interfaces, such as list views, but it can also be used as a
18    /// convenient method of returning lists of data, with support for
19    /// updates.
20    ///
21    /// Each object in the list may also report changes in itself via some
22    /// mechanism (normally the [`notify`][struct@crate::glib::Object#notify] signal).  Taken
23    /// together with the [`items-changed`][struct@crate::ListModel#items-changed] signal, this provides
24    /// for a list that can change its membership, and in which the members can
25    /// change their individual properties.
26    ///
27    /// A good example would be the list of visible wireless network access
28    /// points, where each access point can report dynamic properties such as
29    /// signal strength.
30    ///
31    /// It is important to note that the `GListModel` itself does not report
32    /// changes to the individual items.  It only reports changes to the list
33    /// membership.  If you want to observe changes to the objects themselves
34    /// then you need to connect signals to the objects that you are
35    /// interested in.
36    ///
37    /// All items in a `GListModel` are of (or derived from) the same type.
38    /// [`ListModelExt::item_type()`][crate::prelude::ListModelExt::item_type()] returns that type.  The type may be an
39    /// interface, in which case all objects in the list must implement it.
40    ///
41    /// The semantics are close to that of an array:
42    /// [`ListModelExt::n_items()`][crate::prelude::ListModelExt::n_items()] returns the number of items in the list
43    /// and `Gio::ListModel::get_item()` returns an item at a (0-based) position.
44    /// In order to allow implementations to calculate the list length lazily,
45    /// you can also iterate over items: starting from 0, repeatedly call
46    /// `Gio::ListModel::get_item()` until it returns `NULL`.
47    ///
48    /// An implementation may create objects lazily, but must take care to
49    /// return the same object for a given position until all references to
50    /// it are gone.
51    ///
52    /// On the other side, a consumer is expected only to hold references on
53    /// objects that are currently ‘user visible’, in order to facilitate the
54    /// maximum level of laziness in the implementation of the list and to
55    /// reduce the required number of signal connections at a given time.
56    ///
57    /// This interface is intended only to be used from a single thread.  The
58    /// thread in which it is appropriate to use it depends on the particular
59    /// implementation, but typically it will be from the thread that owns
60    /// the thread-default main context (see
61    /// [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()]) in effect at the time that the
62    /// model was created.
63    ///
64    /// Over time, it has established itself as good practice for list model
65    /// implementations to provide properties `item-type` and `n-items` to
66    /// ease working with them. While it is not required, it is recommended
67    /// that implementations provide these two properties. They should return
68    /// the values of [`ListModelExt::item_type()`][crate::prelude::ListModelExt::item_type()] and
69    /// [`ListModelExt::n_items()`][crate::prelude::ListModelExt::n_items()] respectively and be defined as such:
70    ///
71    /// **⚠️ The following code is in c ⚠️**
72    ///
73    /// ```c
74    /// properties[PROP_ITEM_TYPE] =
75    ///   g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT,
76    ///                       G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
77    /// properties[PROP_N_ITEMS] =
78    ///   g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0,
79    ///                      G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
80    /// ```
81    ///
82    /// ## Signals
83    ///
84    ///
85    /// #### `items-changed`
86    ///  This signal is emitted whenever items were added to or removed
87    /// from @list. At @position, @removed items were removed and @added
88    /// items were added in their place.
89    ///
90    /// Note: If `removed != added`, the positions of all later items
91    /// in the model change.
92    ///
93    ///
94    ///
95    /// # Implements
96    ///
97    /// [`ListModelExt`][trait@crate::prelude::ListModelExt], [`ListModelExtManual`][trait@crate::prelude::ListModelExtManual]
98    #[doc(alias = "GListModel")]
99    pub struct ListModel(Interface<ffi::GListModel, ffi::GListModelInterface>);
100
101    match fn {
102        type_ => || ffi::g_list_model_get_type(),
103    }
104}
105
106impl ListModel {
107    pub const NONE: Option<&'static ListModel> = None;
108}
109
110mod sealed {
111    pub trait Sealed {}
112    impl<T: super::IsA<super::ListModel>> Sealed for T {}
113}
114
115/// Trait containing all [`struct@ListModel`] methods.
116///
117/// # Implementors
118///
119/// [`ListModel`][struct@crate::ListModel], [`ListStore`][struct@crate::ListStore]
120pub trait ListModelExt: IsA<ListModel> + sealed::Sealed + 'static {
121    /// Gets the type of the items in @self.
122    ///
123    /// All items returned from g_list_model_get_item() are of the type
124    /// returned by this function, or a subtype, or if the type is an
125    /// interface, they are an implementation of that interface.
126    ///
127    /// The item type of a #GListModel can not change during the life of the
128    /// model.
129    ///
130    /// # Returns
131    ///
132    /// the #GType of the items contained in @self.
133    #[doc(alias = "g_list_model_get_item_type")]
134    #[doc(alias = "get_item_type")]
135    fn item_type(&self) -> glib::types::Type {
136        unsafe {
137            from_glib(ffi::g_list_model_get_item_type(
138                self.as_ref().to_glib_none().0,
139            ))
140        }
141    }
142
143    /// Gets the number of items in @self.
144    ///
145    /// Depending on the model implementation, calling this function may be
146    /// less efficient than iterating the list with increasing values for
147    /// @position until g_list_model_get_item() returns [`None`].
148    ///
149    /// # Returns
150    ///
151    /// the number of items in @self.
152    #[doc(alias = "g_list_model_get_n_items")]
153    #[doc(alias = "get_n_items")]
154    fn n_items(&self) -> u32 {
155        unsafe { ffi::g_list_model_get_n_items(self.as_ref().to_glib_none().0) }
156    }
157
158    /// Get the item at @position.
159    ///
160    /// If @position is greater than the number of items in @self, [`None`] is
161    /// returned.
162    ///
163    /// [`None`] is never returned for an index that is smaller than the length
164    /// of the list.
165    ///
166    /// This function is meant to be used by language bindings in place
167    /// of g_list_model_get_item().
168    ///
169    /// See also: g_list_model_get_n_items()
170    /// ## `position`
171    /// the position of the item to fetch
172    ///
173    /// # Returns
174    ///
175    /// the object at @position.
176    #[doc(alias = "g_list_model_get_object")]
177    #[doc(alias = "get_object")]
178    fn item(&self, position: u32) -> Option<glib::Object> {
179        unsafe {
180            from_glib_full(ffi::g_list_model_get_object(
181                self.as_ref().to_glib_none().0,
182                position,
183            ))
184        }
185    }
186
187    /// Emits the #GListModel::items-changed signal on @self.
188    ///
189    /// This function should only be called by classes implementing
190    /// #GListModel. It has to be called after the internal representation
191    /// of @self has been updated, because handlers connected to this signal
192    /// might query the new state of the list.
193    ///
194    /// Implementations must only make changes to the model (as visible to
195    /// its consumer) in places that will not cause problems for that
196    /// consumer.  For models that are driven directly by a write API (such
197    /// as #GListStore), changes can be reported in response to uses of that
198    /// API.  For models that represent remote data, changes should only be
199    /// made from a fresh mainloop dispatch.  It is particularly not
200    /// permitted to make changes in response to a call to the #GListModel
201    /// consumer API.
202    ///
203    /// Stated another way: in general, it is assumed that code making a
204    /// series of accesses to the model via the API, without returning to the
205    /// mainloop, and without calling other code, will continue to view the
206    /// same contents of the model.
207    /// ## `position`
208    /// the position at which @self changed
209    /// ## `removed`
210    /// the number of items removed
211    /// ## `added`
212    /// the number of items added
213    #[doc(alias = "g_list_model_items_changed")]
214    fn items_changed(&self, position: u32, removed: u32, added: u32) {
215        unsafe {
216            ffi::g_list_model_items_changed(
217                self.as_ref().to_glib_none().0,
218                position,
219                removed,
220                added,
221            );
222        }
223    }
224
225    /// This signal is emitted whenever items were added to or removed
226    /// from @list. At @position, @removed items were removed and @added
227    /// items were added in their place.
228    ///
229    /// Note: If `removed != added`, the positions of all later items
230    /// in the model change.
231    /// ## `position`
232    /// the position at which @list changed
233    /// ## `removed`
234    /// the number of items removed
235    /// ## `added`
236    /// the number of items added
237    #[doc(alias = "items-changed")]
238    fn connect_items_changed<F: Fn(&Self, u32, u32, u32) + 'static>(
239        &self,
240        f: F,
241    ) -> SignalHandlerId {
242        unsafe extern "C" fn items_changed_trampoline<
243            P: IsA<ListModel>,
244            F: Fn(&P, u32, u32, u32) + 'static,
245        >(
246            this: *mut ffi::GListModel,
247            position: std::ffi::c_uint,
248            removed: std::ffi::c_uint,
249            added: std::ffi::c_uint,
250            f: glib::ffi::gpointer,
251        ) {
252            let f: &F = &*(f as *const F);
253            f(
254                ListModel::from_glib_borrow(this).unsafe_cast_ref(),
255                position,
256                removed,
257                added,
258            )
259        }
260        unsafe {
261            let f: Box_<F> = Box_::new(f);
262            connect_raw(
263                self.as_ptr() as *mut _,
264                b"items-changed\0".as_ptr() as *const _,
265                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
266                    items_changed_trampoline::<Self, F> as *const (),
267                )),
268                Box_::into_raw(f),
269            )
270        }
271    }
272}
273
274impl<O: IsA<ListModel>> ListModelExt for O {}