From 0886127774b391243bca2cd9da15b05c0b302e9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benoi=CC=82t=20Rouleau?= Date: Sat, 14 Nov 2026 14:16:16 -0500 Subject: [PATCH] Report the character a key types with each key down Add EventHandler::key_down_with_character_event, which carries what the key types on the keyboard's layout alongside its KeyCode, the key's place. It hands the key on to key_down_event unless implemented, so existing handlers are unchanged. macOS, the web, Windows, X11 and Wayland report the character; Android and iOS report None. This lets an app match letter shortcuts by the letter on the key, as macOS and browsers do, so Cmd+Z undoes from the key labelled Z on AZERTY, QWERTZ or Dvorak, rather than from the key in QWERTY's Z place. --- js/gl.js | 5 ++++- src/event.rs | 20 ++++++++++++++++++++ src/native/android.rs | 8 ++++++-- src/native/apple/apple_util.rs | 25 +++++++++++++++++++++++++ src/native/ios.rs | 2 +- src/native/linux_wayland.rs | 16 +++++++--------- src/native/linux_x11.rs | 9 ++++----- src/native/macos.rs | 5 +++-- src/native/wasm.rs | 5 +++-- src/native/windows.rs | 32 +++++++++++++++++++++++++++++++- 10 files changed, 104 insertions(+), 23 deletions(-) diff --git a/js/gl.js b/js/gl.js index df0116ac9..edc68ee4a 100644 --- a/js/gl.js +++ b/js/gl.js @@ -1238,7 +1238,10 @@ var importObject = { if (event.altKey) { modifiers |= SAPP_MODIFIER_ALT; } - wasm_exports.key_down(sapp_key_code, modifiers, event.repeat); + // `key` is one character, or a name like "Shift" or "Dead". + var characters = Array.from(event.key); + var character = characters.length == 1 ? characters[0].codePointAt(0) : 0; + wasm_exports.key_down(sapp_key_code, modifiers, event.repeat, character); // for "space", "quote", and "slash" preventDefault will prevent // key_press event, so send it here instead if (sapp_key_code == 32 || sapp_key_code == 39 || sapp_key_code == 47) { diff --git a/src/event.rs b/src/event.rs index 82e0a9258..495b30a21 100644 --- a/src/event.rs +++ b/src/event.rs @@ -181,8 +181,28 @@ pub trait EventHandler { fn char_event(&mut self, _character: char, _keymods: KeyMods, _repeat: bool) {} + /// `keycode` is the key's place on the keyboard, on most platforms: the key + /// in that place on a US QWERTY layout. See + /// [`key_down_with_character_event`](Self::key_down_with_character_event) + /// for what the key types on the user's layout. fn key_down_event(&mut self, _keycode: KeyCode, _keymods: KeyMods, _repeat: bool) {} + /// A key went down, with `character`, what it types on the keyboard's + /// current layout as Shift, and Command on macOS, change it, but not + /// Control: `'z'` for Ctrl+Z, and for Cmd+Z on a French AZERTY layout, whose + /// Z is where QWERTY has W. It's `None` when the key types no character, or + /// several, or the platform doesn't say. Unless implemented, it hands the + /// key on to [`key_down_event`](Self::key_down_event). + fn key_down_with_character_event( + &mut self, + keycode: KeyCode, + _character: Option, + keymods: KeyMods, + repeat: bool, + ) { + self.key_down_event(keycode, keymods, repeat); + } + /// Note: you are not always guaranteed to receive a key_up event. For example on /// Wayland when leaving the focused window, the key_up event will not be caught. fn key_up_event(&mut self, _keycode: KeyCode, _keymods: KeyMods) {} diff --git a/src/native/android.rs b/src/native/android.rs index 9542f2210..610a22455 100644 --- a/src/native/android.rs +++ b/src/native/android.rs @@ -220,8 +220,12 @@ impl MainThreadState { KeyCode::LeftSuper | KeyCode::RightSuper => self.keymods.logo = true, _ => {} } - self.event_handler - .key_down_event(keycode, self.keymods, false); + self.event_handler.key_down_with_character_event( + keycode, + None, + self.keymods, + false, + ); } Message::KeyUp { keycode } => { match keycode { diff --git a/src/native/apple/apple_util.rs b/src/native/apple/apple_util.rs index 0c5fbffaa..e5e4276f5 100644 --- a/src/native/apple/apple_util.rs +++ b/src/native/apple/apple_util.rs @@ -143,6 +143,31 @@ pub fn get_event_char(event: ObjcId) -> Option { } } +/// The one character `event`'s key types on the current layout with the event's +/// Shift and Command, as macOS matches menu shortcuts, so that a layout that +/// types QWERTY's letters while Command is held is followed. +pub fn get_event_key_character(event: ObjcId) -> Option { + unsafe { + let applies_modifiers: bool = + msg_send![event, respondsToSelector: sel!(charactersByApplyingModifiers:)]; + let characters: ObjcId = if applies_modifiers { + let flags: u64 = msg_send![event, modifierFlags]; + let kept = NSEventModifierFlags::NSShiftKeyMask as u64 + | NSEventModifierFlags::NSCommandKeyMask as u64; + msg_send![event, charactersByApplyingModifiers: flags & kept] + } else { + // Before macOS 10.15. + msg_send![event, charactersIgnoringModifiers] + }; + if characters == nil { + return None; + } + let characters = nsstring_to_string(characters); + let mut chars = characters.chars(); + chars.next().filter(|_| chars.next().is_none()) + } +} + pub fn get_event_key_modifier(event: ObjcId) -> KeyMods { let flags: u64 = unsafe { msg_send![event, modifierFlags] }; KeyMods { diff --git a/src/native/ios.rs b/src/native/ios.rs index 78ba78dd3..e1edef4ad 100644 --- a/src/native/ios.rs +++ b/src/native/ios.rs @@ -137,7 +137,7 @@ fn dispatch_message(payload: &mut IosDisplay, msg: Message) { state.keymods }; if let Some(ref mut event_handler) = payload.event_handler { - event_handler.key_down_event(keycode, keymods, false); + event_handler.key_down_with_character_event(keycode, None, keymods, false); } } Message::KeyUp { keycode } => { diff --git a/src/native/linux_wayland.rs b/src/native/linux_wayland.rs index f0a3179cd..f1a1a088d 100644 --- a/src/native/linux_wayland.rs +++ b/src/native/linux_wayland.rs @@ -298,15 +298,14 @@ impl KeyboardContext { // The keycodes in Miniquad are obtained without modifiers let keysym = libxkb.keymap_key_get_sym_without_mod(keymap.xkb_keymap, key + 8); let keycode = keycodes::translate_keysym(keysym); - events.push(WaylandEvent::KeyDown(keycode, keymods, repeat)); // To obtain the underlying character, we do need to provide the modifiers let keysym = (libxkb.xkb_state_key_get_one_sym)(xkb_state, key + 8); let chr = (libxkb.xkb_keysym_to_utf32)(keysym); - if chr > 0 { - if let Some(chr) = char::from_u32(chr) { - events.push(WaylandEvent::Char(chr, keymods, repeat)); - } + let character = char::from_u32(chr).filter(|_| chr > 0); + events.push(WaylandEvent::KeyDown(keycode, character, keymods, repeat)); + if let Some(chr) = character { + events.push(WaylandEvent::Char(chr, keymods, repeat)); } } } @@ -530,7 +529,7 @@ unsafe extern "C" fn seat_handle_capabilities( } enum WaylandEvent { - KeyDown(KeyCode, KeyMods, bool), + KeyDown(KeyCode, Option, KeyMods, bool), KeyUp(KeyCode, KeyMods), Char(char, KeyMods, bool), PointerMotion(f32, f32), @@ -1258,9 +1257,8 @@ where for event in display.events.drain(..) { match event { - WaylandEvent::KeyDown(keycode, keymods, repeat) => { - event_handler.key_down_event(keycode, keymods, repeat) - } + WaylandEvent::KeyDown(keycode, character, keymods, repeat) => event_handler + .key_down_with_character_event(keycode, character, keymods, repeat), WaylandEvent::KeyUp(keycode, keymods) => { event_handler.key_up_event(keycode, keymods) } diff --git a/src/native/linux_x11.rs b/src/native/linux_x11.rs index cc973fbcc..c324ee7aa 100644 --- a/src/native/linux_x11.rs +++ b/src/native/linux_x11.rs @@ -73,12 +73,11 @@ impl X11Display { std::ptr::null_mut(), ); let chr = keycodes::keysym_to_unicode(&mut self.libxkbcommon, keysym); - if chr > 0 { - if let Some(chr) = char::from_u32(chr as u32) { - event_handler.char_event(chr, mods, repeat); - } + let character = char::from_u32(chr as u32).filter(|_| chr > 0); + if let Some(chr) = character { + event_handler.char_event(chr, mods, repeat); } - event_handler.key_down_event(key, mods, repeat); + event_handler.key_down_with_character_event(key, character, mods, repeat); } 3 => { let keycode = event.xkey.keycode; diff --git a/src/native/macos.rs b/src/native/macos.rs index b8d01fdef..f5f9c4ea9 100644 --- a/src/native/macos.rs +++ b/src/native/macos.rs @@ -634,8 +634,9 @@ unsafe fn view_base_decl(decl: &mut ClassDecl) { let mods = get_event_key_modifier(event); let repeat: bool = unsafe { msg_send!(event, isARepeat) }; if let Some(key) = get_event_keycode(event) { + let character = get_event_key_character(event); if let Some(event_handler) = payload.context() { - event_handler.key_down_event(key, mods, repeat); + event_handler.key_down_with_character_event(key, character, mods, repeat); } } @@ -736,7 +737,7 @@ unsafe fn view_base_decl(decl: &mut ClassDecl) { if new_pressed ^ old_pressed { if new_pressed { if let Some(event_handler) = payload.context() { - event_handler.key_down_event(keycode, mods, false); + event_handler.key_down_with_character_event(keycode, None, mods, false); } } else { if let Some(event_handler) = payload.context() { diff --git a/src/native/wasm.rs b/src/native/wasm.rs index c79bb9ce8..6bbe84797 100644 --- a/src/native/wasm.rs +++ b/src/native/wasm.rs @@ -282,12 +282,13 @@ pub extern "C" fn mouse_wheel(dx: i32, dy: i32) { } #[no_mangle] -pub extern "C" fn key_down(key: u32, modifiers: u32, repeat: bool) { +pub extern "C" fn key_down(key: u32, modifiers: u32, repeat: bool, character: u32) { let key = keycodes::translate_keycode(key as _); let mods = keycodes::translate_mod(modifiers as _); + let character = char::from_u32(character).filter(|_| character > 0); tl_event_handler(|event_handler| { - event_handler.key_down_event(key, mods, repeat); + event_handler.key_down_with_character_event(key, character, mods, repeat); }); } diff --git a/src/native/windows.rs b/src/native/windows.rs index 3d2df69ea..01f3c021f 100644 --- a/src/native/windows.rs +++ b/src/native/windows.rs @@ -371,6 +371,35 @@ unsafe fn key_mods() -> KeyMods { mods } +/// The one character the virtual key `vk` types on the current layout, with +/// Shift held or not and no other modifier. +unsafe fn key_character(vk: UINT, scancode: UINT, shift: bool) -> Option { + let mut state = [0u8; 256]; + if shift { + state[VK_SHIFT as usize] = 0x80; + } + let mut typed = [0u16; 8]; + // Leaves the keyboard's state alone, so a dead key still reaches WM_CHAR. + const KEEP_KEYBOARD_STATE: UINT = 0x4; + let length = ToUnicodeEx( + vk, + scancode, + state.as_ptr(), + typed.as_mut_ptr(), + typed.len() as _, + KEEP_KEYBOARD_STATE, + GetKeyboardLayout(0), + ); + if length <= 0 { + return None; + } + let mut chars = char::decode_utf16(typed[..length as usize].iter().copied()); + match (chars.next(), chars.next()) { + (Some(Ok(character)), None) => Some(character), + _ => None, + } +} + unsafe extern "system" fn win32_wndproc( hwnd: HWND, umsg: UINT, @@ -695,7 +724,8 @@ unsafe extern "system" fn win32_wndproc( let keycode = keycodes::translate_keycode(keycode_raw); let mods = key_mods(); let repeat = !!(lparam & 0x40000000) != 0; - event_handler.key_down_event(keycode, mods, repeat); + let character = key_character(wparam as UINT, keycode_raw, mods.shift); + event_handler.key_down_with_character_event(keycode, character, mods, repeat); // Pass to DefWindowProc for IME to work properly return DefWindowProcW(hwnd, umsg, wparam, lparam); }