egui/containers/
combo_box.rs

1use epaint::Shape;
2
3use crate::{
4    Align2, Context, Id, InnerResponse, NumExt as _, Painter, Popup, PopupCloseBehavior, Rect,
5    Response, ScrollArea, Sense, Stroke, TextStyle, TextWrapMode, Ui, UiBuilder, Vec2, WidgetInfo,
6    WidgetText, WidgetType, epaint, style::StyleModifier, style::WidgetVisuals, vec2,
7};
8
9#[expect(unused_imports)] // Documentation
10use crate::style::Spacing;
11
12/// A function that paints the [`ComboBox`] icon
13pub type IconPainter = Box<dyn FnOnce(&Ui, Rect, &WidgetVisuals, bool)>;
14
15/// A drop-down selection menu with a descriptive label.
16///
17/// ```
18/// # egui::__run_test_ui(|ui| {
19/// # #[derive(Debug, PartialEq, Copy, Clone)]
20/// # enum Enum { First, Second, Third }
21/// # let mut selected = Enum::First;
22/// let before = selected;
23/// egui::ComboBox::from_label("Select one!")
24///     .selected_text(format!("{:?}", selected))
25///     .show_ui(ui, |ui| {
26///         ui.selectable_value(&mut selected, Enum::First, "First");
27///         ui.selectable_value(&mut selected, Enum::Second, "Second");
28///         ui.selectable_value(&mut selected, Enum::Third, "Third");
29///     }
30/// );
31///
32/// if selected != before {
33///     // Handle selection change
34/// }
35/// # });
36/// ```
37#[must_use = "You should call .show*"]
38pub struct ComboBox {
39    id_salt: Id,
40    label: Option<WidgetText>,
41    selected_text: WidgetText,
42    width: Option<f32>,
43    height: Option<f32>,
44    icon: Option<IconPainter>,
45    wrap_mode: Option<TextWrapMode>,
46    close_behavior: Option<PopupCloseBehavior>,
47    popup_style: StyleModifier,
48}
49
50impl ComboBox {
51    /// Create new [`ComboBox`] with id and label
52    pub fn new(id_salt: impl std::hash::Hash, label: impl Into<WidgetText>) -> Self {
53        Self {
54            id_salt: Id::new(id_salt),
55            label: Some(label.into()),
56            selected_text: Default::default(),
57            width: None,
58            height: None,
59            icon: None,
60            wrap_mode: None,
61            close_behavior: None,
62            popup_style: StyleModifier::default(),
63        }
64    }
65
66    /// Label shown next to the combo box
67    pub fn from_label(label: impl Into<WidgetText>) -> Self {
68        let label = label.into();
69        Self {
70            id_salt: Id::new(label.text()),
71            label: Some(label),
72            selected_text: Default::default(),
73            width: None,
74            height: None,
75            icon: None,
76            wrap_mode: None,
77            close_behavior: None,
78            popup_style: StyleModifier::default(),
79        }
80    }
81
82    /// Without label.
83    pub fn from_id_salt(id_salt: impl std::hash::Hash) -> Self {
84        Self {
85            id_salt: Id::new(id_salt),
86            label: Default::default(),
87            selected_text: Default::default(),
88            width: None,
89            height: None,
90            icon: None,
91            wrap_mode: None,
92            close_behavior: None,
93            popup_style: StyleModifier::default(),
94        }
95    }
96
97    /// Without label.
98    #[deprecated = "Renamed from_id_salt"]
99    pub fn from_id_source(id_salt: impl std::hash::Hash) -> Self {
100        Self::from_id_salt(id_salt)
101    }
102
103    /// Set the outer width of the button and menu.
104    ///
105    /// Default is [`Spacing::combo_width`].
106    #[inline]
107    pub fn width(mut self, width: f32) -> Self {
108        self.width = Some(width);
109        self
110    }
111
112    /// Set the maximum outer height of the menu.
113    ///
114    /// Default is [`Spacing::combo_height`].
115    #[inline]
116    pub fn height(mut self, height: f32) -> Self {
117        self.height = Some(height);
118        self
119    }
120
121    /// What we show as the currently selected value
122    #[inline]
123    pub fn selected_text(mut self, selected_text: impl Into<WidgetText>) -> Self {
124        self.selected_text = selected_text.into();
125        self
126    }
127
128    /// Use the provided function to render a different [`ComboBox`] icon.
129    /// Defaults to a triangle that expands when the cursor is hovering over the [`ComboBox`].
130    ///
131    /// For example:
132    /// ```
133    /// # egui::__run_test_ui(|ui| {
134    /// # let text = "Selected text";
135    /// pub fn filled_triangle(
136    ///     ui: &egui::Ui,
137    ///     rect: egui::Rect,
138    ///     visuals: &egui::style::WidgetVisuals,
139    ///     _is_open: bool,
140    /// ) {
141    ///     let rect = egui::Rect::from_center_size(
142    ///         rect.center(),
143    ///         egui::vec2(rect.width() * 0.6, rect.height() * 0.4),
144    ///     );
145    ///     ui.painter().add(egui::Shape::convex_polygon(
146    ///         vec![rect.left_top(), rect.right_top(), rect.center_bottom()],
147    ///         visuals.fg_stroke.color,
148    ///         visuals.fg_stroke,
149    ///     ));
150    /// }
151    ///
152    /// egui::ComboBox::from_id_salt("my-combobox")
153    ///     .selected_text(text)
154    ///     .icon(filled_triangle)
155    ///     .show_ui(ui, |_ui| {});
156    /// # });
157    /// ```
158    #[inline]
159    pub fn icon(mut self, icon_fn: impl FnOnce(&Ui, Rect, &WidgetVisuals, bool) + 'static) -> Self {
160        self.icon = Some(Box::new(icon_fn));
161        self
162    }
163
164    /// Controls the wrap mode used for the selected text.
165    ///
166    /// By default, [`Ui::wrap_mode`] will be used, which can be overridden with [`crate::Style::wrap_mode`].
167    ///
168    /// Note that any `\n` in the text will always produce a new line.
169    #[inline]
170    pub fn wrap_mode(mut self, wrap_mode: TextWrapMode) -> Self {
171        self.wrap_mode = Some(wrap_mode);
172        self
173    }
174
175    /// Set [`Self::wrap_mode`] to [`TextWrapMode::Wrap`].
176    #[inline]
177    pub fn wrap(mut self) -> Self {
178        self.wrap_mode = Some(TextWrapMode::Wrap);
179        self
180    }
181
182    /// Set [`Self::wrap_mode`] to [`TextWrapMode::Truncate`].
183    #[inline]
184    pub fn truncate(mut self) -> Self {
185        self.wrap_mode = Some(TextWrapMode::Truncate);
186        self
187    }
188
189    /// Controls the close behavior for the popup.
190    ///
191    /// By default, `PopupCloseBehavior::CloseOnClick` will be used.
192    #[inline]
193    pub fn close_behavior(mut self, close_behavior: PopupCloseBehavior) -> Self {
194        self.close_behavior = Some(close_behavior);
195        self
196    }
197
198    /// Set the style of the popup menu.
199    ///
200    /// Could for example be used with [`crate::containers::menu::menu_style`] to get the frame-less
201    /// menu button style.
202    #[inline]
203    pub fn popup_style(mut self, popup_style: StyleModifier) -> Self {
204        self.popup_style = popup_style;
205        self
206    }
207
208    /// Show the combo box, with the given ui code for the menu contents.
209    ///
210    /// Returns `InnerResponse { inner: None }` if the combo box is closed.
211    pub fn show_ui<R>(
212        self,
213        ui: &mut Ui,
214        menu_contents: impl FnOnce(&mut Ui) -> R,
215    ) -> InnerResponse<Option<R>> {
216        self.show_ui_dyn(ui, Box::new(menu_contents))
217    }
218
219    fn show_ui_dyn<'c, R>(
220        self,
221        ui: &mut Ui,
222        menu_contents: Box<dyn FnOnce(&mut Ui) -> R + 'c>,
223    ) -> InnerResponse<Option<R>> {
224        let Self {
225            id_salt,
226            label,
227            selected_text,
228            width,
229            height,
230            icon,
231            wrap_mode,
232            close_behavior,
233            popup_style,
234        } = self;
235
236        let button_id = ui.make_persistent_id(id_salt);
237
238        ui.horizontal(|ui| {
239            let mut ir = combo_box_dyn(
240                ui,
241                button_id,
242                selected_text,
243                menu_contents,
244                icon,
245                wrap_mode,
246                close_behavior,
247                popup_style,
248                (width, height),
249            );
250            if let Some(label) = label {
251                ir.response.widget_info(|| {
252                    WidgetInfo::labeled(WidgetType::ComboBox, ui.is_enabled(), label.text())
253                });
254                ir.response |= ui.label(label);
255            } else {
256                ir.response
257                    .widget_info(|| WidgetInfo::labeled(WidgetType::ComboBox, ui.is_enabled(), ""));
258            }
259            ir
260        })
261        .inner
262    }
263
264    /// Show a list of items with the given selected index.
265    ///
266    ///
267    /// ```
268    /// # #[derive(Debug, PartialEq)]
269    /// # enum Enum { First, Second, Third }
270    /// # let mut selected = Enum::First;
271    /// # egui::__run_test_ui(|ui| {
272    /// let alternatives = ["a", "b", "c", "d"];
273    /// let mut selected = 2;
274    /// egui::ComboBox::from_label("Select one!").show_index(
275    ///     ui,
276    ///     &mut selected,
277    ///     alternatives.len(),
278    ///     |i| alternatives[i]
279    /// );
280    /// # });
281    /// ```
282    pub fn show_index<Text: Into<WidgetText>>(
283        self,
284        ui: &mut Ui,
285        selected: &mut usize,
286        len: usize,
287        get: impl Fn(usize) -> Text,
288    ) -> Response {
289        let slf = self.selected_text(get(*selected));
290
291        let mut changed = false;
292
293        let mut response = slf
294            .show_ui(ui, |ui| {
295                for i in 0..len {
296                    if ui.selectable_label(i == *selected, get(i)).clicked() {
297                        *selected = i;
298                        changed = true;
299                    }
300                }
301            })
302            .response;
303
304        if changed {
305            response.mark_changed();
306        }
307        response
308    }
309
310    /// Check if the [`ComboBox`] with the given id has its popup menu currently opened.
311    pub fn is_open(ctx: &Context, id: Id) -> bool {
312        Popup::is_id_open(ctx, Self::widget_to_popup_id(id))
313    }
314
315    /// Convert a [`ComboBox`] id to the id used to store it's popup state.
316    fn widget_to_popup_id(widget_id: Id) -> Id {
317        widget_id.with("popup")
318    }
319}
320
321#[expect(clippy::too_many_arguments)]
322fn combo_box_dyn<'c, R>(
323    ui: &mut Ui,
324    button_id: Id,
325    selected_text: WidgetText,
326    menu_contents: Box<dyn FnOnce(&mut Ui) -> R + 'c>,
327    icon: Option<IconPainter>,
328    wrap_mode: Option<TextWrapMode>,
329    close_behavior: Option<PopupCloseBehavior>,
330    popup_style: StyleModifier,
331    (width, height): (Option<f32>, Option<f32>),
332) -> InnerResponse<Option<R>> {
333    let popup_id = ComboBox::widget_to_popup_id(button_id);
334
335    let is_popup_open = Popup::is_id_open(ui.ctx(), popup_id);
336
337    let wrap_mode = wrap_mode.unwrap_or_else(|| ui.wrap_mode());
338
339    let close_behavior = close_behavior.unwrap_or(PopupCloseBehavior::CloseOnClick);
340
341    let margin = ui.spacing().button_padding;
342    let button_response = button_frame(ui, button_id, is_popup_open, Sense::click(), |ui| {
343        let icon_spacing = ui.spacing().icon_spacing;
344        let icon_size = Vec2::splat(ui.spacing().icon_width);
345
346        // The combo box selected text will always have this minimum width.
347        // Note: the `ComboBox::width()` if set or `Spacing::combo_width` are considered as the
348        // minimum overall width, regardless of the wrap mode.
349        let minimum_width = width.unwrap_or_else(|| ui.spacing().combo_width) - 2.0 * margin.x;
350
351        // width against which to lay out the selected text
352        let wrap_width = if wrap_mode == TextWrapMode::Extend {
353            // Use all the width necessary to display the currently selected value's text.
354            f32::INFINITY
355        } else {
356            // Use the available width, currently selected value's text will be wrapped if exceeds this value.
357            ui.available_width() - icon_spacing - icon_size.x
358        };
359
360        let galley = selected_text.into_galley(ui, Some(wrap_mode), wrap_width, TextStyle::Button);
361
362        let actual_width = (galley.size().x + icon_spacing + icon_size.x).at_least(minimum_width);
363        let actual_height = galley.size().y.max(icon_size.y);
364
365        let (_, rect) = ui.allocate_space(Vec2::new(actual_width, actual_height));
366        let button_rect = ui.min_rect().expand2(ui.spacing().button_padding);
367        let response = ui.interact(button_rect, button_id, Sense::click());
368        // response.active |= is_popup_open;
369
370        if ui.is_rect_visible(rect) {
371            let icon_rect = Align2::RIGHT_CENTER.align_size_within_rect(icon_size, rect);
372            let visuals = if is_popup_open {
373                &ui.visuals().widgets.open
374            } else {
375                ui.style().interact(&response)
376            };
377
378            if let Some(icon) = icon {
379                icon(
380                    ui,
381                    icon_rect.expand(visuals.expansion),
382                    visuals,
383                    is_popup_open,
384                );
385            } else {
386                paint_default_icon(ui.painter(), icon_rect.expand(visuals.expansion), visuals);
387            }
388
389            let text_rect = Align2::LEFT_CENTER.align_size_within_rect(galley.size(), rect);
390            ui.painter()
391                .galley(text_rect.min, galley, visuals.text_color());
392        }
393    });
394
395    let height = height.unwrap_or_else(|| ui.spacing().combo_height);
396
397    let inner = Popup::menu(&button_response)
398        .id(popup_id)
399        .width(button_response.rect.width())
400        .close_behavior(close_behavior)
401        .style(popup_style)
402        .show(|ui| {
403            ui.set_min_width(ui.available_width());
404
405            ScrollArea::vertical()
406                .max_height(height)
407                .show(ui, |ui| {
408                    // Often the button is very narrow, which means this popup
409                    // is also very narrow. Having wrapping on would therefore
410                    // result in labels that wrap very early.
411                    // Instead, we turn it off by default so that the labels
412                    // expand the width of the menu.
413                    ui.style_mut().wrap_mode = Some(TextWrapMode::Extend);
414                    menu_contents(ui)
415                })
416                .inner
417        })
418        .map(|r| r.inner);
419
420    InnerResponse {
421        inner,
422        response: button_response,
423    }
424}
425
426fn button_frame(
427    ui: &mut Ui,
428    id: Id,
429    is_popup_open: bool,
430    sense: Sense,
431    add_contents: impl FnOnce(&mut Ui),
432) -> Response {
433    let where_to_put_background = ui.painter().add(Shape::Noop);
434
435    let margin = ui.spacing().button_padding;
436    let interact_size = ui.spacing().interact_size;
437
438    let mut outer_rect = ui.available_rect_before_wrap();
439    outer_rect.set_height(outer_rect.height().at_least(interact_size.y));
440
441    let inner_rect = outer_rect.shrink2(margin);
442    let mut content_ui = ui.new_child(UiBuilder::new().max_rect(inner_rect));
443    add_contents(&mut content_ui);
444
445    let mut outer_rect = content_ui.min_rect().expand2(margin);
446    outer_rect.set_height(outer_rect.height().at_least(interact_size.y));
447
448    let response = ui.interact(outer_rect, id, sense);
449
450    if ui.is_rect_visible(outer_rect) {
451        let visuals = if is_popup_open {
452            &ui.visuals().widgets.open
453        } else {
454            ui.style().interact(&response)
455        };
456
457        ui.painter().set(
458            where_to_put_background,
459            epaint::RectShape::new(
460                outer_rect.expand(visuals.expansion),
461                visuals.corner_radius,
462                visuals.weak_bg_fill,
463                visuals.bg_stroke,
464                epaint::StrokeKind::Inside,
465            ),
466        );
467    }
468
469    ui.advance_cursor_after_rect(outer_rect);
470
471    response
472}
473
474fn paint_default_icon(painter: &Painter, rect: Rect, visuals: &WidgetVisuals) {
475    let rect = Rect::from_center_size(
476        rect.center(),
477        vec2(rect.width() * 0.7, rect.height() * 0.45),
478    );
479
480    // Downward pointing triangle
481    // Previously, we would show an up arrow when we expected the popup to open upwards
482    // (due to lack of space below the button), but this could look weird in edge cases, so this
483    // feature was removed. (See https://github.com/emilk/egui/pull/5713#issuecomment-2654420245)
484    painter.add(Shape::convex_polygon(
485        vec![rect.left_top(), rect.right_top(), rect.center_bottom()],
486        visuals.fg_stroke.color,
487        Stroke::NONE,
488    ));
489}