Route the first keystroke of an IME composition through the input method

When a cell wasn't in edit mode, `grid/keyboard.rs` consumed `Event::Text`
and seeded the in-cell editor with that keystroke. egui only delivers
composition events to a widget that publishes `PlatformOutput::ime` in that
frame, and only a focused `TextEdit` did so — which opens after the grid has
already handled the first key. A CJK IME therefore lost its first key: with
Wubi, typing `xta` wrote `x` into the cell and the input method only ever saw
`ta`.

The grid now publishes `IMEOutput` (egui 0.37's `IMEOutput::new`, anchored to
the active cell) on every frame it owns keyboard input, so the first key
reaches the input method. The editor is seeded from `ImeEvent::Commit`, never
from a `Preedit`; `Event::Text` still handles ASCII exactly as before. The
`context_generation` is kept in `Context` data and advances when the grid
gains IME focus. `PlatformOutput` is rebuilt each frame, so the editor's own
`TextEdit` keeps owning composition without any explicit disable.

A locked cell on a protected sheet gets no IME request: `begin_edit` refuses
those edits, so the grid applies the same merged-cell anchor and protection
check before publishing, avoiding a composition that would be discarded.
`IMEOutput` wants screen coordinates, so the cell and merged-range rectangles
are mirrored for right-to-left sheets and the caret follows the drawn cell.

Adds `tests/it/ime_composition.rs` (registered in `tests/it/main.rs`) with
eight kittest cases: the grid publishes `PlatformOutput::ime` before the first
keystroke, IME is withheld for a dialog and for locked cells but kept for
unlocked cells on a protected sheet, the right-to-left rect is mirrored, a
commit opens the editor with the committed text, a preedit alone does not, and
ASCII typing still seeds the editor. The harness allows tofu because the
suite's pinned font set has no Han face; the tests are about input routing.
This commit is contained in:
alphazw committed 2026-11-13 16:45:13 +08:00
1 parent c0ee120ac2
commit 87d2264d92
3 files changed
+223 -4

No files matched your search

+79 -4
View File
@@ -32,6 +32,7 @@ pub(super) fn keyboard(app: &mut SheetApp, ctx: &egui::Context, resp: &egui::Res
ctx.memory_mut(|m| {
m.set_focus_lock_filter(resp.id, egui::EventFilter { tab: true, horizontal_arrows: true, vertical_arrows: true, escape: true })
});
request_grid_ime(app, ctx, resp, geo, sh);
let events = grid_events(app, ctx, sh);
// A shortcut key that also types a character (Shift+Space sends Text(" ")) must not start an edit.
let shortcut_pressed = events.iter().any(|e| {
@@ -43,6 +44,11 @@ pub(super) fn keyboard(app: &mut SheetApp, ctx: &egui::Context, resp: &egui::Res
// a shortcut ran, that text must not start an edit over what it just did.
let mut shortcut_ran = false;
for ev in events {
// IME events are handled outside the match to keep this loop's complexity down. Any
// non-commit IME event (preedit, delete-surrounding) falls through to `_ => {}` below.
if handle_ime_commit(app, &ev, shortcut_pressed, shortcut_ran) {
return;
}
match ev {
egui::Event::Copy => {
app.copy_to_clipboard(ctx, "edit.copy");
@@ -59,10 +65,7 @@ pub(super) fn keyboard(app: &mut SheetApp, ctx: &egui::Context, resp: &egui::Res
egui::Event::MiddleClickPaste { .. } => {}
egui::Event::Text(_) if shortcut_pressed || shortcut_ran => {}
egui::Event::Text(text) if text.chars().all(|c| !c.is_control()) && !text.is_empty() => {
app.begin_edit(Some(text), false);
if let Some(ed) = app.editor.as_mut() {
ed.caret = ed.text.chars().count();
}
seed_editor(app, text);
return;
}
egui::Event::Key { key, physical_key, pressed: true, modifiers: m, .. } => {
@@ -156,6 +159,78 @@ pub(super) fn keyboard(app: &mut SheetApp, ctx: &egui::Context, resp: &egui::Res
}
}
/// Open the in-cell editor with typed or committed text and put the caret after it.
fn seed_editor(app: &mut SheetApp, text: String) {
app.begin_edit(Some(text), false);
if let Some(ed) = app.editor.as_mut() {
ed.caret = ed.text.chars().count();
}
}
/// Seed the editor from a finished composition, if `ev` is one.
///
/// Only `ImeEvent::Commit` is finished text; a preedit is the input method's in-progress
/// spelling and must not seed the editor. `Event::Ime` and `Event::Text` are mutually
/// exclusive for one keystroke, so accepting a commit cannot double-insert a character.
/// Returns whether the caller should stop handling this frame's events.
fn handle_ime_commit(app: &mut SheetApp, ev: &egui::Event, shortcut_pressed: bool, shortcut_ran: bool) -> bool {
let egui::Event::Ime(egui::ImeEvent::Commit(text)) = ev else { return false };
if shortcut_pressed || shortcut_ran || text.is_empty() {
return false;
}
seed_editor(app, text.clone());
true
}
/// Ask the OS to route keystrokes through the input method while the grid owns keyboard input.
///
/// egui enables IME only for a widget that publishes `PlatformOutput::ime` in that frame. The
/// in-cell `TextEdit` opens *after* the grid has consumed the first keystroke, so without this
/// the first key of a CJK composition is delivered as raw `Event::Text` and lands in the cell
/// (Wubi `xta` writes `x` and the input method only ever sees `ta`). The request must be
/// published on every focused frame, not in response to a key: winit applies it at the end of
/// the frame, so a key arriving while IME is still off cannot be recovered.
///
/// `PlatformOutput` is rebuilt every frame, so returning early (an editor, a dialog or another
/// widget taking focus) simply leaves `ime` as `None` and the input method turns off.
fn request_grid_ime(app: &SheetApp, ctx: &egui::Context, resp: &egui::Response, geo: &Geo, sh: &Sheet) {
if !ctx.memory(|m| m.owns_ime_events(resp.id)) {
return;
}
let Some(d) = app.session.active() else { return };
let active = d.selection.active;
let merged = sh.merge_at(active);
// `begin_edit` refuses a locked cell on a protected sheet. Publishing an IME request for
// one would let the user compose text that is then discarded, so skip it up front, using
// the same merged-cell anchor and protection check as `SheetApp::begin_edit`.
let anchor = merged.map(|m| m.start).unwrap_or(active);
if app.session.locked_cell_message(d.wb.active_sheet(), anchor).is_some() {
return;
}
// `cell_rect`/`range_rect` are logical coordinates, but `IMEOutput` needs screen ones.
// On a right-to-left sheet the grid is mirrored, so publishing the logical rect puts the
// candidate window on the opposite side. After mirroring, `rect.min` is the screen-side
// start of the cell in both layouts, which is where the caret belongs.
let rect = match merged {
Some(m) => geo.mirror_rect(geo.range_rect(sh, m)),
None => geo.mirror_rect(geo.cell_rect(sh, active)),
};
let cursor_rect = egui::Rect::from_min_size(rect.min, egui::vec2(1.0, rect.height()));
// egui 0.37 identifies an IME context by (owner, generation). The generation must change
// when this owner gains focus and stay stable for ordinary text and selection updates.
let gained_focus = resp.gained_focus();
let generation = ctx.data_mut(|data| {
let g: &mut u64 = data.get_temp_mut_or_default(egui::Id::unique("gridcraft.grid_ime_generation"));
if gained_focus || *g == 0 {
*g = g.wrapping_add(1);
}
*g
});
ctx.output_mut(|o| {
o.ime = Some(egui::output::IMEOutput::new(resp.id, generation, egui::IMEPurpose::Normal, rect, cursor_rect));
});
}
/// This frame's input events, without those the focused form control took.
fn grid_events(app: &mut SheetApp, ctx: &egui::Context, sh: &Sheet) -> Vec<egui::Event> {
let events = ctx.input(|i| i.events.clone());
+143
View File
@@ -0,0 +1,143 @@
//! IME composition at the grid level.
//!
//! With a CJK input method, the first keystroke of a composition must reach the input method,
//! not be written straight into the cell as raw text. The grid publishes `PlatformOutput::ime`
//! on every frame it owns keyboard input, so the OS delivers `ImeEvent`s; a `Commit` opens the
//! in-cell editor with the finished text. Plain ASCII keeps using `Event::Text` (no regression).
use egui::{Event, ImeEvent};
use gridcraft_engine::Session;
use gridcraft_engine::core::CellRef;
use gridcraft_ui_egui::SheetApp;
use serde_json::json;
type Harness = egui_kittest::Harness<'static, SheetApp>;
/// A warmed harness over `session`, with the grid holding keyboard input on the active cell.
///
/// The suite pins a font set with no Han face, so the harness draws tofu for the CJK commit
/// text: these tests check input routing, not glyph coverage.
fn fixture_with(session: Session) -> Harness {
let builder = crate::common::builder().allow_missing_glyphs().with_size(egui::vec2(1200.0, 800.0));
crate::common::harness_with(builder, crate::common::app(session), 4)
}
/// A warmed harness over a blank workbook, with the grid holding keyboard input on `A1`.
fn fixture() -> Harness {
fixture_with(crate::support::blank_session())
}
/// A protected sheet with `active` selected, optionally unlocking one cell first.
fn protected_session(active: &str, unlock: Option<&str>) -> Session {
let mut s = Session::new();
s.new_workbook();
if let Some(cell) = unlock {
s.execute("home.formatCells", json!({"range": cell, "style": {"protection": {"locked": false}}})).unwrap();
}
s.execute("review.protectSheet", json!({})).unwrap();
s.execute("selection.set", json!({"cell": active})).unwrap();
s
}
/// The text the in-cell editor currently holds, or `None` when no editor is open.
fn editor_text(h: &Harness) -> Option<String> {
h.state().editor.as_ref().map(|ed| ed.text.clone())
}
/// The grid must request IME on every frame it owns keyboard input: winit applies
/// `set_ime_allowed` at the end of the frame, so requesting it in response to the first key is
/// already too late. The commit tests below only exercise the event handler and would still
/// pass with `request_grid_ime` removed, so this asserts the actual fix.
#[test]
fn grid_publishes_ime_request_before_the_first_keystroke() {
let mut h = fixture();
h.run_steps(1);
let ime = h.output().platform_output.ime.as_ref().expect("the focused grid must request IME");
assert!(matches!(ime.purpose, egui::IMEPurpose::Normal), "cell text is ordinary input");
assert!(ime.rect.width() > 0.0 && ime.rect.height() > 0.0, "the IME rect must cover the active cell");
assert_eq!(ime.cursor_rect.min, ime.rect.min, "the caret sits at the cell's start");
assert!(ime.context_generation > 0, "egui 0.37 needs a non-zero IME context generation");
}
/// When a dialog takes the keyboard, `PlatformOutput` must stop advertising a grid IME owner.
/// The output is rebuilt each frame, so an early return is what turns IME off.
#[test]
fn grid_withholds_ime_request_when_it_does_not_own_keyboard_input() {
let mut h = fixture();
h.state_mut().message = Some(("GridCraft".into(), "busy".into()));
h.run_steps(1);
assert!(h.output().platform_output.ime.is_none(), "a message dialog must take IME ownership away from the grid");
}
/// A locked cell on a protected sheet cannot be edited, so inviting a composition there would
/// only produce text that `SheetApp::begin_edit` discards.
#[test]
fn locked_cell_on_a_protected_sheet_does_not_request_ime() {
let mut h = fixture_with(protected_session("A1", None));
h.run_steps(1);
assert!(h.output().platform_output.ime.is_none(), "a composition on a locked cell is always refused");
}
/// The protection guard must not disable IME for cells that are still editable.
#[test]
fn unlocked_cell_on_a_protected_sheet_still_requests_ime() {
let mut h = fixture_with(protected_session("C2", Some("C2")));
h.run_steps(1);
assert!(h.output().platform_output.ime.is_some(), "unlocked cells stay editable on a protected sheet");
}
/// `IMEOutput::rect` is in screen coordinates, while `Geo::cell_rect` is in logical ones; on a
/// right-to-left sheet the two differ, and the candidate window must follow the drawn cell.
#[test]
fn right_to_left_sheet_publishes_mirrored_ime_rects() {
let mut s = Session::new();
s.new_workbook();
s.execute("view.rightToLeft", json!({"on": true})).unwrap();
s.execute("selection.set", json!({"cell": "B2"})).unwrap();
let mut h = fixture_with(s);
h.run_steps(1);
let geo = h.state().grid.geo.clone().expect("the grid has been drawn");
let sheet = h.state().session.active().unwrap().wb.active().unwrap();
let logical = geo.cell_rect(sheet, CellRef::parse("B2").unwrap());
let expected = geo.mirror_rect(logical);
assert!(geo.rtl, "the fixture must be right-to-left");
assert!((expected.min.x - logical.min.x).abs() > 1.0, "the fixture must distinguish mirrored from logical x");
let ime = h.output().platform_output.ime.as_ref().expect("the focused grid must request IME");
assert!((ime.rect.min.x - expected.min.x).abs() < 0.01, "IME rect must use screen coordinates: got {:?}, expected {:?}", ime.rect, expected);
assert!((ime.rect.max.x - expected.max.x).abs() < 0.01, "IME rect must use screen coordinates: got {:?}, expected {:?}", ime.rect, expected);
assert!((ime.cursor_rect.min.x - ime.rect.min.x).abs() < 0.01, "the caret must sit at the mirrored cell's start");
}
/// A committed composition opens the editor with its text and leaves the caret after it.
#[test]
fn ime_commit_opens_editor_with_committed_text() {
let mut h = fixture();
h.input_mut().events.push(Event::Ime(ImeEvent::Commit("张".into())));
h.run_steps(2);
let ed = h.state().editor.as_ref().expect("an IME commit must open the in-cell editor");
assert_eq!(ed.text, "张", "the committed text should seed the editor");
assert_eq!(ed.caret, ed.text.chars().count(), "the caret should sit after the committed text");
}
/// A preedit is not text yet: it must not open the editor on its own, only the commit does.
#[test]
fn ime_preedit_does_not_seed_editor() {
let mut h = fixture();
h.input_mut().events.push(Event::Ime(ImeEvent::Preedit { text: "zh".into(), active_range_chars: Some(0..2) }));
h.run_steps(2);
assert!(h.state().editor.is_none(), "a preedit must not seed the editor on its own");
h.input_mut().events.push(Event::Ime(ImeEvent::Commit("张".into())));
h.run_steps(2);
assert_eq!(editor_text(&h).as_deref(), Some("张"), "the commit after a preedit opens the editor");
}
/// Plain ASCII never composes, so `Event::Text` still seeds the editor exactly as before.
#[test]
fn ascii_text_still_seeds_editor_no_regression() {
let mut h = fixture();
h.input_mut().events.push(Event::Text("abc".into()));
h.run_steps(2);
assert_eq!(editor_text(&h).as_deref(), Some("abc"), "ASCII typing must still seed the editor");
}
+1
View File
@@ -59,6 +59,7 @@ mod header_column_drag;
mod host_chrome;
mod hyperlink_ctrl_click;
mod hyperlink_dialog;
mod ime_composition;
mod in_cell_editor_size;
mod in_cell_editor_wrap;
mod ink_render;