From 9dfdb4c26fdefddbbabfa5686d85ead6293ec3f6 Mon Sep 17 00:00:00 2001 From: aiongg Date: Thu, 12 Nov 2026 07:01:19 +0000 Subject: [PATCH] Runtime: a host declares its own egui canvas as the window's document canvas focus::host_canvas registers the app's own egui widget as a canvas stop through the stop registration a framework canvas uses, so a bare Tab toggles that window's panels, and the canvas takes keys as its KeyUse says while it has focus. --- crates/ui-contract/src/runtime/focus.rs | 11 +++++ .../src/testing/host_key_trials.rs | 43 ++++++++++++++++++- docs/craft-framework.md | 3 +- 3 files changed, 54 insertions(+), 3 deletions(-) diff --git a/crates/ui-contract/src/runtime/focus.rs b/crates/ui-contract/src/runtime/focus.rs index 383a30753..2786b9377 100644 --- a/crates/ui-contract/src/runtime/focus.rs +++ b/crates/ui-contract/src/runtime/focus.rs @@ -183,6 +183,17 @@ pub(crate) fn register_stop(ctx: &Context, stop: Stop) { }); } +/// Registers the app's own egui widget `id`, drawn in the running pass, as its window's document canvas: a focus stop +/// with `keys`, marked as the canvas (`KeyUse::chrome_key`). The window then shows a document, so with +/// `RootEnv::tab_toggles_chrome` a bare Tab with nothing focused toggles its panels, as with a framework canvas. Focus +/// reaches the canvas by Tab, F6 or `request`; while it has focus, its keys route as `keys` says (the arrows as +/// nudges, Escape as its `Intent::Cancel`). `keys` is `KeyUse::CANVAS`, or a variant such as +/// `KeyUse::CANVAS.with_keep(KeepKeys::Tab)` while the canvas edits text in place and Tab is its own. Call it each pass +/// the canvas shows. +pub fn host_canvas(ctx: &Context, id: Id, keys: KeyUse) { + register_stop(ctx, Stop::new(id, keys.with_chrome_key(true))); +} + /// How many stops the running pass has registered so far. pub(crate) fn stop_count(ctx: &Context) -> usize { with(ctx, |state| state.stops.len()) diff --git a/crates/ui-contract/src/testing/host_key_trials.rs b/crates/ui-contract/src/testing/host_key_trials.rs index 993b95391..c7eccba28 100644 --- a/crates/ui-contract/src/testing/host_key_trials.rs +++ b/crates/ui-contract/src/testing/host_key_trials.rs @@ -2,14 +2,16 @@ use crate::runtime::drag::{self, DragPreview}; use crate::runtime::egui::fixture; -use crate::runtime::focus::KeyUse; +use crate::runtime::env::RootEnv; +use crate::runtime::focus::{FocusTarget, KeepKeys, KeyUse, host_canvas, request}; +use crate::runtime::frame::{ChromeToggle, take_output}; use crate::runtime::keys::with_window_intents; use crate::testing::focus::{Stop, egui_focused, named_id, register_stop, widget}; use crate::testing::input::{key_press, key_reached}; use crate::testing::pointer::{self, moved, press, release}; use crate::testing::{Frames, trial}; use craft_behavior::{Input, Intent}; -use egui::{Event, Id, ImeEvent, Key, Modifiers, Pos2, Rect, Ui}; +use egui::{Event, Id, ImeEvent, Key, Modifiers, Pos2, Rect, Ui, ViewportId}; use std::cell::RefCell; use std::rc::Rc; use std::sync::Arc; @@ -173,3 +175,40 @@ fn copy_with_a_label_selection_copies_the_label() { frames.frame(vec![Event::Copy], &mut show); assert!(frames.copied().iter().any(|copied| !copied.is_empty() && TEXT.contains(copied.as_str())), "egui copied the selection"); } + +/// What a bare Tab did in a window whose host declares its canvas with `keys` (`None`: no canvas), with the canvas +/// focused or not: the chrome toggles it asked for, and whether it reached egui. +fn tab_with_canvas(keys: Option, focused: bool) -> (Vec<(ViewportId, ChromeToggle)>, bool) { + let canvas = named_id("host canvas"); + let (host, mut base) = host_window(); + let mut show = move |ui: &mut Ui| { + base(ui); + widget(ui, canvas); + if let Some(keys) = keys { + host_canvas(ui.ctx(), canvas, keys); + } + }; + let mut frames = Frames::new(); + frames.root(RootEnv { tab_toggles_chrome: true, ..RootEnv::default() }); + frames.frame(Vec::new(), &mut show); + if focused { + request(&frames.ctx, FocusTarget::Id(canvas)); + frames.frame(Vec::new(), &mut show); + } + take_output(&frames.ctx); + seen(&host); + press_key(&mut frames, &mut show, Key::Tab); + (take_output(&frames.ctx).chrome_toggles, seen(&host).0.contains(&Key::Tab)) +} + +#[trial] +fn a_host_canvas_marks_the_window_and_tab_toggles_its_panels() { + assert_eq!(tab_with_canvas(None, false), (Vec::new(), false), "no canvas: Tab moves focus"); + assert_eq!(tab_with_canvas(Some(KeyUse::CANVAS), false), (vec![(ViewportId::ROOT, ChromeToggle::Panels)], false), "nothing focused"); + assert_eq!(tab_with_canvas(Some(KeyUse::CANVAS), true), (vec![(ViewportId::ROOT, ChromeToggle::Panels)], false), "the canvas focused"); + assert_eq!( + tab_with_canvas(Some(KeyUse::CANVAS.with_keep(KeepKeys::Tab)), true), + (Vec::new(), true), + "a focused canvas that keeps Tab gets it from egui" + ); +} diff --git a/docs/craft-framework.md b/docs/craft-framework.md index 63f98cfc1..308a56c7e 100644 --- a/docs/craft-framework.md +++ b/docs/craft-framework.md @@ -142,13 +142,14 @@ An app with its own eframe `App` calls the hooks in `craft::ui::shell::embed`. ` | Each frame | `raw_input_hook` | `embed::before_input(ctx, \|output\| { ...; input })`: the closure receives the `FrameOutput` of the frame before (fired commands, announcements, chrome toggles) and returns the `FrameInput` for this frame (`RootEnv`, command states, the `Host`). | | Each frame | `logic`, after the app's own logic | `embed::logic(ctx, \|\| decision)`: the root window's close path. The closure runs only when the root window was asked to close, and returns `CloseDecision::Close` or `Hold`. | | Each pass | `ui`, before the app's UI | `embed::before_ui(ctx, frame)`: hands the runtime the native window on Windows, and fits the root window to its monitor once. Needs `ui-app`. | +| Each pass | `ui`, where the app draws its own document canvas | Optional: `ui::runtime::focus::host_canvas(ctx, id, KeyUse::CANVAS)` declares it as the window's canvas (Tab row below). | | Each pass | `ui`, last | Optional: `ui::runtime::keys::with_window_intents(ctx, rtl, \|intents\| ...)` reads the keys no component took (below). | `install` takes over these parts of the context for the whole window, not only for framework components: | What | Effect on the app's own egui code | | --- | --- | -| Tab | Bare Tab moves framework focus and never reaches egui, unless the focused framework stop keeps Tab or an app's own widget has the focus (below). With `RootEnv::tab_toggles_chrome`, Tab with nothing focused toggles the chrome and arrives in `FrameOutput::chrome_toggles`. | +| Tab | Bare Tab moves framework focus and never reaches egui, unless the focused framework stop keeps Tab or an app's own widget has the focus (below). With `RootEnv::tab_toggles_chrome`, Tab toggles the chrome in a window that shows a document canvas, with nothing focused or the canvas focused, and arrives in `FrameOutput::chrome_toggles`. The canvas is a framework canvas, or the app's own egui canvas declared each pass with `ui::runtime::focus::host_canvas`. | | F6 | F6 and Shift+F6 move between panes and never reach egui. | | Escape | Plain Escape (Alt and Shift may be held) goes to the focused framework stop and its scopes; with no framework stop focused, it goes to the window as `Intent::Cancel`. It reaches egui only while an app's own widget has the focus (below). | | F10, Alt+letter | Taken while a framework menu bar is registered: F10 focuses the bar, Alt+letter opens a menu (not on macOS). |