egui/containers/
menu.rs

1//! Popup menus, context menus and menu bars.
2//!
3//! Show menus via
4//! - [`Popup::menu`] and [`Popup::context_menu`]
5//! - [`Ui::menu_button`], [`MenuButton`] and [`SubMenuButton`]
6//! - [`MenuBar`]
7//! - [`Response::context_menu`]
8//!
9//! See [`MenuBar`] for an example.
10
11use crate::style::StyleModifier;
12use crate::{
13    Button, Color32, Context, Frame, Id, InnerResponse, IntoAtoms, Layout, Popup,
14    PopupCloseBehavior, Response, Style, Ui, UiBuilder, UiKind, UiStack, UiStackInfo, Widget as _,
15};
16use emath::{Align, RectAlign, Vec2, vec2};
17use epaint::Stroke;
18
19/// Apply a menu style to the [`Style`].
20///
21/// Mainly removes the background stroke and the inactive background fill.
22pub fn menu_style(style: &mut Style) {
23    style.spacing.button_padding = vec2(2.0, 0.0);
24    style.visuals.widgets.active.bg_stroke = Stroke::NONE;
25    style.visuals.widgets.open.bg_stroke = Stroke::NONE;
26    style.visuals.widgets.hovered.bg_stroke = Stroke::NONE;
27    style.visuals.widgets.inactive.weak_bg_fill = Color32::TRANSPARENT;
28    style.visuals.widgets.inactive.bg_stroke = Stroke::NONE;
29}
30
31/// Find the root [`UiStack`] of the menu.
32pub fn find_menu_root(ui: &Ui) -> &UiStack {
33    ui.stack()
34        .iter()
35        .find(|stack| {
36            stack.is_root_ui()
37                || [Some(UiKind::Popup), Some(UiKind::Menu)].contains(&stack.kind())
38                || stack.info.tags.contains(MenuConfig::MENU_CONFIG_TAG)
39        })
40        .expect("We should always find the root")
41}
42
43/// Is this Ui part of a menu?
44///
45/// Returns `false` if this is a menu bar.
46/// Should be used to determine if we should show a menu button or submenu button.
47pub fn is_in_menu(ui: &Ui) -> bool {
48    for stack in ui.stack().iter() {
49        if let Some(config) = stack
50            .info
51            .tags
52            .get_downcast::<MenuConfig>(MenuConfig::MENU_CONFIG_TAG)
53        {
54            return !config.bar;
55        }
56        if [Some(UiKind::Popup), Some(UiKind::Menu)].contains(&stack.kind()) {
57            return true;
58        }
59    }
60    false
61}
62
63/// Configuration and style for menus.
64#[derive(Clone, Debug)]
65pub struct MenuConfig {
66    /// Is this a menu bar?
67    bar: bool,
68
69    /// If the user clicks, should we close the menu?
70    pub close_behavior: PopupCloseBehavior,
71
72    /// Override the menu style.
73    ///
74    /// Default is [`menu_style`].
75    pub style: StyleModifier,
76}
77
78impl Default for MenuConfig {
79    fn default() -> Self {
80        Self {
81            close_behavior: PopupCloseBehavior::default(),
82            bar: false,
83            style: menu_style.into(),
84        }
85    }
86}
87
88impl MenuConfig {
89    /// The tag used to store the menu config in the [`UiStack`].
90    pub const MENU_CONFIG_TAG: &'static str = "egui_menu_config";
91
92    pub fn new() -> Self {
93        Self::default()
94    }
95
96    /// If the user clicks, should we close the menu?
97    #[inline]
98    pub fn close_behavior(mut self, close_behavior: PopupCloseBehavior) -> Self {
99        self.close_behavior = close_behavior;
100        self
101    }
102
103    /// Override the menu style.
104    ///
105    /// Default is [`menu_style`].
106    #[inline]
107    pub fn style(mut self, style: impl Into<StyleModifier>) -> Self {
108        self.style = style.into();
109        self
110    }
111
112    fn from_stack(stack: &UiStack) -> Self {
113        stack
114            .info
115            .tags
116            .get_downcast(Self::MENU_CONFIG_TAG)
117            .cloned()
118            .unwrap_or_default()
119    }
120
121    /// Find the config for the current menu.
122    ///
123    /// Returns the default config if no config is found.
124    pub fn find(ui: &Ui) -> Self {
125        find_menu_root(ui)
126            .info
127            .tags
128            .get_downcast(Self::MENU_CONFIG_TAG)
129            .cloned()
130            .unwrap_or_default()
131    }
132}
133
134/// Holds the state of the menu.
135#[derive(Clone)]
136pub struct MenuState {
137    /// The currently open sub menu in this menu.
138    pub open_item: Option<Id>,
139    last_visible_pass: u64,
140}
141
142impl MenuState {
143    pub const ID: &'static str = "menu_state";
144
145    /// Find the root of the menu and get the state
146    pub fn from_ui<R>(ui: &Ui, f: impl FnOnce(&mut Self, &UiStack) -> R) -> R {
147        let stack = find_menu_root(ui);
148        Self::from_id(ui.ctx(), stack.id, |state| f(state, stack))
149    }
150
151    /// Get the state via the menus root [`Ui`] id
152    pub fn from_id<R>(ctx: &Context, id: Id, f: impl FnOnce(&mut Self) -> R) -> R {
153        let pass_nr = ctx.cumulative_pass_nr();
154        ctx.data_mut(|data| {
155            let state = data.get_temp_mut_or_insert_with(id.with(Self::ID), || Self {
156                open_item: None,
157                last_visible_pass: pass_nr,
158            });
159            // If the menu was closed for at least a frame, reset the open item
160            if state.last_visible_pass + 1 < pass_nr {
161                state.open_item = None;
162            }
163            state.last_visible_pass = pass_nr;
164            f(state)
165        })
166    }
167
168    /// Is the menu with this id the deepest sub menu? (-> no child sub menu is open)
169    pub fn is_deepest_sub_menu(ctx: &Context, id: Id) -> bool {
170        Self::from_id(ctx, id, |state| state.open_item.is_none())
171    }
172}
173
174/// Horizontal menu bar where you can add [`MenuButton`]s.
175///
176/// The menu bar goes well in a [`crate::TopBottomPanel::top`],
177/// but can also be placed in a [`crate::Window`].
178/// In the latter case you may want to wrap it in [`Frame`].
179///
180/// ### Example:
181/// ```
182/// # egui::__run_test_ui(|ui| {
183/// egui::MenuBar::new().ui(ui, |ui| {
184///     ui.menu_button("File", |ui| {
185///         if ui.button("Quit").clicked() {
186///             ui.ctx().send_viewport_cmd(egui::ViewportCommand::Close);
187///         }
188///     });
189/// });
190/// # });
191/// ```
192#[derive(Clone, Debug)]
193pub struct MenuBar {
194    config: MenuConfig,
195    style: StyleModifier,
196}
197
198#[deprecated = "Renamed to `egui::MenuBar`"]
199pub type Bar = MenuBar;
200
201impl Default for MenuBar {
202    fn default() -> Self {
203        Self {
204            config: MenuConfig::default(),
205            style: menu_style.into(),
206        }
207    }
208}
209
210impl MenuBar {
211    pub fn new() -> Self {
212        Self::default()
213    }
214
215    /// Set the style for buttons in the menu bar.
216    ///
217    /// Doesn't affect the style of submenus, use [`MenuConfig::style`] for that.
218    /// Default is [`menu_style`].
219    #[inline]
220    pub fn style(mut self, style: impl Into<StyleModifier>) -> Self {
221        self.style = style.into();
222        self
223    }
224
225    /// Set the config for submenus.
226    ///
227    /// Note: The config will only be passed when using [`MenuButton`], not via [`Popup::menu`].
228    #[inline]
229    pub fn config(mut self, config: MenuConfig) -> Self {
230        self.config = config;
231        self
232    }
233
234    /// Show the menu bar.
235    #[inline]
236    pub fn ui<R>(self, ui: &mut Ui, content: impl FnOnce(&mut Ui) -> R) -> InnerResponse<R> {
237        let Self { mut config, style } = self;
238        config.bar = true;
239        // TODO(lucasmerlin): It'd be nice if we had a ui.horizontal_builder or something
240        // So we don't need the nested scope here
241        ui.horizontal(|ui| {
242            ui.scope_builder(
243                UiBuilder::new()
244                    .layout(Layout::left_to_right(Align::Center))
245                    .ui_stack_info(
246                        UiStackInfo::new(UiKind::Menu)
247                            .with_tag_value(MenuConfig::MENU_CONFIG_TAG, config),
248                    ),
249                |ui| {
250                    style.apply(ui.style_mut());
251
252                    // Take full width and fixed height:
253                    let height = ui.spacing().interact_size.y;
254                    ui.set_min_size(vec2(ui.available_width(), height));
255
256                    content(ui)
257                },
258            )
259            .inner
260        })
261    }
262}
263
264/// A thin wrapper around a [`Button`] that shows a [`Popup::menu`] when clicked.
265///
266/// The only thing this does is search for the current menu config (if set via [`MenuBar`]).
267/// If your menu button is not in a [`MenuBar`] it's fine to use [`Ui::button`] and [`Popup::menu`]
268/// directly.
269pub struct MenuButton<'a> {
270    pub button: Button<'a>,
271    pub config: Option<MenuConfig>,
272}
273
274impl<'a> MenuButton<'a> {
275    pub fn new(atoms: impl IntoAtoms<'a>) -> Self {
276        Self::from_button(Button::new(atoms.into_atoms()))
277    }
278
279    /// Set the config for the menu.
280    #[inline]
281    pub fn config(mut self, config: MenuConfig) -> Self {
282        self.config = Some(config);
283        self
284    }
285
286    /// Create a new menu button from a [`Button`].
287    #[inline]
288    pub fn from_button(button: Button<'a>) -> Self {
289        Self {
290            button,
291            config: None,
292        }
293    }
294
295    /// Show the menu button.
296    pub fn ui<R>(
297        self,
298        ui: &mut Ui,
299        content: impl FnOnce(&mut Ui) -> R,
300    ) -> (Response, Option<InnerResponse<R>>) {
301        let response = self.button.ui(ui);
302        let mut config = self.config.unwrap_or_else(|| MenuConfig::find(ui));
303        config.bar = false;
304        let inner = Popup::menu(&response)
305            .close_behavior(config.close_behavior)
306            .style(config.style.clone())
307            .info(
308                UiStackInfo::new(UiKind::Menu).with_tag_value(MenuConfig::MENU_CONFIG_TAG, config),
309            )
310            .show(content);
311        (response, inner)
312    }
313}
314
315/// A submenu button that shows a [`SubMenu`] if a [`Button`] is hovered.
316pub struct SubMenuButton<'a> {
317    pub button: Button<'a>,
318    pub sub_menu: SubMenu,
319}
320
321impl<'a> SubMenuButton<'a> {
322    /// The default right arrow symbol: `"⏵"`
323    pub const RIGHT_ARROW: &'static str = "⏵";
324
325    pub fn new(atoms: impl IntoAtoms<'a>) -> Self {
326        Self::from_button(Button::new(atoms.into_atoms()).right_text("⏵"))
327    }
328
329    /// Create a new submenu button from a [`Button`].
330    ///
331    /// Use [`Button::right_text`] and [`SubMenuButton::RIGHT_ARROW`] to add the default right
332    /// arrow symbol.
333    pub fn from_button(button: Button<'a>) -> Self {
334        Self {
335            button,
336            sub_menu: SubMenu::default(),
337        }
338    }
339
340    /// Set the config for the submenu.
341    ///
342    /// The close behavior will not affect the current button, but the buttons in the submenu.
343    #[inline]
344    pub fn config(mut self, config: MenuConfig) -> Self {
345        self.sub_menu.config = Some(config);
346        self
347    }
348
349    /// Show the submenu button.
350    pub fn ui<R>(
351        self,
352        ui: &mut Ui,
353        content: impl FnOnce(&mut Ui) -> R,
354    ) -> (Response, Option<InnerResponse<R>>) {
355        let my_id = ui.next_auto_id();
356        let open = MenuState::from_ui(ui, |state, _| {
357            state.open_item == Some(SubMenu::id_from_widget_id(my_id))
358        });
359        let inactive = ui.style().visuals.widgets.inactive;
360        // TODO(lucasmerlin) add `open` function to `Button`
361        if open {
362            ui.style_mut().visuals.widgets.inactive = ui.style().visuals.widgets.open;
363        }
364        let response = self.button.ui(ui);
365        ui.style_mut().visuals.widgets.inactive = inactive;
366
367        let popup_response = self.sub_menu.show(ui, &response, content);
368
369        (response, popup_response)
370    }
371}
372
373/// Show a submenu in a menu.
374///
375/// Useful if you want to make custom menu buttons.
376/// Usually, just use [`MenuButton`] or [`SubMenuButton`] instead.
377#[derive(Clone, Debug, Default)]
378pub struct SubMenu {
379    config: Option<MenuConfig>,
380}
381
382impl SubMenu {
383    pub fn new() -> Self {
384        Self::default()
385    }
386
387    /// Set the config for the submenu.
388    ///
389    /// The close behavior will not affect the current button, but the buttons in the submenu.
390    #[inline]
391    pub fn config(mut self, config: MenuConfig) -> Self {
392        self.config = Some(config);
393        self
394    }
395
396    /// Get the id for the submenu from the widget/response id.
397    pub fn id_from_widget_id(widget_id: Id) -> Id {
398        widget_id.with("submenu")
399    }
400
401    /// Show the submenu.
402    pub fn show<R>(
403        self,
404        ui: &Ui,
405        button_response: &Response,
406        content: impl FnOnce(&mut Ui) -> R,
407    ) -> Option<InnerResponse<R>> {
408        let frame = Frame::menu(ui.style());
409
410        let id = Self::id_from_widget_id(button_response.id);
411
412        let (open_item, menu_id, parent_config) = MenuState::from_ui(ui, |state, stack| {
413            (state.open_item, stack.id, MenuConfig::from_stack(stack))
414        });
415
416        let mut menu_config = self.config.unwrap_or_else(|| parent_config.clone());
417        menu_config.bar = false;
418
419        let menu_root_response = ui
420            .ctx()
421            .read_response(menu_id)
422            // Since we are a child of that ui, this should always exist
423            .unwrap();
424
425        let hover_pos = ui.ctx().pointer_hover_pos();
426
427        // We don't care if the user is hovering over the border
428        let menu_rect = menu_root_response.rect - frame.total_margin();
429        let is_hovering_menu = hover_pos.is_some_and(|pos| {
430            ui.ctx().layer_id_at(pos) == Some(menu_root_response.layer_id)
431                && menu_rect.contains(pos)
432        });
433
434        let is_any_open = open_item.is_some();
435        let mut is_open = open_item == Some(id);
436        let mut set_open = None;
437
438        // We expand the button rect so there is no empty space where no menu is shown
439        // TODO(lucasmerlin): Instead, maybe make item_spacing.y 0.0?
440        let button_rect = button_response
441            .rect
442            .expand2(ui.style().spacing.item_spacing / 2.0);
443
444        // In theory some other widget could cover the button and this check would still pass
445        // But since we check if no other menu is open, nothing should be able to cover the button
446        let is_hovered = hover_pos.is_some_and(|pos| button_rect.contains(pos));
447
448        // The clicked handler is there for accessibility (keyboard navigation)
449        if (!is_any_open && is_hovered) || button_response.clicked() {
450            set_open = Some(true);
451            is_open = true;
452            // Ensure that all other sub menus are closed when we open the menu
453            MenuState::from_id(ui.ctx(), id, |state| {
454                state.open_item = None;
455            });
456        }
457
458        let gap = frame.total_margin().sum().x / 2.0 + 2.0;
459
460        let mut response = button_response.clone();
461        // Expand the button rect so that the button and the first item in the submenu are aligned
462        let expand = Vec2::new(0.0, frame.total_margin().sum().y / 2.0);
463        response.interact_rect = response.interact_rect.expand2(expand);
464
465        let popup_response = Popup::from_response(&response)
466            .id(id)
467            .open(is_open)
468            .align(RectAlign::RIGHT_START)
469            .layout(Layout::top_down_justified(Align::Min))
470            .gap(gap)
471            .style(menu_config.style.clone())
472            .frame(frame)
473            // The close behavior is handled by the menu (see below)
474            .close_behavior(PopupCloseBehavior::IgnoreClicks)
475            .info(
476                UiStackInfo::new(UiKind::Menu)
477                    .with_tag_value(MenuConfig::MENU_CONFIG_TAG, menu_config.clone()),
478            )
479            .show(|ui| {
480                // Ensure our layer stays on top when the button is clicked
481                if button_response.clicked() || button_response.is_pointer_button_down_on() {
482                    ui.ctx().move_to_top(ui.layer_id());
483                }
484                content(ui)
485            });
486
487        if let Some(popup_response) = &popup_response {
488            // If no child sub menu is open means we must be the deepest child sub menu.
489            let is_deepest_submenu = MenuState::is_deepest_sub_menu(ui.ctx(), id);
490
491            // If the user clicks and the cursor is not hovering over our menu rect, it's
492            // safe to assume they clicked outside the menu, so we close everything.
493            // If they were to hover some other parent submenu we wouldn't be open.
494            // Only edge case is the user hovering this submenu's button, so we also check
495            // if we clicked outside the parent menu (which we luckily have access to here).
496            let clicked_outside = is_deepest_submenu
497                && popup_response.response.clicked_elsewhere()
498                && menu_root_response.clicked_elsewhere();
499
500            // We never automatically close when a submenu button is clicked, (so menus work
501            // on touch devices)
502            // Luckily we will always be the deepest submenu when a submenu button is clicked,
503            // so the following check is enough.
504            let submenu_button_clicked = button_response.clicked();
505
506            let clicked_inside = is_deepest_submenu
507                && !submenu_button_clicked
508                && response.ctx.input(|i| i.pointer.any_click())
509                && hover_pos.is_some_and(|pos| popup_response.response.interact_rect.contains(pos));
510
511            let click_close = match menu_config.close_behavior {
512                PopupCloseBehavior::CloseOnClick => clicked_outside || clicked_inside,
513                PopupCloseBehavior::CloseOnClickOutside => clicked_outside,
514                PopupCloseBehavior::IgnoreClicks => false,
515            };
516
517            if click_close {
518                set_open = Some(false);
519                ui.close();
520            }
521
522            let is_moving_towards_rect = ui.input(|i| {
523                i.pointer
524                    .is_moving_towards_rect(&popup_response.response.rect)
525            });
526            if is_moving_towards_rect {
527                // We need to repaint while this is true, so we can detect when
528                // the pointer is no longer moving towards the rect
529                ui.ctx().request_repaint();
530            }
531            let hovering_other_menu_entry = is_open
532                && !is_hovered
533                && !popup_response.response.contains_pointer()
534                && !is_moving_towards_rect
535                && is_hovering_menu;
536
537            let close_called = popup_response.response.should_close();
538
539            // Close the parent ui to e.g. close the popup from where the submenu was opened
540            if close_called {
541                ui.close();
542            }
543
544            if hovering_other_menu_entry {
545                set_open = Some(false);
546            }
547
548            if ui.will_parent_close() {
549                ui.data_mut(|data| data.remove_by_type::<MenuState>());
550            }
551        }
552
553        if let Some(set_open) = set_open {
554            MenuState::from_id(ui.ctx(), menu_id, |state| {
555                state.open_item = set_open.then_some(id);
556            });
557        }
558
559        popup_response
560    }
561}
egui/containers/menu.rs

egui/containers/
menu.rs
