gtk4/auto/
selection_model.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
// 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, Bitset};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`SelectionModel`][crate::SelectionModel] is an interface that add support for selection to list models.
    ///
    /// This support is then used by widgets using list models to add the ability
    /// to select and unselect various items.
    ///
    /// GTK provides default implementations of the most common selection modes such
    /// as [`SingleSelection`][crate::SingleSelection], so you will only need to implement this
    /// interface if you want detailed control about how selections should be handled.
    ///
    /// A [`SelectionModel`][crate::SelectionModel] supports a single boolean per item indicating if an item is
    /// selected or not. This can be queried via [`SelectionModelExt::is_selected()`][crate::prelude::SelectionModelExt::is_selected()].
    /// When the selected state of one or more items changes, the model will emit the
    /// [`selection-changed`][struct@crate::SelectionModel#selection-changed] signal by calling the
    /// [`SelectionModelExt::selection_changed()`][crate::prelude::SelectionModelExt::selection_changed()] function. The positions given
    /// in that signal may have their selection state changed, though that is not a
    /// requirement. If new items added to the model via the
    /// [`items-changed`][struct@crate::gio::ListModel#items-changed] signal are selected or not is up to the
    /// implementation.
    ///
    /// Note that items added via [`items-changed`][struct@crate::gio::ListModel#items-changed] may already
    /// be selected and no [`selection-changed`][struct@crate::SelectionModel#selection-changed] will be
    /// emitted for them. So to track which items are selected, it is necessary to
    /// listen to both signals.
    ///
    /// Additionally, the interface can expose functionality to select and unselect
    /// items. If these functions are implemented, GTK's list widgets will allow users
    /// to select and unselect items. However, [`SelectionModel`][crate::SelectionModel]s are free to only
    /// implement them partially or not at all. In that case the widgets will not
    /// support the unimplemented operations.
    ///
    /// When selecting or unselecting is supported by a model, the return values of
    /// the selection functions do *not* indicate if selection or unselection happened.
    /// They are only meant to indicate complete failure, like when this mode of
    /// selecting is not supported by the model.
    ///
    /// Selections may happen asynchronously, so the only reliable way to find out
    /// when an item was selected is to listen to the signals that indicate selection.
    ///
    /// ## Signals
    ///
    ///
    /// #### `selection-changed`
    ///  Emitted when the selection state of some of the items in @model changes.
    ///
    /// Note that this signal does not specify the new selection state of the
    /// items, they need to be queried manually. It is also not necessary for
    /// a model to change the selection state of any of the items in the selection
    /// model, though it would be rather useless to emit such a signal.
    ///
    ///
    /// <details><summary><h4>ListModel</h4></summary>
    ///
    ///
    /// #### `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.
    ///
    ///
    /// </details>
    ///
    /// # Implements
    ///
    /// [`SelectionModelExt`][trait@crate::prelude::SelectionModelExt], [`trait@gio::prelude::ListModelExt`]
    #[doc(alias = "GtkSelectionModel")]
    pub struct SelectionModel(Interface<ffi::GtkSelectionModel, ffi::GtkSelectionModelInterface>) @requires gio::ListModel;

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

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

/// Trait containing all [`struct@SelectionModel`] methods.
///
/// # Implementors
///
/// [`MultiSelection`][struct@crate::MultiSelection], [`NoSelection`][struct@crate::NoSelection], [`SelectionModel`][struct@crate::SelectionModel], [`SingleSelection`][struct@crate::SingleSelection]
pub trait SelectionModelExt: IsA<SelectionModel> + 'static {
    /// Gets the set containing all currently selected items in the model.
    ///
    /// This function may be slow, so if you are only interested in single item,
    /// consider using [`is_selected()`][Self::is_selected()] or if you are only
    /// interested in a few, consider [`selection_in_range()`][Self::selection_in_range()].
    ///
    /// # Returns
    ///
    /// a [`Bitset`][crate::Bitset] containing all the values currently
    ///   selected in @self. If no items are selected, the bitset is empty.
    ///   The bitset must not be modified.
    #[doc(alias = "gtk_selection_model_get_selection")]
    #[doc(alias = "get_selection")]
    fn selection(&self) -> Bitset {
        unsafe {
            from_glib_full(ffi::gtk_selection_model_get_selection(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the set of selected items in a range.
    ///
    /// This function is an optimization for
    /// [`selection()`][Self::selection()] when you are only
    /// interested in part of the model's selected state. A common use
    /// case is in response to the [`selection-changed`][struct@crate::SelectionModel#selection-changed]
    /// signal.
    /// ## `position`
    /// start of the queried range
    /// ## `n_items`
    /// number of items in the queried range
    ///
    /// # Returns
    ///
    /// A [`Bitset`][crate::Bitset] that matches the selection state
    ///   for the given range with all other values being undefined.
    ///   The bitset must not be modified.
    #[doc(alias = "gtk_selection_model_get_selection_in_range")]
    #[doc(alias = "get_selection_in_range")]
    fn selection_in_range(&self, position: u32, n_items: u32) -> Bitset {
        unsafe {
            from_glib_full(ffi::gtk_selection_model_get_selection_in_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            ))
        }
    }

    /// Checks if the given item is selected.
    /// ## `position`
    /// the position of the item to query
    ///
    /// # Returns
    ///
    /// [`true`] if the item is selected
    #[doc(alias = "gtk_selection_model_is_selected")]
    fn is_selected(&self, position: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_is_selected(
                self.as_ref().to_glib_none().0,
                position,
            ))
        }
    }

    /// Requests to select all items in the model.
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items are now selected.
    #[doc(alias = "gtk_selection_model_select_all")]
    fn select_all(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_all(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Requests to select an item in the model.
    /// ## `position`
    /// the position of the item to select
    /// ## `unselect_rest`
    /// whether previously selected items should be unselected
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the item was selected.
    #[doc(alias = "gtk_selection_model_select_item")]
    fn select_item(&self, position: u32, unselect_rest: bool) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_item(
                self.as_ref().to_glib_none().0,
                position,
                unselect_rest.into_glib(),
            ))
        }
    }

    /// Requests to select a range of items in the model.
    /// ## `position`
    /// the first item to select
    /// ## `n_items`
    /// the number of items to select
    /// ## `unselect_rest`
    /// whether previously selected items should be unselected
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the range was selected.
    #[doc(alias = "gtk_selection_model_select_range")]
    fn select_range(&self, position: u32, n_items: u32, unselect_rest: bool) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_select_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
                unselect_rest.into_glib(),
            ))
        }
    }

    /// Helper function for implementations of [`SelectionModel`][crate::SelectionModel].
    ///
    /// Call this when the selection changes to emit the
    /// [`selection-changed`][struct@crate::SelectionModel#selection-changed] signal.
    /// ## `position`
    /// the first changed item
    /// ## `n_items`
    /// the number of changed items
    #[doc(alias = "gtk_selection_model_selection_changed")]
    fn selection_changed(&self, position: u32, n_items: u32) {
        unsafe {
            ffi::gtk_selection_model_selection_changed(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            );
        }
    }

    /// Make selection changes.
    ///
    /// This is the most advanced selection updating method that allows
    /// the most fine-grained control over selection changes. If you can,
    /// you should try the simpler versions, as implementations are more
    /// likely to implement support for those.
    ///
    /// Requests that the selection state of all positions set in @mask
    /// be updated to the respective value in the @selected bitmask.
    ///
    /// In pseudocode, it would look something like this:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// for (i = 0; i < n_items; i++)
    ///   {
    ///     // don't change values not in the mask
    ///     if (!gtk_bitset_contains (mask, i))
    ///       continue;
    ///
    ///     if (gtk_bitset_contains (selected, i))
    ///       select_item (i);
    ///     else
    ///       unselect_item (i);
    ///   }
    ///
    /// gtk_selection_model_selection_changed (model,
    ///                                        first_changed_item,
    ///                                        n_changed_items);
    /// ```
    ///
    /// @mask and @selected must not be modified. They may refer to the
    /// same bitset, which would mean that every item in the set should
    /// be selected.
    /// ## `selected`
    /// bitmask specifying if items should be selected or unselected
    /// ## `mask`
    /// bitmask specifying which items should be updated
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items were updated according
    ///   to the inputs.
    #[doc(alias = "gtk_selection_model_set_selection")]
    fn set_selection(&self, selected: &Bitset, mask: &Bitset) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_set_selection(
                self.as_ref().to_glib_none().0,
                selected.to_glib_none().0,
                mask.to_glib_none().0,
            ))
        }
    }

    /// Requests to unselect all items in the model.
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean that all items are now unselected.
    #[doc(alias = "gtk_selection_model_unselect_all")]
    fn unselect_all(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_all(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Requests to unselect an item in the model.
    /// ## `position`
    /// the position of the item to unselect
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the item was unselected.
    #[doc(alias = "gtk_selection_model_unselect_item")]
    fn unselect_item(&self, position: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_item(
                self.as_ref().to_glib_none().0,
                position,
            ))
        }
    }

    /// Requests to unselect a range of items in the model.
    /// ## `position`
    /// the first item to unselect
    /// ## `n_items`
    /// the number of items to unselect
    ///
    /// # Returns
    ///
    /// [`true`] if this action was supported and no fallback should be
    ///   tried. This does not mean the range was unselected.
    #[doc(alias = "gtk_selection_model_unselect_range")]
    fn unselect_range(&self, position: u32, n_items: u32) -> bool {
        unsafe {
            from_glib(ffi::gtk_selection_model_unselect_range(
                self.as_ref().to_glib_none().0,
                position,
                n_items,
            ))
        }
    }

    /// Emitted when the selection state of some of the items in @model changes.
    ///
    /// Note that this signal does not specify the new selection state of the
    /// items, they need to be queried manually. It is also not necessary for
    /// a model to change the selection state of any of the items in the selection
    /// model, though it would be rather useless to emit such a signal.
    /// ## `position`
    /// The first item that may have changed
    /// ## `n_items`
    /// number of items with changes
    #[doc(alias = "selection-changed")]
    fn connect_selection_changed<F: Fn(&Self, u32, u32) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn selection_changed_trampoline<
            P: IsA<SelectionModel>,
            F: Fn(&P, u32, u32) + 'static,
        >(
            this: *mut ffi::GtkSelectionModel,
            position: std::ffi::c_uint,
            n_items: std::ffi::c_uint,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                SelectionModel::from_glib_borrow(this).unsafe_cast_ref(),
                position,
                n_items,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"selection-changed\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    selection_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<SelectionModel>> SelectionModelExt for O {}