//! The app's side: events from the platform menu in, menu bars out. use std::borrow::Cow; use std::collections::HashSet; use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use craft_keymap::{Chord, CommandRef, Key, Mods}; use crate::layout::{Clash, Layout}; use crate::model::{Builtin, Item, ItemKind, MenuBar, Node}; /// What the native menu reports. #[derive(Clone, Debug, PartialEq)] pub enum Event { /// An item was chosen with the mouse (or the keyboard inside an open menu), or by a key /// equivalent the app's key handling doesn't know ([`crate::Item::layout_shortcut`]): the /// item's command. Click(CommandRef), /// A key equivalent was pressed: the shortcut, to be handled as the key press it was. Key(Chord), /// An item whose shortcut a text field handles itself (Edit › Copy, Undo) was clicked while a /// text field has the keys: the shortcut, to be handled as a press and release of it. Tap(Chord), /// A click the app's [`NativeMenu::on_command`] hook ran; [`NativeMenu::take_clicks`] leaves it /// out. Handled(CommandRef), } /// How ⌘C, ⌘X and ⌘V reach egui when the native menu takes them as key equivalents (an Edit /// menu with Copy, Cut and Paste items). #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub enum ClipboardKeys { /// As egui-winit makes them without a native menu: ⌘C is [`egui::Event::Copy`], ⌘X /// [`egui::Event::Cut`], and ⌘V a [`egui::ViewportCommand::RequestPaste`], which eframe answers /// with an [`egui::Event::Paste`] of the clipboard's text in the next frame. Text fields copy, /// cut and paste. #[default] Egui, /// Key presses like any other key equivalent, for an app that runs its clipboard commands /// from the keys itself. Raw, } /// What may run from the menus this frame, set by the app. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct Gate { /// A modal dialog is open. pub modal: bool, /// The shortcut editor is recording a chord. pub recording_shortcut: bool, /// A text field has the keys. pub text_editing: bool, } impl Gate { /// Whether `item` may run now: while a modal dialog is open or a shortcut is being recorded, /// only the built-in items (Hide, Hide Others, Minimize, Quit) do. The built-in Quit stays /// because it asks the window to close, and the app's close guard knows about its dialogs; an /// app's own Quit item ([`crate::ItemRole::Quit`]) is greyed with its other commands. A text field having the keys doesn't stop a click: menu commands run while /// typing, as in a Mac app, and the keys a field keeps are handled before the menus see them. pub fn allows(&self, item: &Item) -> bool { self.allows_command(&item.command) } /// [`Gate::allows`] for an item that runs `command`. pub fn allows_command(&self, command: &CommandRef) -> bool { !(self.modal || self.recording_shortcut) || Builtin::of(command).is_some() } /// `bar` with every item the gate forbids disabled, so the menus show them greyed, but the /// items whose shortcut a text field handles itself (Undo, Copy, Select All, …). pub(crate) fn grey<'a>(&self, bar: &'a MenuBar) -> Cow<'a, MenuBar> { fn walk(nodes: &mut [Node], gate: &Gate) { for n in nodes { match n { // The field's own keys stay enabled: AppKit doesn't send a disabled item's key // equivalent on, so greyed Copy or Undo would leave ⌘C and ⌘Z dead in a // dialog's text fields. Their clicks are still dropped (`take_clicks`). Node::Item(it) if !gate.allows(it) && !it.shortcut.as_ref().is_some_and(text_editing_key) => it.enabled = false, Node::Submenu { children, .. } => walk(children, gate), _ => {} } } } if !(self.modal || self.recording_shortcut) { return Cow::Borrowed(bar); } let mut bar = bar.clone(); for m in &mut bar.menus { walk(&mut m.children, self); } Cow::Owned(bar) } } /// An app's [`NativeMenu::on_command`] hook: `true` when it ran the command. pub type CommandHook = Box bool + Send + Sync>; /// What a backend's menu event handler needs from the driver when an item is chosen: the /// current [`Gate`] and the app's [`NativeMenu::on_command`] hook. The platform calls the handler /// between frames, from the event that chose the item, so this is shared with the driver rather /// than borrowed from it. [`NativeMenu::new`] hands it to the backend ([`Backend::attach`]). #[derive(Clone, Default)] pub struct Dispatch(Arc>); type SharedHook = Arc bool + Send + Sync>; #[derive(Default)] struct Shared { gate: Gate, hook: Option, } impl Dispatch { /// The event for an item with `command`, its `shortcut` and [`Item::layout_shortcut`], /// chosen with the modifiers `held` for a key-down (⌘, ⌃, ⌥, ⇧ as AppKit reports them) or /// `None` for a mouse click, under the current gate. A click the gate allows on an app command /// (not a [`Builtin`]) also goes to the app's [`NativeMenu::on_command`] hook, before this /// returns; when the hook ran it, the event is [`Event::Handled`]. pub fn chosen(&self, command: &CommandRef, shortcut: Option<&Chord>, layout_shortcut: bool, held: Option) -> Event { let (gate, hook) = { let shared = self.lock(); (shared.gate, shared.hook.clone()) }; let event = chosen_event(command, shortcut, layout_shortcut, held, gate); if let (Event::Click(c), Some(hook)) = (&event, hook) && gate.allows_command(c) && Builtin::of(c).is_none() && hook(c) { return Event::Handled(c.clone()); } event } fn lock(&self) -> MutexGuard<'_, Shared> { self.0.lock().unwrap_or_else(PoisonError::into_inner) } } /// A platform's native menu bar. pub trait Backend { /// Bring the menu in step with `bar`: update labels, enabled and checked in place, or /// rebuild when its structure changed ([`crate::structure_key`], [`crate::window_key`]). fn sync(&mut self, bar: &MenuBar); /// Events since the last call. Platform items (Hide, Services, Zoom, …) are handled by the /// backend and not reported. fn drain(&mut self) -> Vec; /// Whether one of the native menus is open. fn tracking(&self) -> bool { false } /// Close the open native menu, if there is one. fn cancel_tracking(&mut self) {} /// Keep the driver's [`Dispatch`]: the backend's menu event handler turns every chosen item /// into an [`Event`] through [`Dispatch::chosen`]. [`NativeMenu::new`] calls it once. fn attach(&mut self, dispatch: Dispatch); } /// The native menu bar, while the app uses one (its in-window menus are hidden then). pub struct NativeMenu { backend: Box, /// The state the menus were last built from. state: Option, clicks: Vec, /// An event arrived (AppKit may have toggled a check item itself): re-sync. dirty: bool, clashes: Vec, clipboard: ClipboardKeys, /// ⌘V arrived: [`NativeMenu::take_clicks`] asks eframe for the paste. paste: bool, /// Whether a click may be kept from egui as the one closing an open menu (see /// [`NativeMenu::raw_input`]). armed: bool, gate: Gate, dispatch: Dispatch, /// The menus last laid out, before the gate greyed anything, and the gate they were last /// synced with: a gate change re-syncs them without laying them out again. bar: Option, synced_gate: Option, /// The commands whose items were check items in a layout so far: they stay check items, so /// that `checked` going from `Some` to `None` doesn't rebuild the menus. checkable: HashSet, } impl NativeMenu { pub fn new(mut backend: Box) -> NativeMenu { let dispatch = Dispatch::default(); backend.attach(dispatch.clone()); NativeMenu { backend, state: None, clicks: Vec::new(), dirty: true, clashes: Vec::new(), clipboard: ClipboardKeys::default(), paste: false, armed: true, gate: Gate::default(), dispatch, bar: None, synced_gate: None, checkable: HashSet::new(), } } pub fn clipboard_keys(mut self, keys: ClipboardKeys) -> NativeMenu { self.clipboard = keys; self } /// What may run from the menus. Call it every frame, before [`NativeMenu::take_clicks`]; it /// also holds for the menu events that arrive until the next call. /// /// - While [`Gate::modal`] or [`Gate::recording_shortcut`] is on, the app's items are greyed /// (updated in place at the next [`NativeMenu::sync_with`]) and clicks on them are dropped, /// also a click that arrived before the gate closed and is still waiting for /// [`NativeMenu::take_clicks`]. The built-in items (Hide, Hide Others, Minimize, Quit) stay. /// A greyed item's key equivalent goes to the window, so the app's key handling sees it. /// - While [`Gate::recording_shortcut`] is on, every key equivalent reaches egui as the plain /// key press that was made (⌘Q, ⌘H and ⌘C included), for the shortcut recorder. /// - While [`Gate::text_editing`] is on (in egui, `ctx.wants_keyboard_input()`), a key /// equivalent runs its item as an [`Event::Click`], as a Mac app's menu commands run while /// typing, except the keys the field handles itself: ⌘C, ⌘X and ⌘V (following /// [`ClipboardKeys`]) and [`craft_keymap::text_editing_chords`] (⌘A, ⌘Z, ⇧⌘Z, ⌘←, …) stay /// key presses. pub fn set_gate(&mut self, gate: Gate) { self.gate = gate; self.dispatch.lock().gate = gate; } /// Run `hook` with each command clicked in the menus, from the menu event handler, as the /// click arrives: on macOS on the main thread, between frames, also while egui is idle. Only /// app commands the current gate ([`NativeMenu::set_gate`]) allows reach it, and key /// equivalents reported as key presses don't. It must return quickly; it is for waking the /// app's own loop or a worker. /// /// The hook returns `true` when it ran the command: [`NativeMenu::take_clicks`] then leaves /// it out. A command it returned `false` for comes back from `take_clicks`, after the gate as /// it is then. pub fn on_command(&mut self, hook: CommandHook) { self.dispatch.lock().hook = Some(Arc::from(hook)); } /// Before egui sees this frame's input: key equivalents become the key presses they were, /// and clicks wait for [`NativeMenu::take_clicks`]. /// /// A click or Escape in the window closes an open native menu. AppKit can deliver it to the /// window while the menu is still open (asynchronous menu presentation), so while the backend /// reports one open, the click or Escape is taken out of the input: it closes the menu /// without starting a canvas gesture or reaching the active tool. Pointer moves stay. Only /// one such click is kept from egui until the backend reports no menu open again, so a /// backend that wrongly keeps reporting one open costs one click, not every click. /// /// AppKit takes only the key-down: winit still delivers the key-up (it forwards key-ups while /// ⌘ is held). So a key equivalent adds just its press, ahead of its key-up when that is /// already queued. Adding a made-up release as well sends two key-ups; in PhotoCraft, which /// reads a ⌘V release without a press as an image paste, that made ⌘V paste three times. /// ⌘C, ⌘X and ⌘V follow [`ClipboardKeys`]. pub fn raw_input(&mut self, raw: &mut egui::RawInput) { // The window's own input, before key equivalents are added to it. if let Some(kept) = dismiss_input(raw, || self.armed && self.backend.tracking()) { if kept { self.armed = false; } // Also without a menu reported open: an asynchronously presented menu can still be // on screen after it reports closing. self.backend.cancel_tracking(); } if !self.armed && !self.backend.tracking() { self.armed = true; } for e in self.backend.drain() { match e { Event::Key(chord) => self.add_key(raw, &chord, false), Event::Tap(chord) => self.add_key(raw, &chord, true), Event::Click(command) => self.clicks.push(command), Event::Handled(_) => {} } self.dirty = true; } } /// `tap`: a press and its release, for a click that stands for the key (no key-up follows). fn add_key(&mut self, raw: &mut egui::RawInput, chord: &Chord, tap: bool) { let pressed_key = chord.key.to_egui(); let clipboard = self.clipboard == ClipboardKeys::Egui && chord.mods == Mods::CMD && !self.gate.recording_shortcut; let event = match chord.key { Key::C if clipboard => egui::Event::Copy, Key::X if clipboard => egui::Event::Cut, Key::V if clipboard => { self.paste = true; return; } _ => key_event(chord, true), }; let at = raw .events .iter() .position(|e| matches!(e, egui::Event::Key { key, pressed: false, .. } if *key == pressed_key)) .unwrap_or(raw.events.len()); let press = matches!(event, egui::Event::Key { .. }); raw.events.insert(at, event); if tap && press { raw.events.insert(at + 1, key_event(chord, false)); } } /// The commands clicked since the last call that the gate ([`NativeMenu::set_gate`]) allows /// now, for the app to run like in-window menu clicks; the others are dropped. /// [`Builtin::Minimize`] (minimizes the window) and [`Builtin::Quit`] (asks the window to /// close, see [`craft_quit::on_menu_event`]) are run here and left out. A ⌘V from the menu /// ([`ClipboardKeys::Egui`]) is asked of eframe here too. pub fn take_clicks(&mut self, ctx: &egui::Context) -> Vec { if std::mem::take(&mut self.paste) { ctx.send_viewport_cmd(egui::ViewportCommand::RequestPaste); } let mut out = Vec::new(); for command in std::mem::take(&mut self.clicks) { if !self.gate.allows_command(&command) { continue; } match Builtin::of(&command) { Some(Builtin::Minimize) => ctx.send_viewport_cmd(egui::ViewportCommand::Minimized(true)), Some(Builtin::Quit) => { craft_quit::on_menu_event(ctx, Builtin::Quit.id()); } _ => out.push(command), } } out } /// Bring the native menu up to date. `state` is a hash of what the menus show (see /// [`had_input`]); `build` lays them out ([`crate::mac_layout`]) and runs only when `state` /// changed or a menu event arrived since the last sync, since building the rows usually walks /// every command's enabled state. A menu event re-syncs because AppKit flips a check or radio /// item's state itself when it is chosen: the sync sets it back to the app's state. A gate /// change ([`NativeMenu::set_gate`]) re-syncs the menus last laid out, greyed or not, without /// calling `build`. /// /// `state` must cover everything the menus show. A change that comes without input, such as /// a load or save finishing on a worker or a timer, leaves the menus stale until the next /// input or menu event unless it is in the hash. An app that can't keep the hash complete /// uses [`NativeMenu::sync`] instead. /// /// Returns the layout's clashes when they differ from the last ones returned, for the app to /// log; otherwise nothing. pub fn sync_with(&mut self, state: u64, build: impl FnOnce() -> Layout) -> Vec { let relayout = self.state != Some(state) || self.dirty; if !relayout && self.synced_gate == Some(self.gate) { return Vec::new(); } let mut clashes = Vec::new(); if relayout { let mut layout = build(); self.keep_kinds(&mut layout.bar); clashes = self.keep(layout); self.state = Some(state); } self.push(); clashes } /// [`NativeMenu::sync_with`] without a state hash: the app lays the menus out every frame /// and they are synced when the layout differs from the last one (or a menu event or gate /// change calls for it), so they never go stale. It costs a layout per frame. pub fn sync(&mut self, mut layout: Layout) -> Vec { self.keep_kinds(&mut layout.bar); if !self.dirty && self.bar.as_ref() == Some(&layout.bar) && self.clashes == layout.clashes && self.synced_gate == Some(self.gate) { return Vec::new(); } let clashes = self.keep(layout); // A later `sync_with` lays the menus out again. self.state = None; self.push(); clashes } /// An item that was a check item once stays one, unchecked: switching its kind would change /// [`crate::structure_key`] and rebuild the menus. fn keep_kinds(&mut self, bar: &mut MenuBar) { let checkable = &mut self.checkable; bar.for_each_item_mut(|it| match it.kind { ItemKind::Check(_) => { checkable.insert(it.command.key()); } ItemKind::Plain if checkable.contains(&it.command.key()) => it.kind = ItemKind::Check(false), _ => {} }); } /// Keep `layout` as the menus to show; its clashes when they differ from the last ones. fn keep(&mut self, layout: Layout) -> Vec { self.dirty = false; self.bar = Some(layout.bar); if layout.clashes == self.clashes { return Vec::new(); } self.clashes = layout.clashes.clone(); layout.clashes } /// Sync the backend with the kept menus, greyed by the gate. fn push(&mut self) { if let Some(bar) = &self.bar { self.backend.sync(&self.gate.grey(bar)); } self.synced_gate = Some(self.gate); } } /// `Some` when `raw` has a press or Escape that closes an open menu: `Some(true)` when, with /// `tracking` (a menu is open), those events were removed, since they belong to the menu. pub(crate) fn dismiss_input(raw: &mut egui::RawInput, tracking: impl FnOnce() -> bool) -> Option { if !raw .events .iter() .any(|e| matches!(e, egui::Event::PointerButton { pressed: true, .. } | egui::Event::Key { key: egui::Key::Escape, pressed: true, .. })) { return None; } let kept = tracking(); if kept { raw.events.retain(|e| !matches!(e, egui::Event::PointerButton { .. } | egui::Event::Key { key: egui::Key::Escape, .. })); } Some(kept) } /// What a backend reports for an item chosen with `command`, `chord` (its shortcut) and /// `layout_shortcut` ([`crate::Item::layout_shortcut`]) under `gate`. `held` holds the modifiers /// held when a key-down chose it, `None` for a mouse click. /// /// A key-down is the item's key equivalent, reported as the key press, unless it was ↩ or Space /// inside the open menu: the item's shortcut is not a key equivalent at all ([`native_ok`]), or /// neither ⌘ nor ⌃ is held. The key is the item's (AppKit matched on it); the modifiers are the /// ones held, since AppKit may match ⌘R to a ⇧⌘R item. Minimize, craft-quit's Quit and shortcuts /// the layout assigned are run by the driver or the app's click handling, not by its key /// handling, so they stay clicks. While text editing, the app's key handling leaves shortcuts to /// the field, so a key equivalent is a click too, except the field's own editing keys /// ([`text_editing_key`]); a mouse click on one of those items (Edit › Copy, Undo) is a tap of /// its shortcut ([`Event::Tap`]), so it acts on the field rather than the document. While recording a shortcut every key equivalent is a key press, for the /// recorder. pub(crate) fn chosen_event(command: &CommandRef, chord: Option<&Chord>, layout_shortcut: bool, held: Option, gate: Gate) -> Event { let recording = gate.recording_shortcut; let runs_as_click = !recording && (layout_shortcut || matches!(Builtin::of(command), Some(Builtin::Minimize | Builtin::Quit))); let Some(held) = held else { return match chord { Some(c) if !recording && gate.text_editing && text_editing_key(c) => Event::Tap(*c), _ => Event::Click(command.clone()), }; }; let pressed = chord .filter(|c| !runs_as_click && native_ok(c) && (held.cmd || held.ctrl)) .map(|c| Chord::new(held, c.key)) .filter(|c| recording || !gate.text_editing || text_editing_key(c)); match pressed { Some(chord) => Event::Key(chord), None => Event::Click(command.clone()), } } /// A chord a text field handles itself: the clipboard keys and craft-keymap's text-editing /// chords (undo, redo, select all, moving by word and line). fn text_editing_key(c: &Chord) -> bool { const CLIPBOARD: [Chord; 3] = [Chord::new(Mods::CMD, Key::C), Chord::new(Mods::CMD, Key::X), Chord::new(Mods::CMD, Key::V)]; CLIPBOARD.contains(c) || craft_keymap::text_editing_chords(craft_keymap::Platform::Mac).contains(c) } /// May the native menu make this a key equivalent? Only with ⌘ or ⌃. Other shortcuts (a bare /// letter, ⇧ or ⌥ alone, a bare function key) are tool keys: as key equivalents AppKit would take /// a `b` typed into a text field, and the app's key handling may bind them per tool or context. /// They are shown but not made key equivalents. pub(crate) fn native_ok(c: &Chord) -> bool { c.has_command() } /// The key press egui would have received for `chord` on macOS: `cmd` is ⌘, `ctrl` the Control /// key. pub(crate) fn key_event(chord: &Chord, pressed: bool) -> egui::Event { let m = chord.mods; let key = chord.key.to_egui(); let modifiers = egui::Modifiers { alt: m.alt, ctrl: m.ctrl, shift: m.shift, mac_cmd: m.cmd, command: m.cmd }; egui::Event::Key { key, physical_key: Some(key), pressed, repeat: false, modifiers } } /// A key press or click this frame. It may have changed state an app's menu hash doesn't list, /// so apps fold it into the `state` passed to [`NativeMenu::sync_with`], for example as /// `had_input(ctx).then_some(ctx.cumulative_frame_nr())`. pub fn had_input(ctx: &egui::Context) -> bool { ctx.input(|i| i.events.iter().any(|e| matches!(e, egui::Event::Key { pressed: true, .. } | egui::Event::PointerButton { pressed: false, .. }))) }