feat(macOS): support configurable keyboard types for simulated input

Cargo.toml

@@ -33,6 +33,7 @@ core-foundation = {version = "0.9.3"}
 core-foundation-sys = {version = "0.8.3"}
 core-graphics = {version = "0.22.3", features = ["highsierra"]}
 dispatch = "0.2"
+foreign-types = "0.3.2"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 epoll = {version = "4.1.0"}

examples/simulate_keyboard_type.rs

@@ -0,0 +1,165 @@
+#[cfg(target_os = "macos")]
+use rdev::EventType;
+#[cfg(target_os = "macos")]
+use rdev::MacKeyboardType;
+#[cfg(target_os = "macos")]
+use std::{env, thread, time};
+
+#[cfg(target_os = "macos")]
+const EVENT_DELAY_MS: u64 = 20;
+
+#[cfg(target_os = "macos")]
+const FOCUS_DELAY_SECS: u64 = 2;
+#[cfg(target_os = "macos")]
+const SEND_CONFIRM_ARG: &str = "--send";
+
+#[cfg(target_os = "macos")]
+struct MacKeyboardSample {
+    name: &'static str,
+    keycodes: &'static [rdev::CGKeyCode],
+}
+
+#[cfg(target_os = "macos")]
+enum SampleError {
+    CreateVirtualInput,
+    SendInput,
+}
+
+#[cfg(target_os = "macos")]
+fn mac_key(keycode: rdev::CGKeyCode) -> rdev::Key {
+    rdev::Key::RawKey(rdev::RawKey::MacVirtualKeycode(keycode))
+}
+
+#[cfg(target_os = "macos")]
+fn send_with_input(input: &rdev::VirtualInput, event_type: &EventType) -> Result<(), SampleError> {
+    let delay = time::Duration::from_millis(EVENT_DELAY_MS);
+    input
+        .simulate(event_type)
+        .map_err(|_| SampleError::SendInput)?;
+    thread::sleep(delay);
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn send_key_sequence(
+    input: &rdev::VirtualInput,
+    keycodes: &[rdev::CGKeyCode],
+) -> Result<(), SampleError> {
+    let mut pressed = Vec::with_capacity(keycodes.len());
+    for keycode in keycodes {
+        if let Err(error) = send_with_input(input, &EventType::KeyPress(mac_key(*keycode))) {
+            release_pressed_keys(input, &pressed);
+            return Err(error);
+        }
+        pressed.push(*keycode);
+    }
+    let mut release_error = None;
+    for keycode in pressed.iter().rev() {
+        if let Err(error) = send_with_input(input, &EventType::KeyRelease(mac_key(*keycode))) {
+            release_error = Some(error);
+        }
+    }
+    if let Some(error) = release_error {
+        return Err(error);
+    }
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn release_pressed_keys(input: &rdev::VirtualInput, keycodes: &[rdev::CGKeyCode]) {
+    for keycode in keycodes.iter().rev() {
+        let _ = send_with_input(input, &EventType::KeyRelease(mac_key(*keycode)));
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn send_keyboard_type_samples(
+    keyboard_type_name: &str,
+    keyboard_type: MacKeyboardType,
+    samples: &[MacKeyboardSample],
+) -> Result<(), SampleError> {
+    let Ok(virtual_input) = rdev::VirtualInput::new(
+        rdev::CGEventSourceStateID::HIDSystemState,
+        rdev::CGEventTapLocation::HID,
+    ) else {
+        return Err(SampleError::CreateVirtualInput);
+    };
+    let virtual_input = virtual_input.with_keyboard_type(keyboard_type);
+
+    println!("Sending {} keyboard samples:", keyboard_type_name);
+    for sample in samples {
+        println!("  {}", sample.name);
+        send_key_sequence(&virtual_input, sample.keycodes)?;
+        send_key_sequence(&virtual_input, &[rdev::kVK_Space])?;
+    }
+    send_key_sequence(&virtual_input, &[rdev::kVK_Return])
+}
+
+#[cfg(target_os = "macos")]
+fn test_macos_keys() {
+    if !env::args().any(|arg| arg == SEND_CONFIRM_ARG) {
+        println!(
+            "This example sends real key events to the focused application. Run with {} to continue.",
+            SEND_CONFIRM_ARG
+        );
+        return;
+    }
+
+    let samples = [
+        MacKeyboardSample {
+            name: "Shift+2",
+            keycodes: &[rdev::kVK_Shift, rdev::kVK_ANSI_2],
+        },
+        MacKeyboardSample {
+            name: "ANSI backslash",
+            keycodes: &[rdev::kVK_ANSI_Backslash],
+        },
+        MacKeyboardSample {
+            name: "ISO section",
+            keycodes: &[rdev::kVK_ISO_Section],
+        },
+        MacKeyboardSample {
+            name: "JIS yen",
+            keycodes: &[rdev::kVK_JIS_Yen],
+        },
+    ];
+
+    println!(
+        "Focus a text field. Sending ANSI, ISO, and JIS samples in {} seconds.",
+        FOCUS_DELAY_SECS
+    );
+    println!("Each row uses: Shift+2, ANSI backslash, ISO section, JIS yen.");
+    thread::sleep(time::Duration::from_secs(FOCUS_DELAY_SECS));
+
+    for (keyboard_type_name, keyboard_type) in [
+        ("ANSI", MacKeyboardType::Ansi),
+        ("ISO", MacKeyboardType::Iso),
+        ("JIS", MacKeyboardType::Jis),
+    ] {
+        if let Err(error) = send_keyboard_type_samples(keyboard_type_name, keyboard_type, &samples)
+        {
+            match error {
+                SampleError::CreateVirtualInput => {
+                    println!(
+                        "Failed to create VirtualInput for {} keyboard samples",
+                        keyboard_type_name
+                    );
+                }
+                SampleError::SendInput => {
+                    println!("Failed to send {} keyboard samples", keyboard_type_name);
+                }
+            }
+            return;
+        }
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn main() {
+    test_macos_keys();
+}
+
+#[cfg(not(target_os = "macos"))]
+fn main() {
+    println!("This example is only implemented for MacOS.");
+}

src/codes_conv.rs

@@ -155,7 +155,7 @@ mod test {
                     continue;
                 }
                 if let Some(code2) = super::usb_hid_code_to_macos_code(usb_hid) {
-                    assert_eq!(code, code2 as u32)
+                    assert_eq!(u32::from(code), code2 as u32)
                 } else {
                     assert!(false, "We could not convert back code: {:?}", code);
                 }

src/lib.rs

@@ -265,6 +265,32 @@ pub use crate::macos::{set_is_main_thread, Keyboard, VirtualInput};
 #[cfg(target_os = "macos")]
 pub use core_graphics::{event::CGEventTapLocation, event_source::CGEventSourceStateID};
 
+#[cfg(target_os = "macos")]
+/// Selects the macOS hardware keyboard type used when translating physical keycodes.
+///
+/// This does not switch the current macOS input source, keyboard layout, or IME.
+/// Character output is still translated with the active system input source.
+/// For example, `Iso` means ISO hardware type, not a specific country layout
+/// such as British, German, or French.
+#[non_exhaustive]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum MacKeyboardType {
+    /// Use the system keyboard type reported by macOS.
+    Current,
+    /// Use ANSI hardware keyboard translation.
+    Ansi,
+    /// Use ISO hardware keyboard translation.
+    Iso,
+    /// Use JIS hardware keyboard translation.
+    Jis,
+    /// Use a raw CoreGraphics keyboard type value.
+    ///
+    /// This is an opaque CoreGraphics keyboard type ID, not a stable keyboard
+    /// layout selector. Prefer the named variants unless the value comes from
+    /// CoreGraphics or another macOS system API.
+    Raw(u32),
+}
+
 #[cfg(any(target_os = "android", target_os = "linux"))]
 pub use crate::keycodes::linux::{code_from_key, key_from_code};
 #[cfg(target_os = "linux")]