dear_imgui_rs/widget/
list_box.rs

1//! List boxes
2//!
3//! Classic list-box widget and builder for fixed-height item selection.
4//!
5use std::borrow::Cow;
6
7use crate::Ui;
8use crate::sys;
9
10fn assert_finite_vec2(caller: &str, name: &str, value: [f32; 2]) {
11    assert!(
12        value[0].is_finite() && value[1].is_finite(),
13        "{caller} {name} must contain finite values"
14    );
15}
16
17/// # List Box Widgets
18impl Ui {
19    /// Constructs a new list box builder.
20    pub fn list_box_config<T: AsRef<str>>(&self, label: T) -> ListBox<T> {
21        ListBox::new(label)
22    }
23}
24
25/// Builder for a list box widget
26#[derive(Clone, Debug)]
27#[must_use]
28pub struct ListBox<T> {
29    label: T,
30    size: [f32; 2],
31}
32
33impl<T: AsRef<str>> ListBox<T> {
34    /// Constructs a new list box builder.
35    #[doc(alias = "ListBoxHeaderVec2", alias = "ListBoxHeaderInt")]
36    pub fn new(label: T) -> ListBox<T> {
37        ListBox {
38            label,
39            size: [0.0, 0.0],
40        }
41    }
42
43    /// Sets the list box size based on the given width and height
44    /// If width or height are 0 or smaller, a default value is calculated
45    /// Helper to calculate the size of a listbox and display a label on the right.
46    /// Tip: To have a list filling the entire window width, PushItemWidth(-1) and pass an non-visible label e.g. "##empty"
47    ///
48    /// Default: [0.0, 0.0], in which case the combobox calculates a sensible width and height
49    #[inline]
50    pub fn size(mut self, size: impl Into<[f32; 2]>) -> Self {
51        self.size = size.into();
52        self
53    }
54    /// Creates a list box and starts appending to it.
55    ///
56    /// Returns `Some(ListBoxToken)` if the list box is open. After content has been
57    /// rendered, the token must be ended by calling `.end()`.
58    ///
59    /// Returns `None` if the list box is not open and no content should be rendered.
60    #[must_use]
61    pub fn begin(self, ui: &Ui) -> Option<ListBoxToken<'_>> {
62        assert_finite_vec2("ListBox::begin()", "size", self.size);
63        let size_vec = sys::ImVec2 {
64            x: self.size[0],
65            y: self.size[1],
66        };
67        let label_ptr = ui.scratch_txt(self.label);
68        let should_render =
69            ui.run_with_bound_context(|| unsafe { sys::igBeginListBox(label_ptr, size_vec) });
70        if should_render {
71            Some(ListBoxToken::new(ui))
72        } else {
73            None
74        }
75    }
76    /// Creates a list box and runs a closure to construct the list contents.
77    /// Returns the result of the closure, if it is called.
78    ///
79    /// Note: the closure is not called if the list box is not open.
80    pub fn build<R, F: FnOnce() -> R>(self, ui: &Ui, f: F) -> Option<R> {
81        self.begin(ui).map(|_list| f())
82    }
83}
84
85/// Tracks a list box that can be ended by calling `.end()`
86/// or by dropping
87pub struct ListBoxToken<'ui> {
88    _ui: &'ui Ui,
89}
90
91impl<'ui> ListBoxToken<'ui> {
92    /// Creates a new list box token
93    pub fn new(ui: &'ui Ui) -> Self {
94        Self { _ui: ui }
95    }
96
97    /// Ends the list box
98    pub fn end(self) {
99        // The drop implementation will handle the actual ending
100    }
101}
102
103impl<'ui> Drop for ListBoxToken<'ui> {
104    fn drop(&mut self) {
105        self._ui
106            .run_with_bound_context(|| unsafe { sys::igEndListBox() });
107    }
108}
109
110/// # Convenience functions
111impl<T: AsRef<str>> ListBox<T> {
112    /// Builds a simple list box for choosing from a slice of values
113    pub fn build_simple<V, L>(
114        self,
115        ui: &Ui,
116        current_item: &mut usize,
117        items: &[V],
118        label_fn: &L,
119    ) -> bool
120    where
121        for<'b> L: Fn(&'b V) -> Cow<'b, str>,
122    {
123        let mut result = false;
124        let lb = self;
125        if let Some(_cb) = lb.begin(ui) {
126            for (idx, item) in items.iter().enumerate() {
127                let text = label_fn(item);
128                let selected = idx == *current_item;
129                if ui.selectable_config(&text).selected(selected).build() {
130                    *current_item = idx;
131                    result = true;
132                }
133            }
134        }
135        result
136    }
137
138    /// Builds a simple list box for choosing from a slice of values using an `i32` index.
139    ///
140    /// This is useful when you want to represent \"no selection\" with `-1`, matching Dear ImGui's
141    /// list-box patterns that use an `int*` index.
142    pub fn build_simple_i32<V, L>(
143        self,
144        ui: &Ui,
145        current_item: &mut i32,
146        items: &[V],
147        label_fn: &L,
148    ) -> bool
149    where
150        for<'b> L: Fn(&'b V) -> Cow<'b, str>,
151    {
152        let mut result = false;
153        let lb = self;
154        if let Some(_cb) = lb.begin(ui) {
155            for (idx, item) in items.iter().enumerate() {
156                if idx > i32::MAX as usize {
157                    break;
158                }
159                let idx_i32 = idx as i32;
160                let text = label_fn(item);
161                let selected = idx_i32 == *current_item;
162                if ui.selectable_config(&text).selected(selected).build() {
163                    *current_item = idx_i32;
164                    result = true;
165                }
166            }
167        }
168        result
169    }
170}
dear_imgui_rs/widget/list_box.rs

dear_imgui_rs/widget/
list_box.rs
