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 {}