gtk4/auto/
list_store.rs

Help
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#![allow(deprecated)]
5
6use crate::{ffi, Buildable, TreeDragDest, TreeDragSource, TreeIter, TreeModel, TreeSortable};
7use glib::translate::*;
8
9glib::wrapper! {
10    /// Use `Gio::ListStore` instead
11    /// A list-like data structure that can be used with the [`TreeView`][crate::TreeView].
12    ///
13    /// The [`ListStore`][crate::ListStore] object is a list model for use with a [`TreeView`][crate::TreeView]
14    /// widget.  It implements the [`TreeModel`][crate::TreeModel] interface, and consequentialy,
15    /// can use all of the methods available there.  It also implements the
16    /// [`TreeSortable`][crate::TreeSortable] interface so it can be sorted by the view.
17    /// Finally, it also implements the tree
18    /// [drag](iface.TreeDragSource.html) and [drop](iface.TreeDragDest.html)
19    /// interfaces.
20    ///
21    /// The [`ListStore`][crate::ListStore] can accept most `GType`s as a column type, though
22    /// it can’t accept all custom types.  Internally, it will keep a copy of
23    /// data passed in (such as a string or a boxed pointer).  Columns that
24    /// accept `GObject`s are handled a little differently.  The
25    /// [`ListStore`][crate::ListStore] will keep a reference to the object instead of copying the
26    /// value.  As a result, if the object is modified, it is up to the
27    /// application writer to call [`TreeModelExt::row_changed()`][crate::prelude::TreeModelExt::row_changed()] to emit the
28    /// [`row_changed`][struct@crate::TreeModel#row_changed] signal. This most commonly affects lists
29    /// with [`gdk::Texture`][crate::gdk::Texture]s stored.
30    ///
31    /// An example for creating a simple list store:
32    ///
33    /// **⚠️ The following code is in c ⚠️**
34    ///
35    /// ```c
36    /// enum {
37    ///   COLUMN_STRING,
38    ///   COLUMN_INT,
39    ///   COLUMN_BOOLEAN,
40    ///   N_COLUMNS
41    /// };
42    ///
43    /// {
44    ///   GtkListStore *list_store;
45    ///   GtkTreePath *path;
46    ///   GtkTreeIter iter;
47    ///   int i;
48    ///
49    ///   list_store = gtk_list_store_new (N_COLUMNS,
50    ///                                    G_TYPE_STRING,
51    ///                                    G_TYPE_INT,
52    ///                                    G_TYPE_BOOLEAN);
53    ///
54    ///   for (i = 0; i < 10; i++)
55    ///     {
56    ///       char *some_data;
57    ///
58    ///       some_data = get_some_data (i);
59    ///
60    ///       // Add a new row to the model
61    ///       gtk_list_store_append (list_store, &iter);
62    ///       gtk_list_store_set (list_store, &iter,
63    ///                           COLUMN_STRING, some_data,
64    ///                           COLUMN_INT, i,
65    ///                           COLUMN_BOOLEAN,  FALSE,
66    ///                           -1);
67    ///
68    ///       // As the store will keep a copy of the string internally,
69    ///       // we free some_data.
70    ///       g_free (some_data);
71    ///     }
72    ///
73    ///   // Modify a particular row
74    ///   path = gtk_tree_path_new_from_string ("4");
75    ///   gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
76    ///                            &iter,
77    ///                            path);
78    ///   gtk_tree_path_free (path);
79    ///   gtk_list_store_set (list_store, &iter,
80    ///                       COLUMN_BOOLEAN, TRUE,
81    ///                       -1);
82    /// }
83    /// ```
84    ///
85    /// [`ListStore`][crate::ListStore] is deprecated since GTK 4.10, and should not be used in newly
86    /// written code. You should use `Gio::ListStore` instead, and the various
87    /// list models provided by GTK.
88    ///
89    /// ## Performance Considerations
90    ///
91    /// Internally, the [`ListStore`][crate::ListStore] was originally implemented with a linked list
92    /// with a tail pointer.  As a result, it was fast at data insertion and deletion,
93    /// and not fast at random data access.  The [`ListStore`][crate::ListStore] sets the
94    /// `GTK_TREE_MODEL_ITERS_PERSIST` flag, which means that [`TreeIter`][crate::TreeIter]s can be
95    /// cached while the row exists.  Thus, if access to a particular row is needed
96    /// often and your code is expected to run on older versions of GTK, it is worth
97    /// keeping the iter around.
98    ///
99    /// ## Atomic Operations
100    ///
101    /// It is important to note that only the methods
102    /// gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv()
103    /// are atomic, in the sense that the row is being appended to the store and the
104    /// values filled in in a single operation with regard to [`TreeModel`][crate::TreeModel] signaling.
105    /// In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set()
106    /// will first create a row, which triggers the `GtkTreeModel::row-inserted` signal
107    /// on [`ListStore`][crate::ListStore]. The row, however, is still empty, and any signal handler
108    /// connecting to `GtkTreeModel::row-inserted` on this particular store should be prepared
109    /// for the situation that the row might be empty. This is especially important
110    /// if you are wrapping the [`ListStore`][crate::ListStore] inside a [`TreeModel`][crate::TreeModel]Filter and are
111    /// using a [`TreeModel`][crate::TreeModel]FilterVisibleFunc. Using any of the non-atomic operations
112    /// to append rows to the [`ListStore`][crate::ListStore] will cause the
113    /// [`TreeModel`][crate::TreeModel]FilterVisibleFunc to be visited with an empty row first; the
114    /// function must be prepared for that.
115    ///
116    /// ## GtkListStore as GtkBuildable
117    ///
118    /// The GtkListStore implementation of the [`Buildable`][crate::Buildable] interface allows
119    /// to specify the model columns with a `<columns>` element that may contain
120    /// multiple `<column>` elements, each specifying one model column. The “type”
121    /// attribute specifies the data type for the column.
122    ///
123    /// Additionally, it is possible to specify content for the list store
124    /// in the UI definition, with the `<data>` element. It can contain multiple
125    /// `<row>` elements, each specifying to content for one row of the list model.
126    /// Inside a `<row>`, the `<col>` elements specify the content for individual cells.
127    ///
128    /// Note that it is probably more common to define your models in the code,
129    /// and one might consider it a layering violation to specify the content of
130    /// a list store in a UI definition, data, not presentation, and common wisdom
131    /// is to separate the two, as far as possible.
132    ///
133    /// An example of a UI Definition fragment for a list store:
134    ///
135    /// ```xml
136    /// <object class="GtkListStore">
137    ///   <columns>
138    ///     <column type="gchararray"/>
139    ///     <column type="gchararray"/>
140    ///     <column type="gint"/>
141    ///   </columns>
142    ///   <data>
143    ///     <row>
144    ///       <col id="0">John</col>
145    ///       <col id="1">Doe</col>
146    ///       <col id="2">25</col>
147    ///     </row>
148    ///     <row>
149    ///       <col id="0">Johan</col>
150    ///       <col id="1">Dahlin</col>
151    ///       <col id="2">50</col>
152    ///     </row>
153    ///   </data>
154    /// </object>
155    /// ```
156    ///
157    /// # Implements
158    ///
159    /// [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`TreeDragDestExt`][trait@crate::prelude::TreeDragDestExt], [`TreeDragSourceExt`][trait@crate::prelude::TreeDragSourceExt], [`TreeModelExt`][trait@crate::prelude::TreeModelExt], [`TreeSortableExt`][trait@crate::prelude::TreeSortableExt], [`TreeModelExtManual`][trait@crate::prelude::TreeModelExtManual], [`TreeSortableExtManual`][trait@crate::prelude::TreeSortableExtManual]
160    #[doc(alias = "GtkListStore")]
161    pub struct ListStore(Object<ffi::GtkListStore, ffi::GtkListStoreClass>) @implements Buildable, TreeDragDest, TreeDragSource, TreeModel, TreeSortable;
162
163    match fn {
164        type_ => || ffi::gtk_list_store_get_type(),
165    }
166}
167
168impl ListStore {
169    /// Appends a new row to @self.  @iter will be changed to point to this new
170    /// row.  The row will be empty after this function is called.  To fill in
171    /// values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
172    ///
173    /// # Deprecated since 4.10
174    ///
175    /// Use list models
176    ///
177    /// # Returns
178    ///
179    ///
180    /// ## `iter`
181    /// An unset [`TreeIter`][crate::TreeIter] to set to the appended row
182    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
183    #[allow(deprecated)]
184    #[doc(alias = "gtk_list_store_append")]
185    pub fn append(&self) -> TreeIter {
186        unsafe {
187            let mut iter = TreeIter::uninitialized();
188            ffi::gtk_list_store_append(self.to_glib_none().0, iter.to_glib_none_mut().0);
189            iter
190        }
191    }
192
193    /// Removes all rows from the list store.
194    ///
195    /// # Deprecated since 4.10
196    ///
197    /// Use list models
198    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
199    #[allow(deprecated)]
200    #[doc(alias = "gtk_list_store_clear")]
201    pub fn clear(&self) {
202        unsafe {
203            ffi::gtk_list_store_clear(self.to_glib_none().0);
204        }
205    }
206
207    /// Creates a new row at @position.  @iter will be changed to point to this new
208    /// row.  If @position is -1 or is larger than the number of rows on the list,
209    /// then the new row will be appended to the list. The row will be empty after
210    /// this function is called.  To fill in values, you need to call
211    /// gtk_list_store_set() or gtk_list_store_set_value().
212    ///
213    /// # Deprecated since 4.10
214    ///
215    /// Use list models
216    /// ## `position`
217    /// position to insert the new row, or -1 for last
218    ///
219    /// # Returns
220    ///
221    ///
222    /// ## `iter`
223    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
224    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
225    #[allow(deprecated)]
226    #[doc(alias = "gtk_list_store_insert")]
227    pub fn insert(&self, position: i32) -> TreeIter {
228        unsafe {
229            let mut iter = TreeIter::uninitialized();
230            ffi::gtk_list_store_insert(self.to_glib_none().0, iter.to_glib_none_mut().0, position);
231            iter
232        }
233    }
234
235    /// Inserts a new row after @sibling. If @sibling is [`None`], then the row will be
236    /// prepended to the beginning of the list. @iter will be changed to point to
237    /// this new row. The row will be empty after this function is called. To fill
238    /// in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
239    ///
240    /// # Deprecated since 4.10
241    ///
242    /// Use list models
243    /// ## `sibling`
244    /// A valid [`TreeIter`][crate::TreeIter]
245    ///
246    /// # Returns
247    ///
248    ///
249    /// ## `iter`
250    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
251    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
252    #[allow(deprecated)]
253    #[doc(alias = "gtk_list_store_insert_after")]
254    pub fn insert_after(&self, sibling: Option<&TreeIter>) -> TreeIter {
255        unsafe {
256            let mut iter = TreeIter::uninitialized();
257            ffi::gtk_list_store_insert_after(
258                self.to_glib_none().0,
259                iter.to_glib_none_mut().0,
260                mut_override(sibling.to_glib_none().0),
261            );
262            iter
263        }
264    }
265
266    /// Inserts a new row before @sibling. If @sibling is [`None`], then the row will
267    /// be appended to the end of the list. @iter will be changed to point to this
268    /// new row. The row will be empty after this function is called. To fill in
269    /// values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
270    ///
271    /// # Deprecated since 4.10
272    ///
273    /// Use list models
274    /// ## `sibling`
275    /// A valid [`TreeIter`][crate::TreeIter]
276    ///
277    /// # Returns
278    ///
279    ///
280    /// ## `iter`
281    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
282    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
283    #[allow(deprecated)]
284    #[doc(alias = "gtk_list_store_insert_before")]
285    pub fn insert_before(&self, sibling: Option<&TreeIter>) -> TreeIter {
286        unsafe {
287            let mut iter = TreeIter::uninitialized();
288            ffi::gtk_list_store_insert_before(
289                self.to_glib_none().0,
290                iter.to_glib_none_mut().0,
291                mut_override(sibling.to_glib_none().0),
292            );
293            iter
294        }
295    }
296
297    /// Checks if the given iter is a valid iter for this [`ListStore`][crate::ListStore].
298    ///
299    /// This function is slow. Only use it for debugging and/or testing
300    /// purposes.
301    ///
302    /// # Deprecated since 4.10
303    ///
304    /// Use list models
305    /// ## `iter`
306    /// the iterator to check
307    ///
308    /// # Returns
309    ///
310    /// [`true`] if the iter is valid, [`false`] if the iter is invalid.
311    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
312    #[allow(deprecated)]
313    #[doc(alias = "gtk_list_store_iter_is_valid")]
314    pub fn iter_is_valid(&self, iter: &TreeIter) -> bool {
315        unsafe {
316            from_glib(ffi::gtk_list_store_iter_is_valid(
317                self.to_glib_none().0,
318                mut_override(iter.to_glib_none().0),
319            ))
320        }
321    }
322
323    /// Moves @iter in @self to the position after @position. Note that this
324    /// function only works with unsorted stores. If @position is [`None`], @iter
325    /// will be moved to the start of the list.
326    ///
327    /// # Deprecated since 4.10
328    ///
329    /// Use list models
330    /// ## `iter`
331    /// A [`TreeIter`][crate::TreeIter]
332    /// ## `position`
333    /// A [`TreeIter`][crate::TreeIter]
334    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
335    #[allow(deprecated)]
336    #[doc(alias = "gtk_list_store_move_after")]
337    pub fn move_after(&self, iter: &TreeIter, position: Option<&TreeIter>) {
338        unsafe {
339            ffi::gtk_list_store_move_after(
340                self.to_glib_none().0,
341                mut_override(iter.to_glib_none().0),
342                mut_override(position.to_glib_none().0),
343            );
344        }
345    }
346
347    /// Moves @iter in @self to the position before @position. Note that this
348    /// function only works with unsorted stores. If @position is [`None`], @iter
349    /// will be moved to the end of the list.
350    ///
351    /// # Deprecated since 4.10
352    ///
353    /// Use list models
354    /// ## `iter`
355    /// A [`TreeIter`][crate::TreeIter]
356    /// ## `position`
357    /// A [`TreeIter`][crate::TreeIter]
358    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
359    #[allow(deprecated)]
360    #[doc(alias = "gtk_list_store_move_before")]
361    pub fn move_before(&self, iter: &TreeIter, position: Option<&TreeIter>) {
362        unsafe {
363            ffi::gtk_list_store_move_before(
364                self.to_glib_none().0,
365                mut_override(iter.to_glib_none().0),
366                mut_override(position.to_glib_none().0),
367            );
368        }
369    }
370
371    /// Prepends a new row to @self. @iter will be changed to point to this new
372    /// row. The row will be empty after this function is called. To fill in
373    /// values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
374    ///
375    /// # Deprecated since 4.10
376    ///
377    /// Use list models
378    ///
379    /// # Returns
380    ///
381    ///
382    /// ## `iter`
383    /// An unset [`TreeIter`][crate::TreeIter] to set to the prepend row
384    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
385    #[allow(deprecated)]
386    #[doc(alias = "gtk_list_store_prepend")]
387    pub fn prepend(&self) -> TreeIter {
388        unsafe {
389            let mut iter = TreeIter::uninitialized();
390            ffi::gtk_list_store_prepend(self.to_glib_none().0, iter.to_glib_none_mut().0);
391            iter
392        }
393    }
394
395    /// Removes the given row from the list store.  After being removed,
396    /// @iter is set to be the next valid row, or invalidated if it pointed
397    /// to the last row in @self.
398    ///
399    /// # Deprecated since 4.10
400    ///
401    /// Use list models
402    /// ## `iter`
403    /// A valid [`TreeIter`][crate::TreeIter]
404    ///
405    /// # Returns
406    ///
407    /// [`true`] if @iter is valid, [`false`] if not.
408    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
409    #[allow(deprecated)]
410    #[doc(alias = "gtk_list_store_remove")]
411    pub fn remove(&self, iter: &TreeIter) -> bool {
412        unsafe {
413            from_glib(ffi::gtk_list_store_remove(
414                self.to_glib_none().0,
415                mut_override(iter.to_glib_none().0),
416            ))
417        }
418    }
419
420    /// Swaps @a and @b in @self. Note that this function only works with
421    /// unsorted stores.
422    ///
423    /// # Deprecated since 4.10
424    ///
425    /// Use list models
426    /// ## `a`
427    /// A [`TreeIter`][crate::TreeIter]
428    /// ## `b`
429    /// Another [`TreeIter`][crate::TreeIter]
430    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
431    #[allow(deprecated)]
432    #[doc(alias = "gtk_list_store_swap")]
433    pub fn swap(&self, a: &TreeIter, b: &TreeIter) {
434        unsafe {
435            ffi::gtk_list_store_swap(
436                self.to_glib_none().0,
437                mut_override(a.to_glib_none().0),
438                mut_override(b.to_glib_none().0),
439            );
440        }
441    }
442}
gtk4/auto/list_store.rs

gtk4/auto/
list_store.rs
