Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Cua AI, Inc.
//! Background input injection for Linux via X11 XSendEvent.
//!
//! XSendEvent sends synthetic events directly to a window without changing
//! input focus — the Linux equivalent of PostMessage on Windows, and the
//! mechanism behind the cross-platform "no focus steal" contract.
//!
//! Note: a few apps check the `send_event` flag and ignore synthetic events.
//! Terminal emulators are the notable case (xterm's `allowSendEvents` is off by
//! default); those are handled out of band by writing to the pty master — see
//! `crate::tty`. We deliberately do NOT fall back to the XTest extension for
//! them, because XTest delivers to the *focused* window and would break the
//! no-focus-steal contract.
pub mod action;
/// Shared `delivery_mode` contract (background|foreground) — mirrors macOS
/// `tools::DeliveryMode` and Windows `input::delivery`.
pub mod delivery;
pub mod focus_guard;
pub mod foreground;
/// Low-latency ordered input batches for one target (embedders).
pub mod interactive;
mod mpx_keyboard;
mod mpx_owner;
/// One-shot targeted pointer/keyboard delivery with explicit
/// auto/background/foreground semantics (embedders).
pub mod targeted;
pub use focus_guard::{FocusGuardReport, FocusSnapshot, SameAppWindow};
pub use foreground::{FocusAfter, ForegroundOptions, ForegroundReport};
pub use mpx_keyboard::{
real_keyboard_input_available, send_popup_keyboard_key, send_popup_keyboard_text,
send_virtual_keyboard_key, send_virtual_keyboard_text, KeyboardDeliveryReport, MPX_UINPUT_PATH,
};
use anyhow::{anyhow, bail, Context, Result};
use evdev::uinput::VirtualDevice;
use evdev::{AttributeSet, EventType, InputEvent, Key, RelativeAxisType};
use std::cell::RefCell;
use std::collections::HashMap;
use std::ffi::{CStr, CString};
use std::fs;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::ptr;
use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use std::thread::sleep;
use std::time::{Duration, Instant};
use x11rb::connection::Connection;
use x11rb::protocol::xproto::*;
use x11rb::rust_connection::RustConnection;
const CLICK_DELAY_MS: u64 = 35;
const DOUBLE_CLICK_DELAY_MS: u64 = 50;
const KEY_DELAY_MS: u64 = 10;
const PING_TIMEOUT: Duration = Duration::from_secs(1);
static PING_SERIAL: AtomicU32 = AtomicU32::new(1);
#[derive(Clone, Debug)]
pub struct VirtualPointerDrag {
pub target_window: u64,
pub button: u8,
/// Screen-coordinate waypoints. The pointer presses once at `path[0]`,
/// glides through every waypoint (arc-length interpolated), and releases
/// once at the last point — a single continuous held drag, so a curved
/// path (e.g. a sampled y = f(x)) draws as one smooth stroke rather than
/// a chain of press/release dabs. Must contain >= 2 points.
pub path: Vec<(i32, i32)>,
pub duration_ms: u64,
pub steps: usize,
}
/// Cumulative segment lengths along `path` and its total length.
fn path_cumulative(path: &[(i32, i32)]) -> (Vec<f64>, f64) {
let mut cum = Vec::with_capacity(path.len());
let mut total = 0.0;
cum.push(0.0);
for w in path.windows(2) {
let dx = (w[1].0 - w[0].0) as f64;
let dy = (w[1].1 - w[0].1) as f64;
total += (dx * dx + dy * dy).sqrt();
cum.push(total);
}
(cum, total)
}
/// Sample `y = f(x)` over `[x_from, x_to]` into `samples` window-local
/// waypoints. Evaluated with meval (sin/cos/^/etc.); non-finite outputs
/// (ln of a negative, 1/0, …) are dropped. Errors on a bad expression or
/// fewer than 2 finite points.
pub fn sample_function(
expr: &str,
x_from: f64,
x_to: f64,
samples: u64,
) -> Result<Vec<(f64, f64)>> {
let parsed: meval::Expr = expr
.parse()
.map_err(|e| anyhow!("invalid fn '{expr}': {e}"))?;
let f = parsed
.bind("x")
.map_err(|e| anyhow!("fn must be in terms of x: {e}"))?;
let n = samples.max(2);
let mut pts = Vec::with_capacity(n as usize);
for i in 0..n {
let x = x_from + (x_to - x_from) * (i as f64) / ((n - 1) as f64);
let y = f(x);
if x.is_finite() && y.is_finite() {
pts.push((x, y));
}
}
if pts.len() < 2 {
bail!("fn produced fewer than 2 finite points over the domain");
}
Ok(pts)
}
/// Point at arc-length fraction `t` (0..1) along `path`.
fn point_on_path(path: &[(i32, i32)], cum: &[f64], total: f64, t: f64) -> (i32, i32) {
if path.len() == 1 || total <= 0.0 {
return *path.last().unwrap();
}
let d = t.clamp(0.0, 1.0) * total;
let mut i =
match cum.binary_search_by(|v| v.partial_cmp(&d).unwrap_or(std::cmp::Ordering::Less)) {
Ok(i) => i,
Err(i) => i.saturating_sub(1),
};
if i >= path.len() - 1 {
i = path.len() - 2;
}
let seg = cum[i + 1] - cum[i];
let f = if seg > 0.0 { (d - cum[i]) / seg } else { 0.0 };
let x = path[i].0 as f64 + (path[i + 1].0 - path[i].0) as f64 * f;
let y = path[i].1 as f64 + (path[i + 1].1 - path[i].1) as f64 * f;
(x.round() as i32, y.round() as i32)
}
/// One session's XI2 master pair (XIAddMaster always creates a pointer AND a
/// keyboard) plus the uinput slaves attached to it. The keyboard slave is
/// created lazily by `mpx_keyboard::ensure_master_keyboard`, so a pointer-only
/// click never pays for a second device hotplug.
#[derive(Clone, Copy, Debug)]
struct MasterPointerIds {
pointer_id: i32,
keyboard_id: i32,
_slave_pointer_id: i32,
slave_keyboard_id: Option<i32>,
}
static MPX_POINTERS: OnceLock<Mutex<HashMap<String, MasterPointerIds>>> = OnceLock::new();
static UINPUT_POINTERS: OnceLock<Mutex<HashMap<String, Arc<Mutex<VirtualDevice>>>>> =
OnceLock::new();
static XLIB_THREADS_READY: OnceLock<Result<(), String>> = OnceLock::new();
/// Serialises every MPX operation against the idle reaper (and each other),
/// so a retained master pair is never torn down while a call is using it.
static MPX_OP_LOCK: Mutex<()> = Mutex::new(());
static MPX_LAST_USE: OnceLock<Mutex<HashMap<String, std::time::Instant>>> = OnceLock::new();
static MPX_IDLE_REAPER: std::sync::Once = std::sync::Once::new();
static MPX_CLICK_POPUPS: OnceLock<Mutex<HashMap<String, ClickPopups>>> = OnceLock::new();
/// A session's retained master pair is removed after this much inactivity;
/// `end_session` and the startup reaper cover the explicit and crash cases.
/// `XIRemoveMaster` churns the XInput hierarchy, and mutter 42.x segfaults when
/// it processes that churn (the same reason per-call teardown crashes LibreOffice
/// VCL), so the pair must outlive the inter-action idle of a live session; a
/// long terminal-only stretch leaves the pointer unused far past a few minutes.
/// The window is only a leak backstop for a client that dies without
/// `end_session`; the startup reaper reclaims anything it misses.
const MPX_IDLE_TTL: Duration = Duration::from_secs(1800);
const MPX_IDLE_REAPER_PERIOD: Duration = Duration::from_secs(60);
const MPX_POPUP_QUIET: Duration = Duration::from_millis(250);
static MPX_NAME_COUNTER: AtomicU64 = AtomicU64::new(1);
// evdev 0.12.2 asserts `name.len() + 1 < UINPUT_MAX_NAME_SIZE` while building
// a device. Linux defines UINPUT_MAX_NAME_SIZE as 80, leaving 78 usable bytes.
const EVDEV_UINPUT_NAME_MAX_BYTES: usize = 78;
const UINPUT_POINTER_SUFFIX: &str = " uinput pointer";
pub const UINPUT_UNAVAILABLE_CODE: &str = "uinput_unavailable";
/// Result `path` for pointer actions delivered as real button events from the
/// session's MPX virtual master pointer.
pub const MPX_POINTER_PATH: &str = "mpx_pointer";
#[derive(Debug, thiserror::Error)]
#[error("Linux uinput device unavailable: {reason}")]
struct UinputUnavailable {
reason: String,
}
fn mpx_pointers() -> &'static Mutex<HashMap<String, MasterPointerIds>> {
MPX_POINTERS.get_or_init(|| Mutex::new(HashMap::new()))
}
fn mpx_last_use() -> &'static Mutex<HashMap<String, std::time::Instant>> {
MPX_LAST_USE.get_or_init(|| Mutex::new(HashMap::new()))
}
#[derive(Default)]
struct ClickPopups {
windows: Vec<u64>,
removal_due: Option<Instant>,
}
fn mpx_click_popups() -> &'static Mutex<HashMap<String, ClickPopups>> {
MPX_CLICK_POPUPS.get_or_init(|| Mutex::new(HashMap::new()))
}
fn mark_mpx_use(cursor_id: &str) {
mpx_last_use()
.lock()
.unwrap()
.insert(cursor_id.to_owned(), Instant::now());
if let Some(popups) = mpx_click_popups().lock().unwrap().get_mut(cursor_id) {
popups.removal_due = None;
}
}
fn track_click_popups(cursor_id: &str, opened: impl IntoIterator<Item = u64>) {
let opened: Vec<u64> = opened.into_iter().collect();
let mut tracked = mpx_click_popups().lock().unwrap();
for (id, popups) in tracked.iter_mut() {
if id != cursor_id {
popups.windows.retain(|window| !opened.contains(window));
}
}
let windows = &mut tracked.entry(cursor_id.to_owned()).or_default().windows;
windows.extend(opened);
windows.sort_unstable();
windows.dedup();
}
fn popup_owner(
window: u64,
appeared: &HashMap<String, ClickPopups>,
live: impl Fn(&str) -> bool,
) -> Option<String> {
appeared
.iter()
.find(|(id, popups)| popups.windows.contains(&window) && live(id))
.map(|(id, _)| id.clone())
}
#[derive(Debug, thiserror::Error)]
#[error("no live session's click opened the popup")]
pub struct PopupOwnerGone;
fn popup_owner_guard(popup: u64) -> Result<(std::sync::MutexGuard<'static, ()>, String)> {
let guard = MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let appeared = mpx_click_popups().lock().unwrap();
let pointers = mpx_pointers().lock().unwrap();
let owner = popup_owner(popup, &appeared, |id| pointers.contains_key(id));
drop((pointers, appeared));
Ok((guard, owner.ok_or(PopupOwnerGone)?))
}
/// Take the MPX operation lock for one call on `cursor_id`, stamp its last
/// use, and make sure the idle reaper is running. Hold the guard for the
/// whole operation.
fn mpx_op_guard(cursor_id: &str) -> std::sync::MutexGuard<'static, ()> {
let guard = MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
mark_mpx_use(cursor_id);
MPX_IDLE_REAPER.call_once(|| {
std::thread::Builder::new()
.name("cua-mpx-idle-reaper".into())
.spawn(|| loop {
sleep(MPX_IDLE_REAPER_PERIOD);
let _op = MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let stale = {
let last_use = mpx_last_use().lock().unwrap();
stale_cursor_ids(&last_use, std::time::Instant::now(), MPX_IDLE_TTL)
};
for cursor_id in stale {
tracing::info!(cursor_id, "removing idle MPX master pair");
forget_master_pointer_locked(&cursor_id);
}
})
.ok();
});
guard
}
/// Sessions whose last MPX use is older than `ttl`.
fn stale_cursor_ids(
last_use: &HashMap<String, std::time::Instant>,
now: std::time::Instant,
ttl: Duration,
) -> Vec<String> {
last_use
.iter()
.filter(|(_, at)| now.saturating_duration_since(**at) >= ttl)
.map(|(id, _)| id.clone())
.collect()
}
fn uinput_pointers() -> &'static Mutex<HashMap<String, Arc<Mutex<VirtualDevice>>>> {
UINPUT_POINTERS.get_or_init(|| Mutex::new(HashMap::new()))
}
fn master_pointer_name(cursor_id: &str) -> String {
let nonce = MPX_NAME_COUNTER.fetch_add(1, Ordering::Relaxed);
if let Ok(owner) = mpx_owner::Owner::current() {
return owner.master_name(nonce);
}
// Unknown procfs identity cannot safely participate in automatic recovery.
// Preserve ordinary operation, with the legacy name and cleanup behavior.
let prefix = "CUA ";
let suffix = format!(" mp-{}-{nonce}", std::process::id());
let max_cursor_bytes = EVDEV_UINPUT_NAME_MAX_BYTES
.saturating_sub(prefix.len() + suffix.len() + UINPUT_POINTER_SUFFIX.len());
let cursor_id = sanitize_device_name(cursor_id);
format!(
"{prefix}{}{suffix}",
truncate_utf8(&cursor_id, max_cursor_bytes)
)
}
fn slave_pointer_name(master_name: &str) -> String {
format!("{master_name}{UINPUT_POINTER_SUFFIX}")
}
fn truncate_utf8(value: &str, max_bytes: usize) -> &str {
let mut end = value.len().min(max_bytes);
while !value.is_char_boundary(end) {
end -= 1;
}
&value[..end]
}
fn sanitize_device_name(value: &str) -> String {
value
.chars()
.map(|ch| if ch.is_control() { '_' } else { ch })
.collect()
}
fn normalize_uinput_device_name(name: &str) -> String {
let sanitized = sanitize_device_name(name);
truncate_utf8(&sanitized, EVDEV_UINPUT_NAME_MAX_BYTES).to_owned()
}
fn panic_payload_message(payload: &(dyn std::any::Any + Send)) -> &str {
payload
.downcast_ref::<&str>()
.copied()
.or_else(|| payload.downcast_ref::<String>().map(String::as_str))
.unwrap_or("unknown panic")
}
pub(crate) fn uinput_unavailable(reason: impl Into<String>) -> anyhow::Error {
UinputUnavailable {
reason: reason.into(),
}
.into()
}
fn guarded_uinput_creation<T>(name: &str, create: impl FnOnce(&str) -> Result<T>) -> Result<T> {
let name = normalize_uinput_device_name(name);
match catch_unwind(AssertUnwindSafe(|| create(&name))) {
Ok(Ok(device)) => Ok(device),
Ok(Err(error)) => Err(uinput_unavailable(error.to_string())),
Err(payload) => Err(uinput_unavailable(format!(
"device creation panicked: {}",
panic_payload_message(payload.as_ref())
))),
}
}
pub fn is_uinput_unavailable(error: &anyhow::Error) -> bool {
error.downcast_ref::<UinputUnavailable>().is_some()
}
fn master_pointer_device_name(master_name: &str) -> String {
format!("{master_name} pointer")
}
fn master_keyboard_device_name(master_name: &str) -> String {
format!("{master_name} keyboard")
}
fn open_display() -> Result<*mut x11::xlib::Display> {
open_named_display(ptr::null())
}
fn open_named_display(name: *const std::ffi::c_char) -> Result<*mut x11::xlib::Display> {
match XLIB_THREADS_READY.get_or_init(|| {
let rc = unsafe { x11::xlib::XInitThreads() };
if rc == 0 {
Err("XInitThreads failed".to_owned())
} else {
Ok(())
}
}) {
Ok(()) => {}
Err(err) => bail!("{err}"),
}
let display = unsafe { x11::xlib::XOpenDisplay(name) };
if display.is_null() {
bail!("XOpenDisplay returned null");
}
Ok(display)
}
fn xi2_query_devices(display: *mut x11::xlib::Display) -> Result<Vec<(i32, i32, String)>> {
let mut count = 0;
let ptr =
unsafe { x11::xinput2::XIQueryDevice(display, x11::xinput2::XIAllDevices, &mut count) };
if ptr.is_null() {
bail!("XIQueryDevice returned null");
}
let mut out = Vec::new();
for i in 0..count {
let info = unsafe { *ptr.add(i as usize) };
let name = if info.name.is_null() {
String::new()
} else {
unsafe { CStr::from_ptr(info.name) }
.to_string_lossy()
.into_owned()
};
out.push((info.deviceid, info._use, name));
}
unsafe { x11::xinput2::XIFreeDeviceInfo(ptr) };
Ok(out)
}
fn x_server_vendor(display: *mut x11::xlib::Display) -> String {
let ptr = unsafe { x11::xlib::XServerVendor(display) };
if ptr.is_null() {
return String::new();
}
unsafe { CStr::from_ptr(ptr) }
.to_string_lossy()
.into_owned()
}
fn supports_parallel_pointer_injection(display: *mut x11::xlib::Display) -> Result<()> {
let vendor = x_server_vendor(display);
if vendor.to_ascii_lowercase().contains("tigervnc") {
bail!(
"parallel_mouse_drag is not supported on this X server ('{vendor}'). \
Xtigervnc exposes only its built-in VNC/XTEST devices, so Linux uinput/libinput \
pointers cannot become real X input devices here."
);
}
if is_xtigervnc_process_running() {
let display_name = std::env::var("DISPLAY").unwrap_or_else(|_| "<unknown>".to_owned());
bail!(
"parallel_mouse_drag is not supported on display {display_name} because the active X server is Xtigervnc. \
Xtigervnc exposes only its built-in VNC/XTEST devices, so Linux uinput/libinput pointers \
cannot become real X input devices in this environment."
);
}
Ok(())
}
fn is_xtigervnc_process_running() -> bool {
let display = std::env::var("DISPLAY").unwrap_or_default();
// Extract display number from DISPLAY (e.g., ":0" -> "0", "host:1.0" -> "1")
let display_num = display
.rsplit(':')
.next()
.unwrap_or("")
.split('.')
.next()
.unwrap_or("")
.trim();
if display_num.is_empty() {
return false;
}
// The X server writes its PID to the standard lock file /tmp/.X{N}-lock
let lock_path = format!("/tmp/.X{display_num}-lock");
let Ok(contents) = fs::read_to_string(&lock_path) else {
return false;
};
let pid = contents.trim();
if pid.is_empty() || !pid.bytes().all(|b| b.is_ascii_digit()) {
return false;
}
// Check the executable path of the X server process directly
if let Ok(exe) = fs::read_link(format!("/proc/{pid}/exe")) {
return exe.file_name().and_then(|n| n.to_str()) == Some("Xtigervnc");
}
// Fallback: check the process name via comm (limited to 15 chars, but "Xtigervnc" fits)
if let Ok(comm) = fs::read_to_string(format!("/proc/{pid}/comm")) {
return comm.trim() == "Xtigervnc";
}
false
}
pub fn check_parallel_pointer_support() -> Result<()> {
let display = open_display()?;
let result = supports_parallel_pointer_injection(display);
unsafe { x11::xlib::XCloseDisplay(display) };
result
}
/// The file name of the X server binary backing `DISPLAY`, read from the PID in
/// the server's standard `/tmp/.X{N}-lock` file. Used to recognise servers that
/// can't expose uinput/libinput pointers as real X input slaves.
fn x_server_exe_name() -> Option<String> {
let display = std::env::var("DISPLAY").unwrap_or_default();
let display_num = display
.rsplit(':')
.next()
.unwrap_or("")
.split('.')
.next()
.unwrap_or("")
.trim();
if display_num.is_empty() {
return None;
}
let lock_path = format!("/tmp/.X{display_num}-lock");
let contents = fs::read_to_string(&lock_path).ok()?;
let pid = contents.trim();
if pid.is_empty() || !pid.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
if let Ok(exe) = fs::read_link(format!("/proc/{pid}/exe")) {
if let Some(name) = exe.file_name().and_then(|n| n.to_str()) {
return Some(name.to_owned());
}
}
fs::read_to_string(format!("/proc/{pid}/comm"))
.ok()
.map(|s| s.trim().to_owned())
}
/// True when `DISPLAY` is served by a headless Xvfb. Xvfb has no udev/libinput
/// hotplug, so a uinput device never becomes an X input slave — the whole MPX
/// real-input path (master pointer + uinput slave + shield grab) can never
/// work, and `ensure_master_pointer` would otherwise burn the 5 s slave-bind
/// timeout per attempt before failing.
fn is_xvfb_process_running() -> bool {
x_server_exe_name().as_deref() == Some("Xvfb")
}
/// Cheap up-front probe (no device creation, no slave-bind wait) for whether the
/// no-focus-steal MPX real-input pointer path can work on this X server. Lets the
/// click/scroll tools decide whether to attempt the MPX path or go straight to
/// the legacy XSendEvent fallback, without paying the multi-second uinput
/// slave-bind timeout on servers (Xvfb, Xtigervnc) where it can never succeed.
///
/// NOTE: this only rules out the servers known to lack uinput→X-slave hotplug.
/// A `true` result means "worth attempting"; the per-action call still fails
/// gracefully (and the caller falls back) if the slave never binds.
fn real_pointer_capabilities_available(
server_supported: bool,
xvfb: bool,
uinput_accessible: bool,
unsafe_hotplug_session: bool,
) -> bool {
server_supported && !xvfb && uinput_accessible && !unsafe_hotplug_session
}
fn nonempty(value: Option<&str>) -> bool {
value.is_some_and(|value| !value.trim().is_empty())
}
fn desktop_value_is_kde(value: Option<&str>) -> bool {
value.is_some_and(|value| {
value
.split([':', ';', ','])
.map(str::trim)
.any(|token| token.eq_ignore_ascii_case("kde") || token.eq_ignore_ascii_case("plasma"))
})
}
/// KDE Plasma 6 / Qt 6.11 applications on X11 can crash session-wide when an
/// ephemeral uinput pointer is hotplugged into Xorg. Foreground input does not
/// need that device: the click, drag, scroll, and keyboard tools already use
/// XTEST after activating the target window. Disable only the MPX/uinput
/// capability here so callers retain their existing foreground escalation and
/// XSendEvent fallback behavior.
fn kde_x11_uinput_hotplug_is_unsafe(
session_type: Option<&str>,
current_desktop: Option<&str>,
session_desktop: Option<&str>,
desktop_session: Option<&str>,
kde_full_session: Option<&str>,
display: Option<&str>,
wayland_display: Option<&str>,
) -> bool {
let explicit_x11 = session_type.is_some_and(|value| value.eq_ignore_ascii_case("x11"));
let explicit_wayland = session_type.is_some_and(|value| value.eq_ignore_ascii_case("wayland"));
if explicit_wayland || (!explicit_x11 && nonempty(wayland_display)) {
return false;
}
let x11 = explicit_x11 || nonempty(display);
let kde = desktop_value_is_kde(current_desktop)
|| desktop_value_is_kde(session_desktop)
|| desktop_value_is_kde(desktop_session)
|| kde_full_session.is_some_and(|value| {
matches!(
value.trim().to_ascii_lowercase().as_str(),
"1" | "true" | "yes"
)
});
x11 && kde
}
fn kde_x11_uinput_hotplug_is_unsafe_from_env() -> bool {
let session_type = std::env::var("XDG_SESSION_TYPE").ok();
let current_desktop = std::env::var("XDG_CURRENT_DESKTOP").ok();
let session_desktop = std::env::var("XDG_SESSION_DESKTOP").ok();
let desktop_session = std::env::var("DESKTOP_SESSION").ok();
let kde_full_session = std::env::var("KDE_FULL_SESSION").ok();
let display = std::env::var("DISPLAY").ok();
let wayland_display = std::env::var("WAYLAND_DISPLAY").ok();
kde_x11_uinput_hotplug_is_unsafe(
session_type.as_deref(),
current_desktop.as_deref(),
session_desktop.as_deref(),
desktop_session.as_deref(),
kde_full_session.as_deref(),
display.as_deref(),
wayland_display.as_deref(),
)
}
pub(crate) fn uinput_accessible() -> bool {
fs::OpenOptions::new()
.read(true)
.write(true)
.open("/dev/uinput")
.is_ok()
}
pub fn real_pointer_input_available() -> bool {
// Do not even probe /dev/uinput on an affected KDE/X11 session. Creating
// the device is itself the dangerous operation; a later fallback is too
// late once Xorg has announced the hotplug to Qt clients.
if kde_x11_uinput_hotplug_is_unsafe_from_env() {
return false;
}
// `ensure_master_pointer` creates an XI2 master before attaching the
// uinput slave. If this process cannot open /dev/uinput, attempting that
// path on every click/scroll would create and abandon an XInput master
// pair until Xorg terminates the client with BadAlloc. Skip MPX entirely
// when the required device is inaccessible.
if !uinput_accessible() {
return false;
}
let Ok(display) = open_display() else {
return false;
};
let supported = real_pointer_capabilities_available(
supports_parallel_pointer_injection(display).is_ok(),
is_xvfb_process_running(),
true,
false,
);
unsafe { x11::xlib::XCloseDisplay(display) };
supported
}
fn ensure_master_pointer(cursor_id: &str) -> Result<MasterPointerIds> {
ensure_master_pointer_for_session(cursor_id, kde_x11_uinput_hotplug_is_unsafe_from_env())
}
fn ensure_master_pointer_for_session(
cursor_id: &str,
unsafe_hotplug_session: bool,
) -> Result<MasterPointerIds> {
if unsafe_hotplug_session {
return Err(uinput_unavailable(
"disabled on KDE Plasma X11; retry with delivery_mode='foreground'",
));
}
if let Some(ids) = mpx_pointers().lock().unwrap().get(cursor_id).copied() {
return Ok(ids);
}
let display = open_display()?;
let mut major = 2;
let mut minor = 3;
let rc = unsafe { x11::xinput2::XIQueryVersion(display, &mut major, &mut minor) };
if rc != 0 {
unsafe { x11::xlib::XCloseDisplay(display) };
bail!("XIQueryVersion failed with status {rc}");
}
let base = master_pointer_name(cursor_id);
let device_name = slave_pointer_name(&base);
// Acquire the non-X resource before mutating the XInput hierarchy. The
// inexpensive availability probe above handles the normal permission
// denial; this ordering also prevents a race or late open failure from
// leaking a newly created master pair.
let uinput_device = match create_uinput_pointer(&device_name) {
Ok(device) => device,
Err(error) => {
unsafe { x11::xlib::XCloseDisplay(display) };
return Err(error);
}
};
let mut change = x11::xinput2::XIAnyHierarchyChangeInfo::default();
let name = CString::new(base.clone())?;
unsafe {
let add = change.add();
(*add)._type = x11::xinput2::XIAddMaster;
(*add).name = name.as_ptr() as *mut _;
// Core events stay on so core-only apps (xterm, Tk, …) receive the
// drags too. Note this is not what makes the WM focus the dragged
// window — XI2-aware WMs grab buttons for XIAllMasterDevices — see
// the active-window save/restore in send_parallel_virtual_pointer_drags.
(*add).send_core = 1;
(*add).enable = 1;
}
let rc = unsafe { x11::xinput2::XIChangeHierarchy(display, &mut change, 1) };
unsafe {
x11::xlib::XSync(display, 0);
}
if rc != 0 {
unsafe { x11::xlib::XCloseDisplay(display) };
bail!("XIChangeHierarchy(XIAddMaster) failed with status {rc}");
}
let devices = xi2_query_devices(display)?;
let mut pointer_id = None;
let mut keyboard_id = None;
let pointer_name = master_pointer_device_name(&base);
let keyboard_name = master_keyboard_device_name(&base);
for (device_id, use_, device_name) in devices {
if use_ == x11::xinput2::XIMasterPointer && device_name == pointer_name {
pointer_id = Some(device_id);
} else if use_ == x11::xinput2::XIMasterKeyboard && device_name == keyboard_name {
keyboard_id = Some(device_id);
}
}
let pointer_id = pointer_id
.ok_or_else(|| anyhow!("failed to locate created master pointer for '{cursor_id}'"))?;
let keyboard_id = keyboard_id
.ok_or_else(|| anyhow!("failed to locate created master keyboard for '{cursor_id}'"))?;
let slave_pointer_id = match wait_for_slave_id(
display,
&device_name,
x11::xinput2::XISlavePointer,
Duration::from_secs(5),
) {
Ok(id) => id,
Err(error) => {
// Never leave the fresh master pair behind when the slave never
// hotplugs (no udev/libinput on this server): a stray master with
// nothing attached is exactly the leak the startup reaper exists for.
let _ = remove_master_pointer(display, pointer_id);
unsafe { x11::xlib::XCloseDisplay(display) };
return Err(error);
}
};
attach_slave_to_master(display, slave_pointer_id, pointer_id)?;
set_flat_pointer_accel(display, slave_pointer_id);
unsafe { x11::xlib::XCloseDisplay(display) };
let ids = MasterPointerIds {
pointer_id,
keyboard_id,
_slave_pointer_id: slave_pointer_id,
slave_keyboard_id: None,
};
mpx_pointers()
.lock()
.unwrap()
.insert(cursor_id.to_owned(), ids);
uinput_pointers()
.lock()
.unwrap()
.insert(cursor_id.to_owned(), Arc::new(Mutex::new(uinput_device)));
Ok(ids)
}
pub fn forget_master_pointer(cursor_id: &str) {
let _op = MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
forget_master_pointer_locked(cursor_id);
}
fn forget_master_pointer_locked(cursor_id: &str) {
let mut tracked = mpx_click_popups().lock().unwrap();
let mut last_use = mpx_last_use().lock().unwrap();
match tracked.get_mut(cursor_id) {
Some(popups) if popups.removal_due.is_some() => {}
Some(popups) if !popups.windows.is_empty() => {
let remove_by = *last_use.get(cursor_id).unwrap_or(&Instant::now()) + MPX_IDLE_TTL;
match spawn_popup_waiter(cursor_id.to_owned(), remove_by) {
Ok(_) => {
popups.removal_due = Some(remove_by);
last_use.remove(cursor_id);
}
Err(error) => tracing::warn!(cursor_id, %error, "MPX popup waiter not started"),
}
}
_ => {
tracked.remove(cursor_id);
last_use.remove(cursor_id);
remove_master_pair(cursor_id);
}
}
}
fn popups_mapped(windows: &[u64]) -> Option<bool> {
let (conn, _) = RustConnection::connect(None).ok()?;
let mut mapped = false;
for &window in windows {
match conn.get_window_attributes(window as Window).ok()?.reply() {
Ok(attrs) => mapped |= attrs.map_state == MapState::VIEWABLE,
Err(x11rb::errors::ReplyError::X11Error(_)) => {}
Err(_) => return None,
}
}
Some(mapped)
}
fn popup_wait_over(mapped: Option<bool>, quiet: &mut Option<Instant>, remove_by: Instant) -> bool {
let now = Instant::now();
*quiet = (mapped == Some(false)).then(|| quiet.unwrap_or(now));
quiet.is_some_and(|since| now - since >= MPX_POPUP_QUIET) || now >= remove_by
}
fn spawn_popup_waiter(cursor_id: String, remove_by: Instant) -> Result<()> {
std::thread::Builder::new()
.name("cua-mpx-popup-wait".into())
.spawn(move || {
let mut quiet = None;
loop {
sleep(Duration::from_millis(100));
let _op = MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let mut tracked = mpx_click_popups().lock().unwrap();
let Some(popups) = tracked.get(&cursor_id) else {
return;
};
if popups.removal_due != Some(remove_by) {
return;
}
if popup_wait_over(popups_mapped(&popups.windows), &mut quiet, remove_by) {
tracked.remove(&cursor_id);
return remove_master_pair(&cursor_id);
}
}
})?;
Ok(())
}
fn remove_master_pair(cursor_id: &str) {
// Drop the uinput slaves first: closing the fds unplugs them, so the master
// removal below never has to hand a live slave back to the user's core
// devices (XIAttachToMaster only re-homes slaves that still exist).
uinput_pointers().lock().unwrap().remove(cursor_id);
mpx_keyboard::forget_uinput_keyboard(cursor_id);
let Some(ids) = mpx_pointers().lock().unwrap().remove(cursor_id) else {
return;
};
let Ok(display) = open_display() else {
return;
};
let _ = remove_master_pointer(display, ids.pointer_id);
unsafe { x11::xlib::XCloseDisplay(display) };
}
fn remove_master_pointer(display: *mut x11::xlib::Display, pointer_id: i32) -> Result<()> {
let devices = xi2_query_devices(display)?;
let mut virtual_core_pointer = None;
let mut virtual_core_keyboard = None;
for (device_id, use_, device_name) in devices {
if device_name == "Virtual core pointer" && use_ == x11::xinput2::XIMasterPointer {
virtual_core_pointer = Some(device_id);
} else if device_name == "Virtual core keyboard" && use_ == x11::xinput2::XIMasterKeyboard {
virtual_core_keyboard = Some(device_id);
}
}
let (Some(return_pointer), Some(return_keyboard)) =
(virtual_core_pointer, virtual_core_keyboard)
else {
bail!("cannot remove MPX master without its virtual core return devices");
};
let mut change = x11::xinput2::XIAnyHierarchyChangeInfo::default();
unsafe {
let remove = change.remove();
(*remove)._type = x11::xinput2::XIRemoveMaster;
(*remove).deviceid = pointer_id;
(*remove).return_mode = x11::xinput2::XIAttachToMaster;
(*remove).return_pointer = return_pointer;
(*remove).return_keyboard = return_keyboard;
let rc = x11::xinput2::XIChangeHierarchy(display, &mut change, 1);
x11::xlib::XSync(display, 0);
if rc != 0 {
bail!("XIChangeHierarchy(XIRemoveMaster) failed with status {rc}");
}
}
Ok(())
}
/// Recover only versioned masters whose local owner is provably gone. A PID
/// alone cannot identify an owner on a shared/remote X server or across restarts.
pub(crate) fn reap_orphaned_master_pointers() {
if std::env::var_os("WAYLAND_DISPLAY").is_some() {
return;
}
let Ok(owner) = mpx_owner::Owner::current() else {
return;
};
let Ok(display) = open_display() else {
return;
};
// Prevent an ID from being removed/reused by another X client between our
// enumeration and removal. No network or arbitrary filesystem reads occur
// under this grab: owner checks inspect local procfs and kill(pid, 0).
unsafe {
x11::xlib::XGrabServer(display);
}
// A panic while the server is grabbed would freeze every other X client
// (the whole desktop) until this process dies. Catch it so the ungrab
// below always runs, and report it like any other incomplete recovery.
let result = catch_unwind(AssertUnwindSafe(|| -> Result<()> {
for (id, use_, name) in xi2_query_devices(display)? {
if use_ != x11::xinput2::XIMasterPointer {
continue;
}
let Some(candidate) = mpx_owner::Owner::from_pointer_name(&name) else {
continue;
};
if candidate.stale_in(&owner) {
remove_master_pointer(display, id)?;
tracing::info!(device_id = id, "removed orphaned Cua MPX master pair");
}
}
Ok(())
}));
unsafe {
x11::xlib::XUngrabServer(display);
x11::xlib::XSync(display, 0);
x11::xlib::XCloseDisplay(display);
}
match result {
Ok(Ok(())) => {}
Ok(Err(error)) => tracing::warn!("MPX orphan recovery incomplete: {error}"),
Err(payload) => tracing::warn!(
"MPX orphan recovery panicked (server grab released): {}",
panic_payload_message(payload.as_ref())
),
}
}
fn create_uinput_pointer(name: &str) -> Result<VirtualDevice> {
guarded_uinput_creation(name, |name| {
let mut keys = AttributeSet::<Key>::new();
keys.insert(Key::BTN_LEFT);
keys.insert(Key::BTN_RIGHT);
keys.insert(Key::BTN_MIDDLE);
let mut rel_axes = AttributeSet::<RelativeAxisType>::new();
rel_axes.insert(RelativeAxisType::REL_X);
rel_axes.insert(RelativeAxisType::REL_Y);
// REL_WHEEL (vertical) and REL_HWHEEL (horizontal) so the same uinput
// slave can also drive scroll: libinput turns these into the XI2
// smooth-scroll events GTK consumes, where synthetic Button4-7
// XSendEvents are dropped.
rel_axes.insert(RelativeAxisType::REL_WHEEL);
rel_axes.insert(RelativeAxisType::REL_HWHEEL);
Ok(evdev::uinput::VirtualDeviceBuilder::new()?
.name(name)
.with_keys(&keys)?
.with_relative_axes(&rel_axes)?
.build()?)
})
}
/// Poll `XIQueryDevice` until the X server has hot-added the uinput device
/// named `device_name` as a slave of kind `use_` (`XISlavePointer` /
/// `XISlaveKeyboard`). udev + xf86-input-libinput do the hotplug on a real
/// Xorg; Xvfb/Xtigervnc never will, which is what the timeout covers.
fn wait_for_slave_id(
display: *mut x11::xlib::Display,
device_name: &str,
use_: i32,
timeout: Duration,
) -> Result<i32> {
let deadline = crate::interaction::operation_deadline(timeout);
loop {
for (device_id, seen_use, seen_name) in xi2_query_devices(display)? {
if seen_use == use_ && seen_name == device_name {
return Ok(device_id);
}
}
if std::time::Instant::now() >= deadline {
bail!("timed out waiting for X input slave device '{device_name}'");
}
crate::interaction::pause(Duration::from_millis(50));
}
}
fn attach_slave_to_master(
display: *mut x11::xlib::Display,
slave_pointer_id: i32,
master_pointer_id: i32,
) -> Result<()> {
let mut change = x11::xinput2::XIAnyHierarchyChangeInfo::default();
unsafe {
let attach = change.attach();
(*attach)._type = x11::xinput2::XIAttachSlave;
(*attach).deviceid = slave_pointer_id;
(*attach).new_master = master_pointer_id;
}
let rc = unsafe { x11::xinput2::XIChangeHierarchy(display, &mut change, 1) };
unsafe { x11::xlib::XSync(display, 0) };
if rc != 0 {
bail!("XIChangeHierarchy(XIAttachSlave) failed with status {rc}");
}
Ok(())
}
fn set_flat_pointer_accel(display: *mut x11::xlib::Display, slave_pointer_id: i32) {
// Pin libinput's accel profile to flat so relative deltas map 1:1 onto
// cursor movement — the default adaptive profile rescales small deltas
// and makes drag endpoints drift off-target by a few pixels.
// Best-effort: the property only exists under xf86-input-libinput.
unsafe {
let prop = x11::xlib::XInternAtom(
display,
c"libinput Accel Profile Enabled".as_ptr(),
x11::xlib::True,
);
if prop == 0 {
return;
}
let mut type_ret: x11::xlib::Atom = 0;
let mut format_ret: std::os::raw::c_int = 0;
let mut num_items: std::os::raw::c_ulong = 0;
let mut bytes_after: std::os::raw::c_ulong = 0;
let mut data: *mut std::os::raw::c_uchar = std::ptr::null_mut();
let rc = x11::xinput2::XIGetProperty(
display,
slave_pointer_id,
prop,
0,
16,
x11::xlib::False,
x11::xlib::AnyPropertyType as x11::xlib::Atom,
&mut type_ret,
&mut format_ret,
&mut num_items,
&mut bytes_after,
&mut data,
);
if rc != x11::xlib::Success as i32 || data.is_null() {
return;
}
// Profile order is (adaptive, flat[, custom]); enable flat only.
if format_ret == 8 && (2..=8).contains(&num_items) {
let mut values = vec![0u8; num_items as usize];
values[1] = 1;
x11::xinput2::XIChangeProperty(
display,
slave_pointer_id,
prop,
type_ret,
8,
x11::xlib::PropModeReplace,
values.as_mut_ptr(),
num_items as std::os::raw::c_int,
);
x11::xlib::XSync(display, 0);
}
x11::xlib::XFree(data as *mut _);
}
}
fn warp_master_pointer(
display: *mut x11::xlib::Display,
ids: MasterPointerIds,
x: i32,
y: i32,
) -> Result<()> {
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
let rc = unsafe {
x11::xinput2::XIWarpPointer(
display,
ids.pointer_id,
0,
root,
0.0,
0.0,
0,
0,
x as f64,
y as f64,
)
};
// XSync (not XFlush): the button press that follows is emitted through
// uinput on a separate kernel pipeline, and races ahead of a merely
// queued warp request. Once XSync returns the server has executed the
// warp, so the press lands at the warped position.
unsafe { x11::xlib::XSync(display, 0) };
if rc != 0 {
bail!("XIWarpPointer failed with status {rc}");
}
Ok(())
}
/// True when `window` is override-redirect — a menu, tooltip, or other popup
/// the WM does not manage. Such a window takes its own active pointer grab, so
/// the shield-grab-and-replay dance cannot deliver into it; a plain warp+press
/// on the virtual master is what reaches it (and there is no WM focus to steal).
fn is_override_redirect(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> bool {
let mut attrs: x11::xlib::XWindowAttributes = unsafe { std::mem::zeroed() };
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe { x11::xlib::XGetWindowAttributes(display, window, &mut attrs) };
unsafe { x11::xlib::XSetErrorHandler(previous_handler) };
rc != 0 && attrs.override_redirect != 0
}
/// Direct child of the root window under screen point `(x, y)`: the WM frame
/// of a managed toplevel, or an override-redirect popup (menu, tooltip).
fn root_child_under_point(
display: *mut x11::xlib::Display,
x: i32,
y: i32,
) -> Option<x11::xlib::Window> {
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
let mut child: x11::xlib::Window = 0;
let mut dx = 0;
let mut dy = 0;
let rc = unsafe {
x11::xlib::XTranslateCoordinates(display, root, root, x, y, &mut dx, &mut dy, &mut child)
};
(rc != 0 && child != 0).then_some(child)
}
/// The root child (WM frame or the window itself) that contains `window`.
fn root_child_of(
display: *mut x11::xlib::Display,
window: x11::xlib::Window,
) -> Option<x11::xlib::Window> {
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let mut current = window;
let mut result = None;
for _ in 0..64 {
let mut root_ret: x11::xlib::Window = 0;
let mut parent: x11::xlib::Window = 0;
let mut children: *mut x11::xlib::Window = ptr::null_mut();
let mut count: std::os::raw::c_uint = 0;
let rc = unsafe {
x11::xlib::XQueryTree(
display,
current,
&mut root_ret,
&mut parent,
&mut children,
&mut count,
)
};
if !children.is_null() {
unsafe { x11::xlib::XFree(children as *mut _) };
}
if rc == 0 || parent == 0 {
break;
}
if parent == root {
result = Some(current);
break;
}
current = parent;
}
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
result
}
pub(super) fn xi_mask_len() -> usize {
(x11::xinput2::XI_LASTEVENT as usize >> 3) + 1
}
/// Look up the XInputExtension major opcode so we can recognise its
/// GenericEvent cookies on the display connection.
fn xinput_opcode(display: *mut x11::xlib::Display) -> Option<std::os::raw::c_int> {
let name = match CString::new("XInputExtension") {
Ok(n) => n,
Err(_) => return None,
};
let mut opcode = 0;
let mut event = 0;
let mut error = 0;
let present = unsafe {
x11::xlib::XQueryExtension(display, name.as_ptr(), &mut opcode, &mut event, &mut error)
};
if present != 0 {
Some(opcode)
} else {
None
}
}
/// Modifier evdev codes the virtual keyboard may hold mid-chord.
const MODIFIER_EVDEV_CODES: [u16; 8] = [42, 54, 29, 97, 56, 100, 125, 126];
/// Buttons (1..=3) currently held on the master pointer `pointer_id`, plus the
/// paired master keyboard's modifier state, via `XIQueryPointer`.
fn virtual_master_input_state(
display: *mut x11::xlib::Display,
pointer_id: i32,
) -> (Vec<u8>, x11::xinput2::XIModifierState) {
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
let mut root_ret = 0;
let mut child_ret = 0;
let (mut rx, mut ry, mut wx, mut wy) = (0f64, 0f64, 0f64, 0f64);
let mut buttons = x11::xinput2::XIButtonState::default();
let mut mods = x11::xinput2::XIModifierState::default();
let mut group = x11::xinput2::XIModifierState::default();
let prev = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe {
x11::xinput2::XIQueryPointer(
display,
pointer_id,
root,
&mut root_ret,
&mut child_ret,
&mut rx,
&mut ry,
&mut wx,
&mut wy,
&mut buttons,
&mut mods,
&mut group,
)
};
unsafe { x11::xlib::XSetErrorHandler(prev) };
let mut held = Vec::new();
if rc != 0 && !buttons.mask.is_null() && buttons.mask_len > 0 {
let mask = unsafe { std::slice::from_raw_parts(buttons.mask, buttons.mask_len as usize) };
for button in 1u8..=3 {
let byte = (button / 8) as usize;
if mask.get(byte).is_some_and(|b| b & (1 << (button % 8)) != 0) {
held.push(button);
}
}
unsafe { x11::xlib::XFree(buttons.mask as *mut _) };
}
(held, mods)
}
/// Release anything the session's virtual master still holds from an earlier
/// aborted action: pointer buttons (a shield replay that timed out returned
/// before the release) and keyboard modifiers (a chord interrupted mid-way).
///
/// A held button is not cosmetic: every key event from the paired virtual
/// keyboard then carries `Button1Mask` (bit 8) in its core `state`, which
/// at-spi2 forwards verbatim and Orca reads as its `ORCA_MODIFIER_MASK`
/// (`1 << 8`) — a plain space becomes "Orca+space" and opens the Screen
/// Reader Preferences. Returns what was released, for the tool's report.
fn release_stuck_virtual_input(
cursor_id: &str,
display: *mut x11::xlib::Display,
ids: MasterPointerIds,
keyboard: &Mutex<VirtualDevice>,
) -> Vec<String> {
let mut released = Vec::new();
let (held, mods) = virtual_master_input_state(display, ids.pointer_id);
if !held.is_empty() {
if let Some(pointer) = uinput_pointers().lock().unwrap().get(cursor_id).cloned() {
let mut pointer = pointer.lock().unwrap();
for &button in &held {
if emit_button(&mut pointer, button, false).is_ok() {
released.push(format!("button{button}"));
}
}
}
}
if mods.base != 0 {
let mut keyboard = keyboard.lock().unwrap();
let mut any = false;
for code in MODIFIER_EVDEV_CODES {
any |= keyboard
.emit(&[InputEvent::new(EventType::KEY, code, 0)])
.is_ok();
}
if any {
released.push(format!("modifiers(base=0x{:x})", mods.base));
}
}
if mods.locked != 0 || mods.latched != 0 {
// A locked/latched modifier on the virtual master (CapsLock leaked
// from an interrupted chord) would shift every later character.
unsafe {
let prev = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
x11::xlib::XkbLockModifiers(display, ids.keyboard_id as u32, 0xff, 0);
x11::xlib::XkbLatchModifiers(display, ids.keyboard_id as u32, 0xff, 0);
x11::xlib::XSetErrorHandler(prev);
}
released.push(format!(
"locked/latched modifiers (0x{:x}/0x{:x})",
mods.locked, mods.latched
));
}
if !released.is_empty() {
unsafe { x11::xlib::XSync(display, 0) };
tracing::warn!(cursor_id, ?released, "released stuck virtual input state");
sleep(Duration::from_millis(20));
}
released
}
/// Release a device frozen by a synchronous grab; harmless when not frozen.
fn thaw_device(display: *mut x11::xlib::Display, device_id: i32) {
unsafe {
let prev = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
x11::xinput2::XIAllowEvents(
display,
device_id,
x11::xinput2::XIAsyncDevice,
x11::xlib::CurrentTime,
);
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(prev);
}
}
fn ewmh_active_window(display: *mut x11::xlib::Display) -> Option<x11::xlib::Window> {
unsafe {
let atom = x11::xlib::XInternAtom(display, c"_NET_ACTIVE_WINDOW".as_ptr(), x11::xlib::True);
if atom == 0 {
return None;
}
let root = x11::xlib::XDefaultRootWindow(display);
let mut type_ret: x11::xlib::Atom = 0;
let mut format_ret: std::os::raw::c_int = 0;
let mut nitems: std::os::raw::c_ulong = 0;
let mut bytes_after: std::os::raw::c_ulong = 0;
let mut data: *mut std::os::raw::c_uchar = std::ptr::null_mut();
let rc = x11::xlib::XGetWindowProperty(
display,
root,
atom,
0,
1,
x11::xlib::False,
x11::xlib::XA_WINDOW,
&mut type_ret,
&mut format_ret,
&mut nitems,
&mut bytes_after,
&mut data,
);
if rc != x11::xlib::Success as i32 || data.is_null() {
return None;
}
let window = if nitems >= 1 && format_ret == 32 {
Some(*(data as *const std::os::raw::c_ulong) as x11::xlib::Window)
} else {
None
};
x11::xlib::XFree(data as *mut _);
window.filter(|w| *w != 0)
}
}
/// Current X server time via the standard PropertyNotify round-trip.
/// EWMH activation requests stamped CurrentTime(0) lose to the WM's
/// focus-stealing prevention whenever any newer input exists.
fn x_server_time(display: *mut x11::xlib::Display) -> x11::xlib::Time {
unsafe {
let root = x11::xlib::XDefaultRootWindow(display);
let win = x11::xlib::XCreateSimpleWindow(display, root, -1, -1, 1, 1, 0, 0, 0);
x11::xlib::XSelectInput(display, win, x11::xlib::PropertyChangeMask);
let atom = x11::xlib::XInternAtom(display, c"CUA_TIME_PROBE".as_ptr(), x11::xlib::False);
x11::xlib::XChangeProperty(
display,
win,
atom,
x11::xlib::XA_STRING,
8,
x11::xlib::PropModeReplace,
[0u8].as_ptr(),
0,
);
x11::xlib::XSync(display, 0);
let mut time: x11::xlib::Time = x11::xlib::CurrentTime;
let mut ev: x11::xlib::XEvent = std::mem::zeroed();
while x11::xlib::XCheckWindowEvent(display, win, x11::xlib::PropertyChangeMask, &mut ev)
!= 0
{
if ev.get_type() == x11::xlib::PropertyNotify {
time = ev.property.time;
}
}
x11::xlib::XDestroyWindow(display, win);
x11::xlib::XFlush(display);
time
}
}
fn ewmh_activate_window(
display: *mut x11::xlib::Display,
window: x11::xlib::Window,
current_active: x11::xlib::Window,
) {
unsafe {
let atom = x11::xlib::XInternAtom(display, c"_NET_ACTIVE_WINDOW".as_ptr(), x11::xlib::True);
if atom == 0 {
return;
}
let root = x11::xlib::XDefaultRootWindow(display);
let mut ev: x11::xlib::XClientMessageEvent = std::mem::zeroed();
ev.type_ = x11::xlib::ClientMessage;
ev.window = window;
ev.message_type = atom;
ev.format = 32;
ev.data.set_long(0, 2); // source indication: pager/tool
ev.data
.set_long(1, x_server_time(display) as std::os::raw::c_long);
ev.data.set_long(2, current_active as std::os::raw::c_long);
x11::xlib::XSendEvent(
display,
root,
x11::xlib::False,
x11::xlib::SubstructureRedirectMask | x11::xlib::SubstructureNotifyMask,
&mut ev as *mut _ as *mut x11::xlib::XEvent,
);
x11::xlib::XSync(display, 0);
}
}
/// Activate `xid` and LEAVE it active (no restore) — the persistent foreground
/// swap behind `bring_to_front`. Returns the window that was active before, so
/// the caller can report/inspect it. Best-effort; returns `None` prior on a
/// headless display.
pub fn x11_activate_window_persistent(xid: u64) -> Result<Option<u64>> {
// Called directly from the tool layer (bring_to_front / foreground
// activation), not through `send_virtual_pointer_*`/`deliver`, so without
// this guard its `XSetErrorHandler` swap below can race theirs: whichever
// thread restores its saved "previous" handler last can clobber the
// other's still-in-flight `ignore_x_error` installation, briefly leaving
// the process default handler active (which can abort the process on an
// unrelated async X11 error) — or vice versa. `MPX_OP_LOCK` is a leaf
// lock here (this function calls nothing that itself takes it), so no
// reentrancy risk.
let _op = mpx_op_guard("x11_activate_window_persistent");
let display = unsafe { x11::xlib::XOpenDisplay(ptr::null()) };
if display.is_null() {
bail!(
"cannot activate window: no X display (DISPLAY={:?})",
std::env::var("DISPLAY").ok()
);
}
let prior = ewmh_active_window(display);
ewmh_activate_window(
display,
xid as x11::xlib::Window,
prior.unwrap_or(0) as x11::xlib::Window,
);
unsafe {
// Some WMs honor `_NET_ACTIVE_WINDOW` as raise-only. Persistent
// activation must establish input focus too, just like the bounded
// foreground rung above, or `bring_to_front` can report success while
// keyboard focus remains on the previous window.
let previous_handler = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
x11::xlib::XSetInputFocus(
display,
xid as x11::xlib::Window,
x11::xlib::RevertToParent,
x11::xlib::CurrentTime,
);
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
x11::xlib::XCloseDisplay(display);
}
Ok(prior)
}
fn button_code(button: u8) -> Result<Key> {
match button {
1 => Ok(Key::BTN_LEFT),
2 => Ok(Key::BTN_MIDDLE),
3 => Ok(Key::BTN_RIGHT),
_ => bail!("unsupported button {button} for uinput pointer"),
}
}
fn emit_button(device: &mut VirtualDevice, button: u8, press: bool) -> Result<()> {
let code = button_code(button)?;
device.emit(&[InputEvent::new(
EventType::KEY,
code.0,
if press { 1 } else { 0 },
)])?;
Ok(())
}
/// Emit a release for `button` regardless of state; the kernel drops a
/// release for a button that is not held, so this is safe to call on every
/// exit path of a press train or gesture.
fn release_button_best_effort(device: &Arc<Mutex<VirtualDevice>>, button: u8) {
if let Ok(mut device) = device.lock() {
if let Err(error) = emit_button(&mut device, button, false) {
tracing::warn!("virtual pointer button {button} release failed: {error:#}");
}
}
}
fn emit_relative_motion(device: &mut VirtualDevice, dx: i32, dy: i32) -> Result<()> {
let mut events = Vec::with_capacity(2);
if dx != 0 {
events.push(InputEvent::new(
EventType::RELATIVE,
RelativeAxisType::REL_X.0,
dx,
));
}
if dy != 0 {
events.push(InputEvent::new(
EventType::RELATIVE,
RelativeAxisType::REL_Y.0,
dy,
));
}
if events.is_empty() {
return Ok(());
}
device.emit(&events)?;
Ok(())
}
/// Emit one wheel detent on the uinput slave. `horizontal` selects REL_HWHEEL
/// (positive = right) over REL_WHEEL (positive = up); `value` is the signed
/// detent count. libinput translates these into the XI2 scroll events GTK reads.
fn emit_scroll(device: &mut VirtualDevice, horizontal: bool, value: i32) -> Result<()> {
let axis = if horizontal {
RelativeAxisType::REL_HWHEEL
} else {
RelativeAxisType::REL_WHEEL
};
device.emit(&[InputEvent::new(EventType::RELATIVE, axis.0, value)])?;
Ok(())
}
pub fn send_parallel_virtual_pointer_drags(drags: &[(String, VirtualPointerDrag)]) -> Result<()> {
let _op = mpx_op_guard(
drags
.first()
.map(|(id, _)| id.as_str())
.unwrap_or("default"),
);
for (cursor_id, _) in drags {
mark_mpx_use(cursor_id);
}
let display = open_display()?;
supports_parallel_pointer_injection(display)?;
struct ActiveDrag {
cursor_id: String,
ids: MasterPointerIds,
device: Arc<Mutex<VirtualDevice>>,
drag: VirtualPointerDrag,
cum: Vec<f64>,
total: f64,
steps: usize,
step_delay: Duration,
current_step: usize,
next_at: std::time::Instant,
last_x: i32,
last_y: i32,
}
let start_at = std::time::Instant::now() + Duration::from_millis(120);
let mut active = Vec::with_capacity(drags.len());
// A click-to-focus WM that grabs buttons for every master device would
// activate the target on the press. Remember the focus state and hand it
// back afterwards so parallel drags don't steal it (mutter grabs for the
// Virtual Core Pointer only, so there the restore is a no-op).
let saved_focus = save_focus_state(display);
let result = (|| -> Result<()> {
for (cursor_id, drag) in drags {
let ids = ensure_master_pointer(cursor_id)?;
let device = uinput_pointers()
.lock()
.unwrap()
.get(cursor_id)
.cloned()
.ok_or_else(|| anyhow!("missing uinput pointer for '{cursor_id}'"))?;
let (cum, total) = path_cumulative(&drag.path);
let start = *drag.path.first().unwrap_or(&(0, 0));
active.push(ActiveDrag {
cursor_id: cursor_id.clone(),
ids,
device,
drag: drag.clone(),
cum,
total,
steps: drag.steps.max(1),
step_delay: if drag.steps.max(1) > 1 {
Duration::from_millis(drag.duration_ms / drag.steps.max(1) as u64)
} else {
Duration::from_millis(drag.duration_ms)
},
current_step: 0,
next_at: start_at,
last_x: start.0,
last_y: start.1,
});
}
let now = std::time::Instant::now();
if start_at > now {
crate::interaction::pause(start_at - now);
}
// Press each drag straight from its virtual master (see
// `send_virtual_pointer_click` for why there is no XI2 shield grab:
// on this server the grab-and-replay swallowed the press). The press
// point must not be covered by another toplevel.
for item in &active {
let start = *item.drag.path.first().unwrap_or(&(0, 0));
if let PointCover::Occluded(occluded) = occluding_window(
display,
item.drag.target_window as x11::xlib::Window,
start.0,
start.1,
)? {
return Err(occluded.into());
}
thaw_device(display, item.ids.pointer_id);
warp_master_pointer(display, item.ids, start.0, start.1)?;
{
let mut device = item.device.lock().unwrap();
emit_button(&mut device, item.drag.button, true)?;
}
}
crate::interaction::pause(Duration::from_millis(40));
while active.iter().any(|item| item.current_step < item.steps) {
let now = std::time::Instant::now();
let mut advanced = false;
let mut next_deadline = None;
for item in &mut active {
if item.current_step >= item.steps {
continue;
}
if now >= item.next_at {
item.current_step += 1;
let t = item.current_step as f64 / item.steps as f64;
let (ix, iy) = point_on_path(&item.drag.path, &item.cum, item.total, t);
let dx = ix - item.last_x;
let dy = iy - item.last_y;
if dx != 0 || dy != 0 {
let mut device = item.device.lock().unwrap();
emit_relative_motion(&mut device, dx, dy)?;
// Keep the agent cursor overlay tracking the drag so
// the gesture is visible, not just its endpoints.
crate::overlay::send_command_for(
item.cursor_id.clone(),
cursor_overlay::OverlayCommand::SnapTo {
x: ix as f64,
y: iy as f64,
heading_radians: Some((dy as f64).atan2(dx as f64)),
},
);
}
item.last_x = ix;
item.last_y = iy;
item.next_at = now + item.step_delay;
advanced = true;
}
if item.current_step < item.steps {
next_deadline = Some(match next_deadline {
Some(deadline) => std::cmp::min(deadline, item.next_at),
None => item.next_at,
});
}
}
if !advanced {
if let Some(deadline) = next_deadline {
let now = std::time::Instant::now();
if deadline > now {
crate::interaction::pause(deadline - now);
}
}
}
}
for item in &active {
let mut device = item.device.lock().unwrap();
emit_button(&mut device, item.drag.button, false)?;
}
Ok(())
})();
// Whatever happened above, no virtual master may keep a button held
// (a stuck Button1 poisons the core modifier state for later chords).
for (cursor_id, drag) in drags {
if let Some(device) = uinput_pointers().lock().unwrap().get(cursor_id).cloned() {
release_button_best_effort(&device, drag.button);
}
}
// The per-session master pair is retained for reuse (torn down on
// end_session / idle / startup reap). Creating and destroying an XI2 master
// plus hot-plugging a uinput slave on every call churns the XInput
// hierarchy hard enough to crash fragile toolkits (LibreOffice VCL); one
// long-lived pair per session avoids that and is cheaper. The focus is
// still saved and restored around each gesture.
let _ = drags;
restore_focus_state(display, &saved_focus);
unsafe {
x11::xlib::XCloseDisplay(display);
}
result
}
/// A discrete no-focus-steal pointer click driven through the same real-input
/// pipeline as [`send_parallel_virtual_pointer_drags`] — MPX master pointer +
/// uinput slave — reduced to a press/release (or a short press/release train
/// for `count` > 1) at one screen point.
///
/// This is what lands **right / middle / double** clicks (and any left click
/// the AT-SPI path can't actuate) on XInput2 toolkits: GTK3/4, VCL, Qt and
/// Chromium silently drop synthetic `XSendEvent` pointer events, so those
/// clicks are otherwise no-ops. Coordinates are screen-absolute;
/// `target_window` is the X11 toplevel the caller means to hit. The press is
/// delivered straight from the virtual master: no XI2 shield grab. On GNOME
/// (mutter) the click-to-focus passive grab is installed for the Virtual Core
/// Pointer only, so a second master's press never activates the window; the
/// grab-and-replay "shield" that was meant to hide the press from the WM
/// instead swallowed it on this server (the replayed press never reached the
/// application) and left the device frozen. Focus is still saved and restored
/// around the click for WMs that do grab every master device. `button` is an
/// X button number (1=left, 2=middle, 3=right); `count` >= 1 (2 = double-click).
#[derive(Clone, Debug)]
pub struct VirtualPointerClick {
pub target_window: u64,
pub x: i32,
pub y: i32,
pub button: u8,
pub count: usize,
}
/// The screen point the caller aimed at is covered by another toplevel, so a
/// real pointer press there would land on the covering window, not the
/// target. Refused before any input is sent.
#[derive(Debug, Clone)]
pub struct TargetOccluded {
pub target_window: u64,
pub covering_window: u64,
pub covering_title: String,
pub covering_pid: Option<u32>,
pub x: i32,
pub y: i32,
}
impl std::fmt::Display for TargetOccluded {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"screen point ({}, {}) over window {} is covered by window {}{}{}; a real pointer \
press there would land on the covering window",
self.x,
self.y,
self.target_window,
self.covering_window,
if self.covering_title.is_empty() {
String::new()
} else {
format!(" \"{}\"", self.covering_title)
},
self.covering_pid
.map(|pid| format!(" (pid {pid})"))
.unwrap_or_default(),
)
}
}
impl std::error::Error for TargetOccluded {}
/// A mapped override-redirect toplevel: a popup menu, popover, combo list
/// or tooltip. The WM does not manage it, so it is absent from
/// `list_windows`; the pointer tools name it so a caller can walk it with
/// `get_window_state(pid, window_id=<window>)`.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct PopupWindow {
pub window: u64,
pub x: i32,
pub y: i32,
pub width: u32,
pub height: u32,
pub title: String,
pub pid: Option<u32>,
}
impl PopupWindow {
pub fn to_json(&self) -> serde_json::Value {
serde_json::json!({
"window_id": self.window,
"bounds": { "x": self.x, "y": self.y, "width": self.width, "height": self.height },
"title": self.title,
"pid": self.pid,
})
}
/// `popup window 12345678 "Edit" (220x340 at 410,220)`.
pub fn describe(&self) -> String {
format!(
"popup window {}{} ({}x{} at {},{})",
self.window,
if self.title.is_empty() {
String::new()
} else {
format!(" \"{}\"", self.title)
},
self.width,
self.height,
self.x,
self.y
)
}
}
/// The caller's window-local point does not lie inside the window: a
/// coordinate-frame mistake (screen pixels passed as window pixels, or the
/// wrong window_id), refused before any input is sent.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PointOutsideWindow {
pub target_window: u64,
pub screen_x: i32,
pub screen_y: i32,
pub window_x: i32,
pub window_y: i32,
/// Screen-space `(x, y, width, height)` of the window.
pub bounds: (i32, i32, u32, u32),
}
impl std::fmt::Display for PointOutsideWindow {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let (bx, by, bw, bh) = self.bounds;
write!(
f,
"window-local point ({}, {}) of window {} resolves to screen ({}, {}), outside \
the window's bounds (x={bx}, y={by}, {bw}x{bh}); no input was sent",
self.window_x, self.window_y, self.target_window, self.screen_x, self.screen_y
)
}
}
impl std::error::Error for PointOutsideWindow {}
/// Screen-space `(x, y, width, height)` of `window`, or `None` when it is
/// gone.
fn window_screen_bounds(
display: *mut x11::xlib::Display,
window: x11::xlib::Window,
) -> Option<(i32, i32, u32, u32)> {
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let mut root: x11::xlib::Window = 0;
let (mut gx, mut gy) = (0i32, 0i32);
let (mut width, mut height, mut border, mut depth) = (0u32, 0u32, 0u32, 0u32);
let rc = unsafe {
x11::xlib::XGetGeometry(
display,
window,
&mut root,
&mut gx,
&mut gy,
&mut width,
&mut height,
&mut border,
&mut depth,
)
};
let mut result = None;
if rc != 0 && root != 0 {
let (mut dx, mut dy) = (0i32, 0i32);
let mut child: x11::xlib::Window = 0;
let ok = unsafe {
x11::xlib::XTranslateCoordinates(
display, window, root, 0, 0, &mut dx, &mut dy, &mut child,
)
};
if ok != 0 {
result = Some((dx, dy, width, height));
}
}
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
result
}
fn bounds_contain(bounds: (i32, i32, u32, u32), x: i32, y: i32) -> bool {
let (bx, by, bw, bh) = bounds;
x >= bx && y >= by && x < bx.saturating_add(bw as i32) && y < by.saturating_add(bh as i32)
}
/// Describe a mapped override-redirect root child as a [`PopupWindow`].
fn popup_info(display: *mut x11::xlib::Display, child: x11::xlib::Window) -> Option<PopupWindow> {
let mut attrs: x11::xlib::XWindowAttributes = unsafe { std::mem::zeroed() };
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe { x11::xlib::XGetWindowAttributes(display, child, &mut attrs) };
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
if rc == 0 || attrs.override_redirect == 0 || attrs.map_state != x11::xlib::IsViewable {
return None;
}
if attrs.width <= 1 || attrs.height <= 1 {
return None;
}
let pid = window_or_child_pid(display, child);
Some(PopupWindow {
window: child,
x: attrs.x,
y: attrs.y,
width: attrs.width as u32,
height: attrs.height as u32,
title: window_title_for_report(display, child),
pid,
})
}
fn window_or_child_pid(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> Option<u32> {
crate::x11::window_pid(window).or_else(|| {
window_children(display, window)
.into_iter()
.find_map(crate::x11::window_pid)
})
}
/// Every mapped override-redirect child of the root, bottom to top.
fn mapped_popups(display: *mut x11::xlib::Display) -> Vec<PopupWindow> {
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
window_children(display, root)
.into_iter()
.filter_map(|child| popup_info(display, child))
.collect()
}
/// The mapped override-redirect popup (menu, popover, combo list) under the
/// screen point, if any.
pub fn popup_under_screen_point(x: i32, y: i32) -> Option<PopupWindow> {
let display = open_display().ok()?;
let popup = root_child_under_point(display, x, y).and_then(|child| popup_info(display, child));
unsafe {
x11::xlib::XCloseDisplay(display);
}
popup
}
/// `xid` described as a popup when it is a mapped override-redirect window.
pub fn popup_window_info(xid: u64) -> Option<PopupWindow> {
let display = open_display().ok()?;
let popup = popup_info(display, xid as x11::xlib::Window);
unsafe {
x11::xlib::XCloseDisplay(display);
}
popup
}
/// Mapped popups on the screen right now (bottom to top), for a caller that
/// wants "the menu that is open" without a window id.
pub fn mapped_popup_windows() -> Vec<PopupWindow> {
let Ok(display) = open_display() else {
return Vec::new();
};
let popups = mapped_popups(display);
unsafe {
x11::xlib::XCloseDisplay(display);
}
popups
}
/// `_NET_WM_WINDOW_TYPE` says the popup is a tooltip / notification / DND
/// icon: mapped and override-redirect, but nobody's grab.
fn popup_is_passive(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> bool {
let type_atom = intern_atom(display, "_NET_WM_WINDOW_TYPE");
let passive: Vec<x11::xlib::Atom> = [
"_NET_WM_WINDOW_TYPE_TOOLTIP",
"_NET_WM_WINDOW_TYPE_NOTIFICATION",
"_NET_WM_WINDOW_TYPE_DND",
]
.iter()
.map(|name| intern_atom(display, name))
.collect();
let mut actual_type: x11::xlib::Atom = 0;
let mut actual_format: std::os::raw::c_int = 0;
let mut nitems: std::os::raw::c_ulong = 0;
let mut bytes_after: std::os::raw::c_ulong = 0;
let mut prop: *mut std::os::raw::c_uchar = ptr::null_mut();
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe {
x11::xlib::XGetWindowProperty(
display,
window,
type_atom,
0,
8,
0,
x11::xlib::XA_ATOM,
&mut actual_type,
&mut actual_format,
&mut nitems,
&mut bytes_after,
&mut prop,
)
};
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
let mut result = false;
if rc == 0 && !prop.is_null() {
if actual_format == 32 && nitems > 0 {
let atoms = unsafe {
std::slice::from_raw_parts(prop as *const std::os::raw::c_ulong, nitems as usize)
};
result = atoms
.iter()
.any(|atom| passive.contains(&(*atom as x11::xlib::Atom)));
}
unsafe { x11::xlib::XFree(prop as *mut _) };
}
result
}
fn intern_atom(display: *mut x11::xlib::Display, name: &str) -> x11::xlib::Atom {
let cname = CString::new(name).unwrap_or_default();
unsafe { x11::xlib::XInternAtom(display, cname.as_ptr(), 0) }
}
/// The topmost mapped override-redirect popup that `pid` owns (a Qt combo
/// list or completer, a GTK/VCL menu) — the toolkit behind it holds an
/// active keyboard grab that makes the X server drop core key events from
/// any *other* master keyboard aimed at that client (`IsInterferingGrab`),
/// so the virtual master keyboard route is silently lost while it is up.
/// Tooltips / notifications are not grabs and do not count.
pub fn popup_of_pid(pid: u32) -> Option<PopupWindow> {
let display = open_display().ok()?;
let popup = mapped_popups(display)
.into_iter()
.rev()
.filter(|popup| popup.pid == Some(pid))
.find(|popup| !popup_is_passive(display, popup.window as x11::xlib::Window));
unsafe {
x11::xlib::XCloseDisplay(display);
}
popup
}
/// `_NET_WM_PID` of the window holding the core keyboard focus, walking up
/// its X parents (the focus often sits on a child of the client toplevel).
pub fn core_focus_owner_pid() -> Option<u32> {
let display = open_display().ok()?;
let mut focus: x11::xlib::Window = 0;
let mut revert: std::os::raw::c_int = 0;
unsafe { x11::xlib::XGetInputFocus(display, &mut focus, &mut revert) };
let root = unsafe { x11::xlib::XDefaultRootWindow(display) };
let mut owner = None;
let mut current = focus;
for _ in 0..8 {
if current == 0 || current == root || current == x11::xlib::PointerRoot as x11::xlib::Window
{
break;
}
if let Some(pid) = crate::x11::window_pid(current as u64) {
owner = Some(pid);
break;
}
let mut parent: x11::xlib::Window = 0;
let mut qroot: x11::xlib::Window = 0;
let mut children: *mut x11::xlib::Window = ptr::null_mut();
let mut n: std::os::raw::c_uint = 0;
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe {
x11::xlib::XQueryTree(
display,
current,
&mut qroot,
&mut parent,
&mut children,
&mut n,
)
};
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
if !children.is_null() {
unsafe { x11::xlib::XFree(children as *mut _) };
}
if rc == 0 || parent == current {
break;
}
current = parent;
}
unsafe {
x11::xlib::XCloseDisplay(display);
}
owner
}
/// Delivery path name for keys sent on the core keyboard while the target's
/// own popup holds the keyboard grab.
pub const XTEST_CORE_GRAB_PATH: &str = "xtest_core_grab";
/// A popup of the target pid holds the keyboard grab and the core focus is
/// not the target's, so no route reaches the target without stealing input
/// from the focused application; refused before any key was sent.
#[derive(Debug, Clone)]
pub struct PopupKeyboardGrab {
pub pid: u32,
pub popup: PopupWindow,
pub focus_owner: Option<u32>,
}
impl std::fmt::Display for PopupKeyboardGrab {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"pid {} has {} open, which holds a keyboard grab that drops keys from the virtual \
keyboard, and the core focus belongs to {}; no key was sent",
self.pid,
self.popup.describe(),
match self.focus_owner {
Some(pid) => format!("pid {pid}"),
None => "no window".to_owned(),
}
)
}
}
impl std::error::Error for PopupKeyboardGrab {}
/// Keys for a target whose own popup (`popup`) holds the keyboard grab: the
/// X server routes the *core* keyboard to the grab holder, which is the
/// target itself, so XTest on the core keyboard reaches it without any
/// focus change — verified afterwards on the core focus and the active
/// window. Refused (`PopupKeyboardGrab`) when the core focus belongs to
/// another pid: then a missing grab would send the keys elsewhere.
pub fn send_keys_under_popup_grab(
pid: u32,
popup: PopupWindow,
send: impl FnOnce() -> Result<()>,
) -> Result<KeyboardDeliveryReport> {
let focus_owner = core_focus_owner_pid();
if focus_owner != Some(pid) {
return Err(PopupKeyboardGrab {
pid,
popup,
focus_owner,
}
.into());
}
let display = open_display()?;
let saved = save_focus_state(display);
let sent = send();
unsafe { x11::xlib::XSync(display, 0) };
let unchanged = focus_state_unchanged(display, &saved);
unsafe {
x11::xlib::XCloseDisplay(display);
}
sent?;
Ok(KeyboardDeliveryReport {
virtual_focus_held: true,
core_focus_unchanged: unchanged,
delivery_confirmed: true,
key_events: 0,
skipped_characters: Vec::new(),
focus_guard: None,
released_stuck: Vec::new(),
path: XTEST_CORE_GRAB_PATH,
grab_popup: Some(popup),
})
}
/// Cheap post-checks a real-pointer action can make without touching the
/// application: whether the WM's active window / core focus stayed put, and
/// whether the screen region around the action point changed.
#[derive(Clone, Debug, Default)]
pub struct PointerEffect {
/// `_NET_ACTIVE_WINDOW` and the core input focus were the same after the
/// action as before it (sampled before the safety-net restore).
pub focus_unchanged: bool,
/// Percentage of pixels (0..100) that changed in a bounded region around
/// the action point, comparing right before the press with ~250 ms after
/// the release; `None` when the capture failed.
pub region_diff_pct: Option<f64>,
/// Real screen point the pointer acted at.
pub x: i32,
pub y: i32,
/// Mapped override-redirect toplevels (menus, popovers, combo lists,
/// tooltips) that appeared between the press and the post-check. A
/// context menu opening is a window change the contract accepts as
/// evidence of a landed click.
pub popups_appeared: usize,
/// Background focus-guard outcome when the tool ran the action under
/// [`focus_guard`]: whether the application moved the desktop focus after
/// the press (a menu grab, a dialog) and whether it was restored.
pub focus_guard: Option<FocusGuardReport>,
/// The point was under another window of the target's own pid (its
/// dialog over its main window) and the press went to that window.
pub retargeted_to: Option<SameAppCover>,
/// The popups behind `popups_appeared`, so the tool can name them.
pub popups: Vec<PopupWindow>,
/// The window-local point the caller asked for, when it had one.
pub window_point: Option<(i32, i32)>,
/// A toplevel of ANOTHER pid under the action point (a drop target, the
/// window a drag ended on): what it did during the action.
pub foreign_window: Option<ForeignWindowEffect>,
}
/// What a toplevel of another pid under the action point did during the
/// action: its title before/after and the windows its pid mapped meanwhile.
/// The focus guard only watches the target pid, so a file dropped onto VLC
/// (auto-played, title changed) would otherwise be invisible.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ForeignWindowEffect {
pub window: u64,
pub pid: u32,
pub title_before: String,
pub title_after: String,
pub new_windows: Vec<(u64, String)>,
}
impl ForeignWindowEffect {
pub fn changed(&self) -> bool {
self.title_before != self.title_after || !self.new_windows.is_empty()
}
pub fn to_json(&self) -> serde_json::Value {
serde_json::json!({
"window_id": self.window,
"pid": self.pid,
"title_before": self.title_before,
"title_after": self.title_after,
"new_windows": self.new_windows.iter().map(|(id, title)| serde_json::json!({"window_id": id, "title": title})).collect::<Vec<_>>(),
})
}
/// One sentence for the tool text.
pub fn describe(&self) -> String {
let mut parts = Vec::new();
if self.title_before != self.title_after {
parts.push(format!(
"its title changed from \"{}\" to \"{}\"",
self.title_before, self.title_after
));
}
if !self.new_windows.is_empty() {
parts.push(format!(
"it opened {}",
self.new_windows
.iter()
.map(|(id, title)| format!("window {id} \"{title}\""))
.collect::<Vec<_>>()
.join(", ")
));
}
format!(
"The point was over window {} of another application (pid {}); {}.",
self.window,
self.pid,
if parts.is_empty() {
"it did not visibly react (title unchanged, no new window)".to_owned()
} else {
parts.join(" and ")
}
)
}
}
/// The topmost managed toplevel under the screen point that belongs to a
/// pid other than `target_pid`, with that pid's toplevels at this moment.
fn foreign_toplevel_under(
target_pid: Option<u32>,
x: i32,
y: i32,
) -> Option<(crate::x11::WindowInfo, Vec<u64>)> {
let windows = crate::x11::list_windows(None);
let hit = windows
.iter()
.rev()
.find(|w| {
w.is_on_screen
&& w.width > 0
&& w.height > 0
&& x >= w.x
&& y >= w.y
&& x < w.x + w.width as i32
&& y < w.y + w.height as i32
})?
.clone();
let pid = hit.pid?;
if target_pid == Some(pid) {
return None;
}
let owned = windows
.iter()
.filter(|w| w.pid == Some(pid))
.map(|w| w.xid)
.collect();
Some((hit, owned))
}
/// Re-read the foreign toplevel after the action.
fn foreign_window_effect(
before: Option<(crate::x11::WindowInfo, Vec<u64>)>,
) -> Option<ForeignWindowEffect> {
let (hit, owned) = before?;
let pid = hit.pid?;
let title_after = crate::x11::window_info(hit.xid)
.map(|w| w.title)
.unwrap_or_default();
let new_windows = crate::x11::list_windows(Some(pid))
.into_iter()
.filter(|w| !owned.contains(&w.xid) && w.is_on_screen)
.map(|w| (w.xid, w.title))
.collect();
Some(ForeignWindowEffect {
window: hit.xid,
pid,
title_before: hit.title,
title_after,
new_windows,
})
}
impl PointerEffect {
/// A region that changed more than this has plainly reacted to the click
/// (a menu, a caret, a selection, a pressed button). Below it the click
/// may still have landed without a visible reaction.
pub const LANDED_THRESHOLD_PCT: f64 = 0.4;
pub fn landed(&self) -> bool {
self.popups_appeared > 0
|| self
.region_diff_pct
.is_some_and(|pct| pct >= Self::LANDED_THRESHOLD_PCT)
}
}
/// Mapped override-redirect children of the root window: popup menus and
/// popovers, but also tooltips and the agent-cursor overlay, so only the
/// *new* ones across an action are meaningful (see [`mapped_popups`]).
fn new_popups(before: &[PopupWindow], after: Vec<PopupWindow>) -> Vec<PopupWindow> {
after
.into_iter()
.filter(|popup| !before.iter().any(|old| old.window == popup.window))
.collect()
}
/// Debug overrides for the multi-click cadence (milliseconds), read once.
fn click_cadence() -> (u64, u64) {
fn env_ms(name: &str, default: u64) -> u64 {
std::env::var(name)
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(default)
}
(
env_ms("CUA_MPX_PRESS_MS", 12),
env_ms("CUA_MPX_CLICK_GAP_MS", CLICK_DELAY_MS),
)
}
/// Half-size of the square screen region compared around the action point.
const EFFECT_REGION_HALF: i32 = 120;
/// Half-size of the central square masked out of the comparison: the agent
/// cursor overlay pulses there and would count as a change.
const EFFECT_MASK_HALF: i32 = 32;
/// Wait for the application to react before comparing the region.
const EFFECT_SETTLE: Duration = Duration::from_millis(250);
/// Raw ZPixmap bytes of a root-window region (clamped to the screen).
fn root_region_pixels(cx: i32, cy: i32) -> Option<(Vec<u8>, usize, usize)> {
let (conn, screen_num) = RustConnection::connect(None).ok()?;
let screen = &conn.setup().roots[screen_num];
let sw = i32::from(screen.width_in_pixels);
let sh = i32::from(screen.height_in_pixels);
let x0 = (cx - EFFECT_REGION_HALF).clamp(0, sw.max(1) - 1);
let y0 = (cy - EFFECT_REGION_HALF).clamp(0, sh.max(1) - 1);
let x1 = (cx + EFFECT_REGION_HALF).clamp(x0 + 1, sw);
let y1 = (cy + EFFECT_REGION_HALF).clamp(y0 + 1, sh);
let (w, h) = ((x1 - x0) as usize, (y1 - y0) as usize);
let reply = conn
.get_image(
ImageFormat::Z_PIXMAP,
screen.root,
x0 as i16,
y0 as i16,
w as u16,
h as u16,
u32::MAX,
)
.ok()?
.reply()
.ok()?;
if reply.depth < 24 || reply.data.len() < w * h * 4 {
return None;
}
Some((reply.data, w, h))
}
/// Percentage of pixels outside the central mask whose 8-bit channels differ
/// by more than a small tolerance between two captures of the same region.
pub(crate) fn region_diff_pct(
before: &(Vec<u8>, usize, usize),
after: &(Vec<u8>, usize, usize),
) -> Option<f64> {
let (a, w, h) = before;
let (b, w2, h2) = after;
if w != w2 || h != h2 || a.len() != b.len() || *w == 0 || *h == 0 {
return None;
}
let (cx, cy) = (*w as i32 / 2, *h as i32 / 2);
let mut changed = 0usize;
let mut counted = 0usize;
for y in 0..*h {
for x in 0..*w {
if (x as i32 - cx).abs() <= EFFECT_MASK_HALF
&& (y as i32 - cy).abs() <= EFFECT_MASK_HALF
{
continue;
}
counted += 1;
let i = (y * w + x) * 4;
let differs = (0..3).any(|c| {
let pa = i32::from(a[i + c]);
let pb = i32::from(b[i + c]);
(pa - pb).abs() > 24
});
if differs {
changed += 1;
}
}
}
(counted > 0).then(|| 100.0 * changed as f64 / counted as f64)
}
/// Best-effort `_NET_WM_NAME` / `WM_NAME` of a window (or of a child, for a
/// WM frame), for naming a covering window in a refusal.
fn window_title_for_report(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> String {
fn name_of(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> Option<String> {
unsafe {
let net_name =
x11::xlib::XInternAtom(display, c"_NET_WM_NAME".as_ptr(), x11::xlib::True);
for prop in [net_name, x11::xlib::XA_WM_NAME] {
if prop == 0 {
continue;
}
let mut type_ret: x11::xlib::Atom = 0;
let mut format_ret = 0;
let mut nitems: std::os::raw::c_ulong = 0;
let mut bytes_after: std::os::raw::c_ulong = 0;
let mut data: *mut std::os::raw::c_uchar = std::ptr::null_mut();
let rc = x11::xlib::XGetWindowProperty(
display,
window,
prop,
0,
256,
x11::xlib::False,
x11::xlib::AnyPropertyType as x11::xlib::Atom,
&mut type_ret,
&mut format_ret,
&mut nitems,
&mut bytes_after,
&mut data,
);
if rc == x11::xlib::Success as i32 && !data.is_null() {
let text = if format_ret == 8 && nitems > 0 {
Some(
String::from_utf8_lossy(std::slice::from_raw_parts(
data,
nitems as usize,
))
.into_owned(),
)
} else {
None
};
x11::xlib::XFree(data as *mut _);
if let Some(text) = text.filter(|t| !t.trim().is_empty()) {
return Some(text);
}
}
}
}
None
}
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let mut title = name_of(display, window);
if title.is_none() {
title = window_children(display, window)
.into_iter()
.rev()
.find_map(|kid| name_of(display, kid));
}
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
title.unwrap_or_default()
}
/// Direct children of `window` (empty on error).
fn window_children(
display: *mut x11::xlib::Display,
window: x11::xlib::Window,
) -> Vec<x11::xlib::Window> {
let mut root_ret: x11::xlib::Window = 0;
let mut parent: x11::xlib::Window = 0;
let mut children: *mut x11::xlib::Window = ptr::null_mut();
let mut count: std::os::raw::c_uint = 0;
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let rc = unsafe {
x11::xlib::XQueryTree(
display,
window,
&mut root_ret,
&mut parent,
&mut children,
&mut count,
)
};
unsafe { x11::xlib::XSetErrorHandler(previous_handler) };
if rc == 0 || children.is_null() {
return Vec::new();
}
let kids = unsafe { std::slice::from_raw_parts(children, count as usize) }.to_vec();
unsafe { x11::xlib::XFree(children as *mut _) };
kids
}
/// The toplevel (root child) the virtual pointer would press on at `(x, y)`
/// when the caller means `window`. `Ok(None)` when the point is over the
/// target itself (its WM frame) or over an override-redirect popup (a menu or
/// combo list the click is meant to reach, or the agent-cursor overlay);
/// `Ok(Some(_))` names the window that covers the point instead.
fn occluding_window(
display: *mut x11::xlib::Display,
window: x11::xlib::Window,
x: i32,
y: i32,
) -> Result<PointCover> {
if let Some(bounds) = window_screen_bounds(display, window) {
if !bounds_contain(bounds, x, y) {
return Ok(PointCover::Outside(PointOutsideWindow {
target_window: window,
screen_x: x,
screen_y: y,
window_x: x - bounds.0,
window_y: y - bounds.1,
bounds,
}));
}
}
let under = root_child_under_point(display, x, y);
let frame = root_child_of(display, window);
match (under, frame) {
(Some(under), Some(frame)) if under != frame && !is_override_redirect(display, under) => {
let previous_handler = unsafe { x11::xlib::XSetErrorHandler(Some(ignore_x_error)) };
let covering_client = window_children(display, under)
.into_iter()
.find(|kid| crate::x11::window_pid(*kid).is_some());
let covering_pid = crate::x11::window_pid(under)
.or_else(|| covering_client.and_then(crate::x11::window_pid));
unsafe {
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(previous_handler);
}
let target_pid = crate::x11::window_pid(window);
let title = window_title_for_report(display, under);
// The app's own window (a dialog, a file chooser) sits over the
// point: the press goes where the caller can see it, on that
// window, and the effect reports the retarget.
if target_pid.is_some() && covering_pid == target_pid {
return Ok(PointCover::SameApp(SameAppCover {
window: covering_client.unwrap_or(under),
title,
}));
}
Ok(PointCover::Occluded(TargetOccluded {
target_window: window,
covering_window: under,
covering_title: title,
covering_pid,
x,
y,
}))
}
(Some(_), Some(_)) | (None, _) => Ok(PointCover::Clear),
(Some(_), None) => bail!("target window {window} is not mapped on this screen"),
}
}
/// What sits over the screen point a background pointer action aims at.
#[derive(Debug, Clone)]
enum PointCover {
/// The target (or a popup meant to receive the press).
Clear,
/// A window of the target's own pid; the press is retargeted to it.
SameApp(SameAppCover),
/// Another application's window; refused.
Occluded(TargetOccluded),
/// The point is not inside the target window at all; refused.
Outside(PointOutsideWindow),
}
/// The target application's own window that received a press aimed at a
/// point of another of its windows (its dialog over its main window).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SameAppCover {
/// Client window id (the `list_windows` id, not the WM frame).
pub window: u64,
pub title: String,
}
/// True when neither the EWMH active window nor the core focus moved since
/// `saved` was taken.
fn focus_state_unchanged(display: *mut x11::xlib::Display, saved: &SavedFocus) -> bool {
unsafe { x11::xlib::XSync(display, 0) };
let mut core_focus: x11::xlib::Window = 0;
let mut revert_to: std::os::raw::c_int = 0;
unsafe {
x11::xlib::XGetInputFocus(display, &mut core_focus, &mut revert_to);
}
ewmh_active_window(display) == saved.ewmh_active && core_focus == saved.core_focus
}
fn pointer_effect(
display: *mut x11::xlib::Display,
saved: &SavedFocus,
before: Option<(Vec<u8>, usize, usize)>,
popups_before: &[PopupWindow],
foreign_before: Option<(crate::x11::WindowInfo, Vec<u64>)>,
x: i32,
y: i32,
) -> PointerEffect {
unsafe { x11::xlib::XSync(display, 0) };
crate::interaction::pause(EFFECT_SETTLE);
let after = root_region_pixels(x, y);
let popups = new_popups(popups_before, mapped_popups(display));
let foreign_window = foreign_window_effect(foreign_before);
PointerEffect {
focus_unchanged: focus_state_unchanged(display, saved),
region_diff_pct: match (before, after) {
(Some(b), Some(a)) => region_diff_pct(&b, &a),
_ => None,
},
x,
y,
popups_appeared: popups.len(),
focus_guard: None,
retargeted_to: None,
popups,
window_point: None,
foreign_window,
}
}
/// Land a discrete click via the MPX real-input pipeline (see
/// [`VirtualPointerClick`]). Refuses with [`TargetOccluded`] when another
/// toplevel covers the point. Returns the post-checks the tool reports.
pub fn send_virtual_pointer_click(
cursor_id: &str,
click: &VirtualPointerClick,
) -> Result<PointerEffect> {
let _op = mpx_op_guard(cursor_id);
let display = open_display()?;
supports_parallel_pointer_injection(display)?;
let saved_focus = save_focus_state(display);
let result = (|| -> Result<PointerEffect> {
let window = click.target_window as x11::xlib::Window;
let retargeted_to = match occluding_window(display, window, click.x, click.y)? {
PointCover::Clear => None,
PointCover::SameApp(cover) => Some(cover),
PointCover::Occluded(occluded) => return Err(occluded.into()),
PointCover::Outside(outside) => return Err(outside.into()),
};
let ids = ensure_master_pointer(cursor_id)?;
let device = uinput_pointers()
.lock()
.unwrap()
.get(cursor_id)
.cloned()
.ok_or_else(|| anyhow!("missing uinput pointer for '{cursor_id}'"))?;
let count = click.count.max(1);
// A device left frozen by an earlier synchronous grab (a WM that never
// replayed) would queue this press forever.
thaw_device(display, ids.pointer_id);
warp_master_pointer(display, ids, click.x, click.y)?;
let popups_before = mapped_popups(display);
let foreign_before = foreign_toplevel_under(
crate::x11::window_pid(click.target_window),
click.x,
click.y,
);
let before = root_region_pixels(click.x, click.y);
let (press_ms, gap_ms) = click_cadence();
let train = (|| -> Result<()> {
for i in 0..count {
{
let mut device = device.lock().unwrap();
emit_button(&mut device, click.button, true)?;
// A real press and release are separate evdev frames; give
// the toolkit a press it can see before the release lands.
crate::interaction::pause(Duration::from_millis(press_ms));
emit_button(&mut device, click.button, false)?;
}
// Multi-click cadence: keep press→press well under the toolkit
// double-click threshold (GTK default 250 ms) so count=2 lands
// as a real double-click, not two singles.
if count > 1 && i + 1 < count {
crate::interaction::pause(Duration::from_millis(gap_ms));
}
}
Ok(())
})();
// Never leave the button held: a stuck Button1 on the virtual master
// sets bit 8 of the core modifier state (Orca's modifier), so every
// later virtual-keyboard chord would open Orca's preferences.
release_button_best_effort(&device, click.button);
train?;
let mut effect = pointer_effect(
display,
&saved_focus,
before,
&popups_before,
foreign_before,
click.x,
click.y,
);
effect.retargeted_to = retargeted_to;
let target_pid = if effect.popups.is_empty() {
None
} else {
window_or_child_pid(display, click.target_window as x11::xlib::Window)
};
track_click_popups(
cursor_id,
effect
.popups
.iter()
.filter(|popup| popup.pid.is_some() && popup.pid == target_pid)
.map(|popup| popup.window),
);
Ok(effect)
})();
restore_focus_state(display, &saved_focus);
unsafe {
x11::xlib::XCloseDisplay(display);
}
result
}
/// One held drag on the session's virtual master pointer: press at
/// `path[0]`, glide through the waypoints, release at the end. Same delivery
/// rules as [`send_virtual_pointer_click`] (no shield grab, occlusion refusal
/// at the press point, focus saved and restored).
pub fn send_virtual_pointer_drag(
cursor_id: &str,
drag: &VirtualPointerDrag,
) -> Result<PointerEffect> {
let _op = mpx_op_guard(cursor_id);
let display = open_display()?;
supports_parallel_pointer_injection(display)?;
let saved_focus = save_focus_state(display);
let result = (|| -> Result<PointerEffect> {
if drag.path.len() < 2 {
bail!("drag path needs at least 2 points");
}
let window = drag.target_window as x11::xlib::Window;
let start = drag.path[0];
let end = drag.path[drag.path.len() - 1];
let retargeted_to = match occluding_window(display, window, start.0, start.1)? {
PointCover::Clear => None,
PointCover::SameApp(cover) => Some(cover),
PointCover::Occluded(occluded) => return Err(occluded.into()),
PointCover::Outside(outside) => return Err(outside.into()),
};
let ids = ensure_master_pointer(cursor_id)?;
let device = uinput_pointers()
.lock()
.unwrap()
.get(cursor_id)
.cloned()
.ok_or_else(|| anyhow!("missing uinput pointer for '{cursor_id}'"))?;
let (cum, total) = path_cumulative(&drag.path);
let steps = drag.steps.max(1);
let step_delay = Duration::from_millis(drag.duration_ms / steps as u64);
thaw_device(display, ids.pointer_id);
warp_master_pointer(display, ids, start.0, start.1)?;
let popups_before = mapped_popups(display);
let foreign_before =
foreign_toplevel_under(crate::x11::window_pid(drag.target_window), end.0, end.1);
let before = root_region_pixels(end.0, end.1);
let gesture = (|| -> Result<()> {
{
let mut device = device.lock().unwrap();
emit_button(&mut device, drag.button, true)?;
}
// Let the toolkit register the press (and arm its drag threshold)
// before the first motion.
crate::interaction::pause(Duration::from_millis(40));
let (mut last_x, mut last_y) = start;
for step in 1..=steps {
let t = step as f64 / steps as f64;
let (ix, iy) = point_on_path(&drag.path, &cum, total, t);
let (dx, dy) = (ix - last_x, iy - last_y);
if dx != 0 || dy != 0 {
let mut device = device.lock().unwrap();
emit_relative_motion(&mut device, dx, dy)?;
crate::overlay::send_command_for(
cursor_id.to_owned(),
cursor_overlay::OverlayCommand::SnapTo {
x: ix as f64,
y: iy as f64,
heading_radians: Some((dy as f64).atan2(dx as f64)),
},
);
}
last_x = ix;
last_y = iy;
crate::interaction::pause(step_delay);
}
// Relative motion accumulates libinput rounding; pin the release
// to the exact end point before letting go.
warp_master_pointer(display, ids, end.0, end.1)?;
crate::interaction::pause(Duration::from_millis(20));
let mut device = device.lock().unwrap();
emit_button(&mut device, drag.button, false)?;
Ok(())
})();
// Release on every exit path (see `send_virtual_pointer_click`).
release_button_best_effort(&device, drag.button);
gesture?;
let mut effect = pointer_effect(
display,
&saved_focus,
before,
&popups_before,
foreign_before,
end.0,
end.1,
);
effect.retargeted_to = retargeted_to;
Ok(effect)
})();
restore_focus_state(display, &saved_focus);
unsafe {
x11::xlib::XCloseDisplay(display);
}
result
}
/// A discrete no-focus-steal scroll driven through the MPX master pointer +
/// uinput slave. Unlike a click it needs no shield grab: WMs don't focus on
/// wheel input, and libinput turns the emitted REL_WHEEL/REL_HWHEEL detents into
/// the XI2 smooth-scroll events GTK consumes — where synthetic Button4-7
/// `XSendEvent`s are dropped. `x`,`y` are the screen point to scroll over (the
/// scroll lands on whatever window owns that pixel under our master pointer);
/// `ticks` is a signed detent count (+up / +right per evdev convention).
#[derive(Clone, Debug)]
pub struct VirtualPointerScroll {
pub target_window: u64,
pub x: i32,
pub y: i32,
pub horizontal: bool,
pub ticks: i32,
}
/// Land a discrete scroll via the MPX real-input pipeline (see
/// [`VirtualPointerScroll`]). Warps the dedicated master pointer over the target
/// point, then emits `|ticks|` wheel detents on the uinput slave. The master is
/// torn down and focus restored on exit, matching the click/drag paths.
pub fn send_virtual_pointer_scroll(cursor_id: &str, scroll: &VirtualPointerScroll) -> Result<()> {
let _op = mpx_op_guard(cursor_id);
let display = open_display()?;
supports_parallel_pointer_injection(display)?;
let saved_focus = save_focus_state(display);
let result = (|| -> Result<()> {
let ids = ensure_master_pointer(cursor_id)?;
let device = uinput_pointers()
.lock()
.unwrap()
.get(cursor_id)
.cloned()
.ok_or_else(|| anyhow!("missing uinput pointer for '{cursor_id}'"))?;
warp_master_pointer(display, ids, scroll.x, scroll.y)?;
let detents = scroll.ticks.unsigned_abs() as usize;
if detents == 0 {
return Ok(());
}
let unit = if scroll.ticks >= 0 { 1 } else { -1 };
for _ in 0..detents {
{
let mut device = device.lock().unwrap();
emit_scroll(&mut device, scroll.horizontal, unit)?;
}
crate::interaction::pause(Duration::from_millis(CLICK_DELAY_MS));
}
Ok(())
})();
let _ = cursor_id; // master pair retained for reuse (see the drag path).
restore_focus_state(display, &saved_focus);
unsafe {
x11::xlib::XCloseDisplay(display);
}
result
}
/// Pre-drag focus snapshot: the EWMH active window when a conforming WM is
/// running, plus the core input focus as a WM-agnostic fallback.
struct SavedFocus {
ewmh_active: Option<x11::xlib::Window>,
core_focus: x11::xlib::Window,
core_revert_to: std::os::raw::c_int,
}
fn save_focus_state(display: *mut x11::xlib::Display) -> SavedFocus {
let mut core_focus: x11::xlib::Window = 0;
let mut core_revert_to: std::os::raw::c_int = 0;
unsafe {
x11::xlib::XGetInputFocus(display, &mut core_focus, &mut core_revert_to);
}
SavedFocus {
ewmh_active: ewmh_active_window(display),
core_focus,
core_revert_to,
}
}
unsafe extern "C" fn ignore_x_error(
_display: *mut x11::xlib::Display,
_event: *mut x11::xlib::XErrorEvent,
) -> std::os::raw::c_int {
0
}
fn restore_focus_state(display: *mut x11::xlib::Display, saved: &SavedFocus) {
let cleanup = std::time::Instant::now() + crate::interaction::CLEANUP_CAP;
let nap = |wait: Duration| {
sleep(wait.min(cleanup.saturating_duration_since(std::time::Instant::now())))
};
// Let the release/focus events from the drag settle before reading the
// post-drag state, so we don't race the WM's own focus update.
unsafe { x11::xlib::XSync(display, 0) };
if let Some(prev) = saved.ewmh_active {
// Fast path: on WMs whose click-to-focus grab ignores the virtual
// master (mutter grabs for the Virtual Core Pointer only) nothing
// moved, and a 300 ms settle per click would be pure latency.
if ewmh_active_window(display) == Some(prev) {
let mut stable = 0;
for _ in 0..4 {
nap(Duration::from_millis(25));
if ewmh_active_window(display) == Some(prev) {
stable += 1;
} else {
stable = 0;
break;
}
}
if stable >= 3 {
return;
}
}
// EWMH path: ask the WM to re-activate, so its active-window
// bookkeeping (decorations, stacking) stays consistent. The WM
// processes its own click-to-focus for the drag asynchronously and
// can re-activate the dragged window even after one re-activation of
// ours has landed — so don't stop at first success: require the
// active window to hold stable for consecutive checks, re-sending on
// every regression, within a bounded budget.
let name = unsafe { std::ffi::CStr::from_ptr(x11::xlib::XDisplayString(display)) };
let conn = name
.to_str()
.ok()
.and_then(|name| RustConnection::connect(Some(name)).ok())
.map(|(conn, _)| conn);
let prev_pid = conn
.as_ref()
.zip(u32::try_from(prev).ok())
.and_then(|(conn, prev)| crate::x11::get_window_pid(conn, prev).ok().flatten());
let own_dialog = |now: Option<x11::xlib::Window>| match (&conn, prev_pid, now) {
(Some(conn), Some(pid), Some(now)) => now != prev && is_own_dialog(conn, pid, now),
_ => false,
};
if own_dialog(ewmh_active_window(display)) || !window_exists(display, prev) {
return;
}
nap(Duration::from_millis(150));
let mut stable = 0;
let mut attempt = 0;
while std::time::Instant::now() < cleanup {
attempt += 1;
let now = ewmh_active_window(display);
if now == Some(prev) {
stable += 1;
if stable >= 3 {
return;
}
} else if own_dialog(now) || !window_exists(display, prev) {
return;
} else {
stable = 0;
// MPX clicks can leave a core-protocol WM believing the
// dragged window is focused while the core focus never moved
// there: its XSetInputFocus for our activation is then a
// no-op, no FocusIn arrives, and its bookkeeping never
// updates. Bounce the core focus onto the window the WM
// believes active so the activation produces a real focus
// transition the WM can observe.
if attempt > 2 {
if let Some(now_win) = now {
unsafe {
let prev_handler = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
x11::xlib::XSetInputFocus(
display,
now_win,
x11::xlib::RevertToParent,
x11::xlib::CurrentTime,
);
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(prev_handler);
}
nap(Duration::from_millis(50));
}
}
ewmh_activate_window(display, prev, now.unwrap_or(0));
}
nap(Duration::from_millis(50));
}
if stable == 0 {
tracing::warn!("focus restore: WM did not re-activate 0x{prev:x}");
}
return;
}
// No EWMH WM (bare X / minimal WM): restore the core input focus
// directly. The saved window may have been destroyed meanwhile, and
// Xlib's default error handler exits the process on BadWindow, so the
// restore runs under a scoped ignore-errors handler.
if saved.core_focus == 0 {
return;
}
unsafe {
let mut now_focus: x11::xlib::Window = 0;
let mut now_revert: std::os::raw::c_int = 0;
x11::xlib::XGetInputFocus(display, &mut now_focus, &mut now_revert);
if now_focus == saved.core_focus {
return;
}
let prev_handler = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
x11::xlib::XSetInputFocus(
display,
saved.core_focus,
saved.core_revert_to,
x11::xlib::CurrentTime,
);
x11::xlib::XSync(display, 0);
x11::xlib::XSetErrorHandler(prev_handler);
}
}
/// Whether `window` still exists; a click that closed the saved window leaves
/// nothing to restore.
fn window_exists(display: *mut x11::xlib::Display, window: x11::xlib::Window) -> bool {
unsafe {
let prev_handler = x11::xlib::XSetErrorHandler(Some(ignore_x_error));
let mut attributes: x11::xlib::XWindowAttributes = std::mem::zeroed();
let exists = x11::xlib::XGetWindowAttributes(display, window, &mut attributes) != 0;
x11::xlib::XSetErrorHandler(prev_handler);
exists
}
}
fn is_own_dialog(conn: &RustConnection, previous_pid: u32, active: x11::xlib::Window) -> bool {
let Ok(active) = u32::try_from(active) else {
return false;
};
if crate::x11::get_window_pid(conn, active).ok().flatten() != Some(previous_pid) {
return false;
}
let windows = |property: Atom, kind: Atom| -> Vec<u32> {
conn.get_property(false, active, property, kind, 0, 32)
.ok()
.and_then(|cookie| cookie.reply().ok())
.and_then(|reply| reply.value32().map(|values| values.collect()))
.unwrap_or_default()
};
if windows(AtomEnum::WM_TRANSIENT_FOR.into(), AtomEnum::WINDOW.into())
.iter()
.any(|&parent| parent != x11rb::NONE)
{
return true;
}
let atom = |name: &str| crate::x11::get_atom(conn, name).ok();
let (Some(window_type), Some(dialog)) = (
atom("_NET_WM_WINDOW_TYPE"),
atom("_NET_WM_WINDOW_TYPE_DIALOG"),
) else {
return false;
};
windows(window_type, AtomEnum::ATOM.into()).contains(&dialog)
}
#[derive(Clone, Copy, Debug)]
struct EventTarget {
window: Window,
local_x: i16,
local_y: i16,
root_x: i16,
root_y: i16,
}
fn point_in_rect(x: i32, y: i32, geom: &GetGeometryReply) -> bool {
x >= geom.x as i32
&& y >= geom.y as i32
&& x < geom.x as i32 + geom.width as i32
&& y < geom.y as i32 + geom.height as i32
}
fn deepest_child_at_point(
conn: &RustConnection,
window: Window,
local_x: i32,
local_y: i32,
) -> Result<(Window, i32, i32)> {
let tree = conn.query_tree(window)?.reply()?;
for child in tree.children.iter().rev() {
let Ok(geom) = conn.get_geometry(*child)?.reply() else {
continue;
};
if !point_in_rect(local_x, local_y, &geom) {
continue;
}
let child_x = local_x - geom.x as i32;
let child_y = local_y - geom.y as i32;
return deepest_child_at_point(conn, *child, child_x, child_y);
}
Ok((window, local_x, local_y))
}
fn window_path_at_point(
conn: &RustConnection,
window: Window,
local_x: i32,
local_y: i32,
) -> Result<Vec<(Window, i32, i32, EventMask)>> {
let attributes = conn.get_window_attributes(window)?.reply()?;
let mut path = vec![(window, local_x, local_y, attributes.all_event_masks)];
let tree = conn.query_tree(window)?.reply()?;
for child in tree.children.iter().rev() {
let Ok(geom) = conn.get_geometry(*child)?.reply() else {
continue;
};
if !point_in_rect(local_x, local_y, &geom) {
continue;
}
let child_x = local_x - geom.x as i32;
let child_y = local_y - geom.y as i32;
path.extend(window_path_at_point(conn, *child, child_x, child_y)?);
break;
}
Ok(path)
}
fn deepest_event_target(
path: &[(Window, i32, i32, EventMask)],
required_masks: EventMask,
) -> (Window, i32, i32) {
path.iter()
.rev()
.find(|(_, _, _, selected)| selected.contains(required_masks))
.or_else(|| path.last())
.map(|&(window, x, y, _)| (window, x, y))
.expect("window path always contains its toplevel")
}
fn click_event_target(path: &[(Window, i32, i32, EventMask)]) -> (Window, i32, i32) {
deepest_event_target(path, EventMask::BUTTON_PRESS)
}
fn build_event_target(
conn: &RustConnection,
xid: u64,
x: i32,
y: i32,
window: Window,
local_x: i32,
local_y: i32,
) -> Result<EventTarget> {
let top = xid as Window;
let root = conn.setup().roots[0].root;
let root_pos = conn.translate_coordinates(top, root, 0, 0)?.reply()?;
Ok(EventTarget {
window,
local_x: local_x as i16,
local_y: local_y as i16,
root_x: (root_pos.dst_x as i32 + x) as i16,
root_y: (root_pos.dst_y as i32 + y) as i16,
})
}
fn resolve_event_target(conn: &RustConnection, xid: u64, x: i32, y: i32) -> Result<EventTarget> {
let top = xid as Window;
let (window, local_x, local_y) = deepest_child_at_point(conn, top, x, y)?;
build_event_target(conn, xid, x, y, window, local_x, local_y)
}
fn resolve_click_event_target(
conn: &RustConnection,
xid: u64,
x: i32,
y: i32,
) -> Result<EventTarget> {
let top = xid as Window;
let path = window_path_at_point(conn, top, x, y)?;
// Button bindings commonly select only ButtonPress (Tk's <Button-1> is one
// example). Route the complete synthetic click to that same client-owned
// window: splitting release onto a different geometric leaf does not form a
// coherent toolkit click sequence.
let target = click_event_target(&path);
build_event_target(conn, xid, x, y, target.0, target.1, target.2)
}
fn button_state_mask(button: u8) -> KeyButMask {
match button {
1 => KeyButMask::BUTTON1,
2 => KeyButMask::BUTTON2,
3 => KeyButMask::BUTTON3,
4 => KeyButMask::BUTTON4,
5 => KeyButMask::BUTTON5,
_ => KeyButMask::from(0u16),
}
}
/// Open an X11 connection for background input injection, failing *loudly* and
/// actionably when input cannot be delivered — rather than letting a pure
/// Wayland session fall through to an X11 path that silently no-ops yet reports
/// success (#1921). On a pure Wayland session with the native backend off, this
/// returns a clear error naming the fix; otherwise it connects and, on any
/// connect failure, surfaces DISPLAY so the cause is diagnosable.
fn connect_x11_for_input() -> Result<(RustConnection, usize)> {
if let Some(reason) = crate::wayland::wayland_input_unavailable_reason() {
bail!("{reason}");
}
let (conn, screen) = RustConnection::connect(None).map_err(|e| {
anyhow!(
"cannot inject input: X11 connection failed (DISPLAY={:?}): {e}",
std::env::var("DISPLAY").ok()
)
})?;
action::fence(conn.stream())?;
Ok((conn, screen))
}
fn admitted<T, E: Into<anyhow::Error>>(send: impl FnOnce() -> Result<T, E>) -> Result<T> {
action::admit(send)?.map_err(Into::into)
}
/// How long dropping an abandoned call's [`Delivered`] waits for its
/// releases. It bounds the wait only: the releasing thread is not stopped,
/// and keeps the call's desktop lease until its X11 requests return.
const ABANDONED_RELEASE_WAIT: Duration = Duration::from_secs(2);
/// XTest presses this call queued, and whether each is still held. A route
/// releases what is held on its own connection, even after a failure.
/// Abandoning the call shuts that connection, so the releases it still owes
/// cannot go out there: dropping this then sends them on a fresh connection
/// from a thread that holds the call's [`action::Action`], and with it the
/// desktop, until those releases are done. The drop waits for them at most
/// [`ABANDONED_RELEASE_WAIT`]; past it the thread still holds the desktop.
/// The server ignores a release for a key or button that is already up.
#[derive(Default)]
struct Delivered(Vec<(u8, u8, bool)>);
impl Delivered {
fn press<C>(
&mut self,
kind: u8,
detail: u8,
send: impl FnOnce() -> Result<C, x11rb::errors::ConnectionError>,
) -> Result<C> {
let sent = admitted(send)?;
self.0.push((kind + 1, detail, true));
Ok(sent)
}
/// The release of the latest held `detail` pressed by `kind + 1` went out.
fn released(&mut self, release: u8, detail: u8) {
if let Some(press) = self
.0
.iter_mut()
.rev()
.find(|press| **press == (release, detail, true))
{
press.2 = false;
}
}
/// Release on `conn` whatever is still held, latest first.
fn release_held(&mut self, conn: &RustConnection) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let mut result = Ok(());
for (release, detail, held) in self.0.iter_mut().rev().filter(|press| press.2) {
*held = false;
if let Err(error) = conn.xtest_fake_input(*release, *detail, 0, x11rb::NONE, 0, 0, 0) {
result = result.and(Err(error.into()));
}
}
result
}
/// The server took every release: nothing is owed after abandon.
fn confirmed(&mut self) {
self.0.clear();
}
}
impl Drop for Delivered {
fn drop(&mut self) {
let Some(action) = action::current().filter(|action| action.is_abandoned()) else {
return;
};
if self.0.is_empty() {
return;
}
let presses = self
.0
.drain(..)
.map(|(release, detail, _)| (release, detail));
if let Err(error) = release_abandoned(action, presses.collect()) {
tracing::warn!("releasing the input of an abandoned call failed: {error:#}");
}
}
}
fn release_abandoned(action: Arc<action::Action>, presses: Vec<(u8, u8)>) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (done, finished) = std::sync::mpsc::channel();
std::thread::spawn(move || {
let _desktop = action;
let released = (|| -> Result<()> {
let (conn, _) = RustConnection::connect(None)?;
for &(kind, detail) in presses.iter().rev() {
conn.xtest_fake_input(kind, detail, 0, x11rb::NONE, 0, 0, 0)?;
}
conn.get_input_focus()?.reply()?;
Ok(())
})();
let _ = done.send(released);
});
finished.recv_timeout(ABANDONED_RELEASE_WAIT).map_err(|_| {
anyhow!("the X server did not take the releases within {ABANDONED_RELEASE_WAIT:?}")
})?
}
/// Send a synthetic FocusIn event to a window without changing the actual X11 input focus.
/// This can trigger toolkit-level focus handlers (e.g., Qt5's AT-SPI bridge) without
/// moving the window manager's active window. Use with send_focus_out to restore state.
pub fn send_focus_in(xid: u64) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let window = xid as u32;
let focus_in = FocusInEvent {
response_type: FOCUS_IN_EVENT,
detail: NotifyDetail::NONLINEAR,
sequence: 0,
event: window,
mode: NotifyMode::NORMAL,
};
admitted(|| conn.send_event(false, window, EventMask::FOCUS_CHANGE, focus_in))?;
conn.flush()?;
Ok(())
}
/// Send a synthetic FocusOut event to restore focus state after send_focus_in.
pub fn send_focus_out(xid: u64) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let window = xid as u32;
let focus_out = FocusOutEvent {
response_type: FOCUS_OUT_EVENT,
detail: NotifyDetail::NONLINEAR,
sequence: 0,
event: window,
mode: NotifyMode::NORMAL,
};
admitted(|| conn.send_event(false, window, EventMask::FOCUS_CHANGE, focus_out))?;
conn.flush()?;
Ok(())
}
/// Round-trip to the X server before the short-lived connection that sent
/// synthetic events is dropped. A bare flush is not enough: the server may
/// discard the tail of a client's request stream when the connection closes,
/// which drops the last key or button event (observed under Xvfb).
fn settle_synthetic_events(conn: &RustConnection) {
if let Ok(cookie) = conn.get_input_focus() {
let _ = cookie.reply();
}
}
/// Send a button click (down + up) to a window at window-local coordinates.
pub fn send_click(xid: u64, x: i32, y: i32, count: usize, button: u8) -> Result<()> {
send_click_with_modifiers(xid, x, y, count, button, &[])
}
/// Send a target-addressed X11 click whose event-state mask carries the named
/// modifiers. Unlike a plain AT-SPI action, this preserves multi-selection
/// semantics without changing the X input focus.
pub fn send_click_with_modifiers(
xid: u64,
x: i32,
y: i32,
count: usize,
button: u8,
modifiers: &[&str],
) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let root = conn.setup().roots[0].root;
let modifier_state = modifiers_to_state(modifiers);
for _ in 0..count {
let target = resolve_click_event_target(&conn, xid, x, y)?;
let press = ButtonPressEvent {
response_type: BUTTON_PRESS_EVENT,
detail: button,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: target.window,
child: x11rb::NONE,
root_x: target.root_x,
root_y: target.root_y,
event_x: target.local_x,
event_y: target.local_y,
state: modifier_state,
same_screen: true,
};
let release = ButtonReleaseEvent {
response_type: BUTTON_RELEASE_EVENT,
detail: button,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: target.window,
child: x11rb::NONE,
root_x: target.root_x,
root_y: target.root_y,
event_x: target.local_x,
event_y: target.local_y,
state: KeyButMask::from(
u16::from(modifier_state) | u16::from(button_state_mask(button)),
),
same_screen: true,
};
// The event mask selects recipients independently of the payload type.
// Select the press client for both payloads so a press-only toolkit
// binding (such as Tk's <Button-1>) receives one coherent click.
admitted(|| conn.send_event(false, target.window, EventMask::BUTTON_PRESS, press))?
.check()?;
crate::interaction::pause(Duration::from_millis(CLICK_DELAY_MS));
admitted(|| conn.send_event(false, target.window, EventMask::BUTTON_PRESS, release))?
.check()?;
if count > 1 {
crate::interaction::pause(Duration::from_millis(80));
}
}
settle_synthetic_events(&conn);
Ok(())
}
pub fn send_button_down(xid: u64, x: i32, y: i32, button: u8) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let root = conn.setup().roots[0].root;
let target = resolve_event_target(&conn, xid, x, y)?;
let press = ButtonPressEvent {
response_type: BUTTON_PRESS_EVENT,
detail: button,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: target.window,
child: x11rb::NONE,
root_x: target.root_x,
root_y: target.root_y,
event_x: target.local_x,
event_y: target.local_y,
state: KeyButMask::from(0u16),
same_screen: true,
};
admitted(|| conn.send_event(false, target.window, EventMask::BUTTON_PRESS, press))?.check()?;
settle_synthetic_events(&conn);
Ok(())
}
pub fn send_motion(xid: u64, x: i32, y: i32, button: Option<u8>) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let root = conn.setup().roots[0].root;
let target = resolve_event_target(&conn, xid, x, y)?;
let motion = MotionNotifyEvent {
response_type: MOTION_NOTIFY_EVENT,
detail: Motion::NORMAL,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: target.window,
child: x11rb::NONE,
root_x: target.root_x,
root_y: target.root_y,
event_x: target.local_x,
event_y: target.local_y,
state: button
.map(button_state_mask)
.unwrap_or_else(|| KeyButMask::from(0u16)),
same_screen: true,
};
admitted(|| conn.send_event(false, target.window, EventMask::POINTER_MOTION, motion))?;
conn.flush()?;
settle_synthetic_events(&conn);
Ok(())
}
pub fn send_button_up(xid: u64, x: i32, y: i32, button: u8) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let root = conn.setup().roots[0].root;
let target = resolve_event_target(&conn, xid, x, y)?;
let release = ButtonReleaseEvent {
response_type: BUTTON_RELEASE_EVENT,
detail: button,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: target.window,
child: x11rb::NONE,
root_x: target.root_x,
root_y: target.root_y,
event_x: target.local_x,
event_y: target.local_y,
state: button_state_mask(button),
same_screen: true,
};
conn.send_event(false, target.window, EventMask::BUTTON_RELEASE, release)?
.check()?;
settle_synthetic_events(&conn);
Ok(())
}
/// Type a string by sending KeyPress/KeyRelease events for each character.
pub fn send_type_text(xid: u64, text: &str) -> Result<()> {
send_type_text_with_delay(xid, text, 0)
}
fn type_text_with_preflight<G>(
text: &str,
keymap: &GetKeyboardMappingReply,
mut remap: impl FnMut(char, &mut GetKeyboardMappingReply) -> Result<(u8, Option<G>)>,
mut send: impl FnMut(u8, bool) -> Result<()>,
) -> Result<Vec<G>> {
let mut mapping = keymap.clone();
let mut guards = Vec::new();
let mut resolved = std::collections::HashMap::new();
let mut keys = Vec::new();
for ch in text.chars() {
let key = match resolved.get(&ch).copied() {
Some(key) => key,
None => {
let key = match char_to_keycode_shift(&mapping, mpx_keyboard::keysym_for_char(ch)) {
Some(key) => key,
None => {
let (keycode, guard) = remap(ch, &mut mapping).map_err(|error| {
let needed = text
.chars()
.map(mpx_keyboard::keysym_for_char)
.filter(|keysym| !keymap.keysyms.contains(keysym))
.collect::<std::collections::HashSet<_>>()
.len();
anyhow::anyhow!(
"typed 0 of {} characters: the text needs {needed} spare keycodes: {error:#}",
text.chars().count()
)
})?;
guards.extend(guard);
(keycode, false)
}
};
resolved.insert(ch, key);
key
}
};
keys.push(key);
}
for (keycode, needs_shift) in keys {
send(keycode, needs_shift)?;
}
Ok(guards)
}
fn type_text_in_spare_batches<G>(
text: &str,
mapping: &GetKeyboardMappingReply,
mut remap: impl FnMut(char, &mut GetKeyboardMappingReply) -> Result<(u8, Option<G>)>,
mut send: impl FnMut(u8, bool) -> Result<()>,
mut finish: impl FnMut() -> bool,
) -> Result<()> {
let total = text.chars().count();
let spares = match mapping.keysyms_per_keycode as usize {
0 => 0,
per => mapping
.keysyms
.chunks(per)
.enumerate()
.filter(|&(i, syms)| is_spare_keycode(8 + i, syms))
.count(),
};
let mut rest = text.chars().peekable();
let mut typed = 0;
while rest.peek().is_some() {
let mut mapping = mapping.clone();
let mut guards = Vec::new();
let mut resolved = std::collections::HashMap::new();
let mut remapped = 0;
let mut keys = Vec::new();
while let Some(&ch) = rest.peek() {
let key = match resolved
.get(&ch)
.copied()
.or_else(|| char_to_keycode_shift(&mapping, mpx_keyboard::keysym_for_char(ch)))
{
Some(key) => key,
None if spares > 0 && remapped == spares => break,
None => {
let (keycode, guard) = remap(ch, &mut mapping).map_err(|error| {
anyhow::anyhow!("typed {typed} of {total} characters: {error:#}")
})?;
remapped += 1;
guards.extend(guard);
resolved.insert(ch, (keycode, false));
(keycode, false)
}
};
keys.push(key);
rest.next();
}
for (keycode, needs_shift) in keys {
send(keycode, needs_shift)?;
typed += 1;
}
if !finish() && rest.peek().is_some() {
bail!(
"typed {typed} of {total} characters: the client has not confirmed reading the keys on the spare keycodes the next characters need"
);
}
}
Ok(())
}
/// Type a string with an additional `inter_char_ms` delay between each character.
pub fn send_type_text_with_delay(xid: u64, text: &str, inter_char_ms: u64) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let window = xid as u32;
let root = conn.setup().roots[0].root;
let mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
let client = RefCell::new(TextClient::new(&conn, Some(window)));
type_text_in_spare_batches(
text,
&mapping,
|ch, mapping| text_keycode(&mut client.borrow_mut(), mapping, ch),
|keycode, needs_shift| {
client.borrow_mut().record_recipient(keycode);
let state = if needs_shift {
KeyButMask::SHIFT
} else {
KeyButMask::from(0u16)
};
let press = KeyPressEvent {
response_type: KEY_PRESS_EVENT,
detail: keycode,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: window,
child: x11rb::NONE,
root_x: 0,
root_y: 0,
event_x: 0,
event_y: 0,
state,
same_screen: true,
};
let release = KeyReleaseEvent {
response_type: KEY_RELEASE_EVENT,
detail: keycode,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: window,
child: x11rb::NONE,
root_x: 0,
root_y: 0,
event_x: 0,
event_y: 0,
state,
same_screen: true,
};
admitted(|| conn.send_event(false, window, EventMask::KEY_PRESS, press))?;
// Start the hold interval after sending the press, not while it is buffered.
conn.flush()?;
crate::interaction::pause(Duration::from_millis(KEY_DELAY_MS));
conn.send_event(false, window, EventMask::KEY_RELEASE, release)?;
conn.flush()?;
if inter_char_ms > 0 {
crate::interaction::pause(Duration::from_millis(inter_char_ms));
}
Ok(())
},
|| client.borrow_mut().release(),
)?;
// Deliver the final release before this short-lived connection closes.
conn.get_input_focus()?.reply()?;
Ok(())
}
/// Type `text` into whatever window currently holds X keyboard focus, using the
/// XTest extension. Unlike [`send_type_text`] (synthetic XSendEvent, which GTK/Qt
/// silently drop for key input), XTest injects *real* input events, so they
/// actually reach the focused widget — a spreadsheet cell, a terminal, a canvas —
/// that exposes no AT-SPI EditableText interface to fill. There is no window
/// argument because XTest always delivers to the focused window; the caller
/// focuses the target by clicking it first. `\n`/`\t` map to Return/Tab.
pub fn send_type_text_xtest(text: &str) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (conn, _) = connect_x11_for_input()?;
let mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
// Shift keycode (modifier index 0) for shifted characters.
let modmap = conn.get_modifier_mapping()?.reply()?;
let kpm = modmap.keycodes_per_modifier() as usize;
let shift_kc = modmap
.keycodes
.get(..kpm)
.and_then(|s| s.iter().copied().find(|&k| k != 0))
.unwrap_or(50);
let client = RefCell::new(TextClient::new(&conn, None));
type_text_in_spare_batches(
text,
&mapping,
|ch, mapping| text_keycode(&mut client.borrow_mut(), mapping, ch),
|keycode, needs_shift| {
client.borrow_mut().record_recipient(keycode);
let mut delivered = Delivered::default();
for kc in needs_shift.then_some(shift_kc).into_iter().chain([keycode]) {
delivered.press(KEY_PRESS_EVENT, kc, || {
conn.xtest_fake_input(KEY_PRESS_EVENT, kc, 0, x11rb::NONE, 0, 0, 0)
})?;
}
conn.xtest_fake_input(KEY_RELEASE_EVENT, keycode, 0, x11rb::NONE, 0, 0, 0)?;
if needs_shift {
conn.xtest_fake_input(KEY_RELEASE_EVENT, shift_kc, 0, x11rb::NONE, 0, 0, 0)?;
}
conn.flush()?;
delivered.confirmed();
crate::interaction::pause(Duration::from_millis(KEY_DELAY_MS));
Ok(())
},
|| client.borrow_mut().release(),
)?;
// Round-trip so the server delivers the final character's key events before
// this short-lived connection drops (see send_key_xtest — keyboard XTEST
// events queued on a connection that closes immediately can be lost).
let _ = conn.get_input_focus()?.reply();
Ok(())
}
/// Press a named key (with optional modifiers) into whatever window holds X
/// keyboard focus, via the XTest extension. This is the REAL-input analogue of
/// [`send_key`]: XTest events are indistinguishable from physical input, so
/// GTK/Qt/Chromium/Firefox accept them — whereas the synthetic `XSendEvent`
/// path in [`send_key`] is silently dropped by those toolkits (they check the
/// `send_event` flag). Used by the `foreground` delivery rung, which activates
/// the target first, so XTest-to-focus lands on the intended widget.
///
/// Modifiers (e.g. `["ctrl"]`, `["ctrl","shift"]`) are pressed before and
/// released after the key. Modifier names resolve to their keysyms
/// (Control_L/Shift_L/Alt_L/Super_L), then to keycodes that are in the server's
/// modifier map, so the modifier mask actually engages. Sparse/headless keymaps
/// that lack a keysym borrow a spare keycode via
/// [`keycode_for_keysym`]; the returned guards restore the map on drop.
pub fn send_key_xtest(key: &str, modifiers: &[&str]) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (conn, _) = connect_x11_for_input()?;
let mut mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
// Resolve modifier keycodes first. Keep any spare-keycode remap guards alive
// until after the events are delivered (drop at end of fn).
let mut guards = Vec::new();
let mut mod_keycodes = Vec::new();
for m in modifiers {
let ks = key_name_to_keysym(m)?;
let (kc, guard) = keycode_for_keysym(&conn, &mut mapping, ks, m)?;
if let Some(g) = guard {
guards.push(g);
}
mod_keycodes.push(kc);
}
// Resolve the main key, SHIFT-AWARE. A keysym at the shifted level (slot 1)
// — e.g. '*', '+', '(' on a US layout, including the spelled-out names
// asterisk/plus/parenleft — must be typed with Shift held; a bare keycode
// press emits the slot-0 glyph instead (e.g. '*' -> '8', '+' -> '='). Prefer
// the slot-0/slot-1 lookup (`char_to_keycode_shift`); fall back to the
// spare-keycode remap (which binds the keysym across all levels, so no shift)
// only when the keysym is absent from the map.
let keysym = key_name_to_keysym(key)?;
let (keycode, needs_shift) = match char_to_keycode_shift(&mapping, keysym) {
Some(found) => found,
None => {
let (kc, guard) = keycode_for_keysym(&conn, &mut mapping, keysym, key)?;
if let Some(g) = guard {
guards.push(g);
}
(kc, false)
}
};
// Hold Shift around the key when it lives at the shifted level and the caller
// didn't already pass Shift as a modifier. Resolve the Shift keycode from the
// server's modifier map so the mask actually engages.
let shift_requested = modifiers.iter().any(|m| m.eq_ignore_ascii_case("shift"));
let auto_shift_kc = if needs_shift && !shift_requested {
let modmap = conn.get_modifier_mapping()?.reply()?;
let kpm = modmap.keycodes_per_modifier() as usize;
modmap
.keycodes
.get(..kpm)
.and_then(|s| s.iter().copied().find(|&k| k != 0))
} else {
None
};
// Press modifiers (+ auto-Shift), tap the key, release in reverse order.
let mut delivered = Delivered::default();
for kc in mod_keycodes
.iter()
.copied()
.chain(auto_shift_kc)
.chain([keycode])
{
delivered.press(KEY_PRESS_EVENT, kc, || {
conn.xtest_fake_input(KEY_PRESS_EVENT, kc, 0, x11rb::NONE, 0, 0, 0)
})?;
}
// Flush modifiers and key-down before measuring the delivered hold interval.
conn.flush()?;
crate::interaction::pause(Duration::from_millis(KEY_DELAY_MS));
conn.xtest_fake_input(KEY_RELEASE_EVENT, keycode, 0, x11rb::NONE, 0, 0, 0)?;
if let Some(sk) = auto_shift_kc {
conn.xtest_fake_input(KEY_RELEASE_EVENT, sk, 0, x11rb::NONE, 0, 0, 0)?;
}
for &kc in mod_keycodes.iter().rev() {
conn.xtest_fake_input(KEY_RELEASE_EVENT, kc, 0, x11rb::NONE, 0, 0, 0)?;
}
conn.flush()?;
delivered.confirmed();
// Round-trip so the server actually PROCESSES (delivers) the injected XTEST
// key events before this function returns and drops its short-lived
// connection. `flush()` only writes the requests to the socket; without a
// following reply-bearing request the connection can close before the server
// routes the KeyPress/KeyRelease to the focused window, and the events are
// dropped. Observed under Xtigervnc: identical raw `xtest_fake_input` calls
// deliver when the connection stays alive but vanish from this short-lived
// one — pointer events (send_click_xtest_desktop) survive, keyboard events do
// not. Unconditional (previously only ran for spare-keycode remaps).
let _ = conn.get_input_focus()?.reply();
if !guards.is_empty() {
// Spare-keycode remap: give the target a beat to translate the events
// under the temporary mapping before the guards restore it on drop.
sleep(Duration::from_millis(KEY_DELAY_MS));
}
drop(guards);
Ok(())
}
/// Screen-absolute click via the XTest extension — the desktop-target
/// foreground click. It warps the real pointer to `(x, y)` and injects a true
/// button press/release there, so the event lands on whatever window owns that
/// screen pixel (the Linux peer of the Windows `WindowFromPoint` + macOS
/// global-HID `CGEvent` desktop click).
///
/// XTest delivering to the focused / under-pointer window is precisely why the
/// *background* paths above use `XSendEvent` instead (see the module header) —
/// but it is exactly what desktop scope wants: the agent has located the target
/// by vision on the whole screen and issues a real screen-absolute pointer
/// click. `button` is an X button number (1=left, 2=middle, 3=right).
pub fn send_click_xtest_desktop(x: i32, y: i32, button: u8, count: usize) -> Result<()> {
send_click_xtest_desktop_with_modifiers(x, y, button, count, &[])
}
/// Real XTest click with physical modifier down/up transitions around the
/// pointer gesture. Used only after the caller selected foreground delivery.
pub fn send_click_xtest_desktop_with_modifiers(
x: i32,
y: i32,
button: u8,
count: usize,
modifiers: &[&str],
) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (conn, screen_num) = connect_x11_for_input()?;
let root = conn.setup().roots[screen_num].root;
let mut mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
let mut guards = Vec::new();
let mut modifier_keycodes = Vec::new();
for modifier in modifiers {
let keysym = key_name_to_keysym(modifier)?;
let (keycode, guard) = keycode_for_keysym(&conn, &mut mapping, keysym, modifier)?;
if let Some(guard) = guard {
guards.push(guard);
}
modifier_keycodes.push(keycode);
}
let mut delivered = Delivered::default();
let gesture_result = (|| -> Result<()> {
for &keycode in &modifier_keycodes {
delivered.press(KEY_PRESS_EVENT, keycode, || {
conn.xtest_fake_input(KEY_PRESS_EVENT, keycode, 0, x11rb::NONE, 0, 0, 0)
})?;
}
// Absolute pointer warp (MotionNotify, detail=0 => absolute) so the
// button events that follow are delivered at (x, y).
admitted(|| conn.xtest_fake_input(MOTION_NOTIFY_EVENT, 0, 0, root, x as i16, y as i16, 0))?;
let count = count.max(1);
for click_index in 0..count {
let press = delivered.press(BUTTON_PRESS_EVENT, button, || {
conn.xtest_fake_input(BUTTON_PRESS_EVENT, button, 0, root, x as i16, y as i16, 0)
})?;
// Confirm delivery before sleeping; buffering both edges produces a zero-ms click.
press.check()?;
crate::interaction::pause(Duration::from_millis(CLICK_DELAY_MS));
conn.xtest_fake_input(BUTTON_RELEASE_EVENT, button, 0, root, x as i16, y as i16, 0)?
.check()?;
delivered.released(BUTTON_RELEASE_EVENT, button);
if click_index + 1 < count {
// Keep the existing gap between completed click pairs.
crate::interaction::pause(Duration::from_millis(DOUBLE_CLICK_DELAY_MS));
}
}
Ok(())
})();
// Attempt all releases after a partial failure. Do not strand buttons or modifiers.
let release_result = delivered.release_held(&conn);
// Complete queued modifier releases before the short-lived connection closes,
// while preserving the primary gesture or cleanup error when one exists.
let completion_result = (|| -> Result<()> {
conn.get_input_focus()?.reply()?;
Ok(())
})();
if completion_result.is_ok() {
delivered.confirmed();
}
drop(guards);
gesture_result?;
release_result?;
completion_result?;
Ok(())
}
/// Move the real X11 pointer to a screen-absolute desktop coordinate.
pub fn send_move_xtest_desktop(x: i32, y: i32) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (conn, screen_num) = connect_x11_for_input()?;
let root = conn.setup().roots[screen_num].root;
admitted(|| conn.xtest_fake_input(MOTION_NOTIFY_EVENT, 0, 0, root, x as i16, y as i16, 0))?;
conn.flush()?;
let _ = conn.get_input_focus()?.reply();
Ok(())
}
/// Scroll the window under a screen-absolute point via real XTest wheel-button
/// events. X11 buttons 4/5 are vertical up/down and 6/7 horizontal left/right.
pub fn send_scroll_xtest_desktop(x: i32, y: i32, direction: &str, amount: usize) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let button = match direction {
"up" => 4,
"down" => 5,
"left" => 6,
"right" => 7,
other => anyhow::bail!("unknown desktop scroll direction: {other}"),
};
let (conn, screen_num) = connect_x11_for_input()?;
let root = conn.setup().roots[screen_num].root;
admitted(|| conn.xtest_fake_input(MOTION_NOTIFY_EVENT, 0, 0, root, x as i16, y as i16, 0))?;
let mut delivered = Delivered::default();
for _ in 0..amount.max(1) {
delivered.press(BUTTON_PRESS_EVENT, button, || {
conn.xtest_fake_input(BUTTON_PRESS_EVENT, button, 0, root, x as i16, y as i16, 0)
})?;
conn.xtest_fake_input(BUTTON_RELEASE_EVENT, button, 0, root, x as i16, y as i16, 0)?;
}
conn.flush()?;
delivered.confirmed();
let _ = conn.get_input_focus()?.reply();
Ok(())
}
#[allow(clippy::too_many_arguments)]
pub fn send_drag_xtest_desktop_with_modifiers(
from_x: i32,
from_y: i32,
to_x: i32,
to_y: i32,
button: u8,
duration_ms: u64,
steps: usize,
modifiers: &[&str],
) -> Result<()> {
use x11rb::protocol::xtest::ConnectionExt as _;
let (conn, screen_num) = connect_x11_for_input()?;
let root = conn.setup().roots[screen_num].root;
let mut mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
let mut guards = Vec::new();
let mut modifier_keycodes = Vec::new();
for modifier in modifiers {
let keysym = key_name_to_keysym(modifier)?;
let (keycode, guard) = keycode_for_keysym(&conn, &mut mapping, keysym, modifier)?;
if let Some(guard) = guard {
guards.push(guard);
}
modifier_keycodes.push(keycode);
}
let steps = steps.max(1);
let delay = duration_ms / steps as u64;
let mut delivered = Delivered::default();
let gesture_result = (|| -> Result<()> {
for &keycode in &modifier_keycodes {
delivered.press(KEY_PRESS_EVENT, keycode, || {
conn.xtest_fake_input(KEY_PRESS_EVENT, keycode, 0, x11rb::NONE, 0, 0, 0)
})?;
}
admitted(|| {
conn.xtest_fake_input(
MOTION_NOTIFY_EVENT,
0,
0,
root,
from_x as i16,
from_y as i16,
0,
)
})?;
delivered.press(BUTTON_PRESS_EVENT, button, || {
conn.xtest_fake_input(
BUTTON_PRESS_EVENT,
button,
0,
root,
from_x as i16,
from_y as i16,
0,
)
})?;
conn.flush()?;
for step in 1..=steps {
let t = step as f64 / steps as f64;
let x = from_x as f64 + (to_x - from_x) as f64 * t;
let y = from_y as f64 + (to_y - from_y) as f64 * t;
admitted(|| {
conn.xtest_fake_input(
MOTION_NOTIFY_EVENT,
0,
0,
root,
x.round() as i16,
y.round() as i16,
0,
)
})?;
conn.flush()?;
if delay > 0 {
crate::interaction::pause(Duration::from_millis(delay));
}
}
conn.xtest_fake_input(
BUTTON_RELEASE_EVENT,
button,
0,
root,
to_x as i16,
to_y as i16,
0,
)?;
delivered.released(BUTTON_RELEASE_EVENT, button);
Ok(())
})();
// Always attempt to release the button and every modifier queued above,
// including when a later motion request fails.
let mut cleanup_result = delivered.release_held(&conn);
if let Err(error) = conn.flush() {
cleanup_result = cleanup_result.and(Err(error.into()));
}
if cleanup_result.is_ok() {
delivered.confirmed();
}
let _ = conn.get_input_focus()?.reply();
drop(guards);
gesture_result?;
cleanup_result?;
Ok(())
}
/// Send a named key press to a window.
pub fn send_key(xid: u64, key: &str, modifiers: &[&str]) -> Result<()> {
send_key_to_target(xid, None, key, modifiers)
}
/// Send a named key to the deepest child at window-local coordinates without
/// activating the window. Coordinate keyboard actions use this so embedded
/// Chromium renderers receive the event on their input surface rather than on
/// the native top-level wrapper.
pub fn send_key_at(xid: u64, x: i32, y: i32, key: &str, modifiers: &[&str]) -> Result<()> {
send_key_to_target(xid, Some((x, y)), key, modifiers)
}
fn send_key_to_target(
xid: u64,
point: Option<(i32, i32)>,
key: &str,
modifiers: &[&str],
) -> Result<()> {
let (conn, _) = connect_x11_for_input()?;
let target = point
.map(|(x, y)| resolve_event_target(&conn, xid, x, y))
.transpose()?;
let window = target.map(|target| target.window).unwrap_or(xid as u32);
let root = conn.setup().roots[0].root;
// Resolve the named key to a keysym, then to a keycode. On sparse/headless
// keymaps (e.g. a minimal Xwayland :0) the keysym may have no keycode at all
// — historically this failed with "Keysym 0x.. not in keyboard map".
// `keycode_for_keysym` instead borrows a spare keycode and hands back a guard
// that restores the original mapping once the event has been delivered.
let keysym = key_name_to_keysym(key)?;
let mut mapping = conn.get_keyboard_mapping(8, 248)?.reply()?;
let (keycode, remap_guard) = keycode_for_keysym(&conn, &mut mapping, keysym, key)?;
// XSendEvent's state mask describes modifiers for one key event, but does
// not update Chromium's internal modifier state by itself. Emit the
// modifier transitions as part of the background chord so web handlers see
// the same ordered sequence as physical input without activating the
// target window.
let mut remap_guards = Vec::new();
let mut modifier_keycodes = Vec::new();
for modifier in modifiers {
let modifier_keysym = key_name_to_keysym(modifier)?;
let (modifier_keycode, guard) =
keycode_for_keysym(&conn, &mut mapping, modifier_keysym, modifier)?;
if let Some(guard) = guard {
remap_guards.push(guard);
}
modifier_keycodes.push((modifier_keycode, modifiers_to_state(&[*modifier])));
}
let send_key_event = |response_type, detail, state, event_mask| {
let event = KeyPressEvent {
response_type,
detail,
sequence: 0,
time: x11rb::CURRENT_TIME,
root,
event: window,
child: x11rb::NONE,
root_x: target.map(|target| target.root_x).unwrap_or(0),
root_y: target.map(|target| target.root_y).unwrap_or(0),
event_x: target.map(|target| target.local_x).unwrap_or(0),
event_y: target.map(|target| target.local_y).unwrap_or(0),
state,
same_screen: true,
};
admitted(|| conn.send_event(false, window, event_mask, event))
};
let mut state_bits = 0u16;
for &(modifier_keycode, modifier_mask) in &modifier_keycodes {
send_key_event(
KEY_PRESS_EVENT,
modifier_keycode,
KeyButMask::from(state_bits),
EventMask::KEY_PRESS,
)?;
state_bits |= u16::from(modifier_mask);
}
let state = KeyButMask::from(state_bits);
send_key_event(KEY_PRESS_EVENT, keycode, state, EventMask::KEY_PRESS)?;
// Otherwise X11 receives both transitions together after the sleep.
conn.flush()?;
crate::interaction::pause(Duration::from_millis(KEY_DELAY_MS));
send_key_event(KEY_RELEASE_EVENT, keycode, state, EventMask::KEY_RELEASE)?;
for &(modifier_keycode, modifier_mask) in modifier_keycodes.iter().rev() {
send_key_event(
KEY_RELEASE_EVENT,
modifier_keycode,
KeyButMask::from(state_bits),
EventMask::KEY_RELEASE,
)?;
state_bits &= !u16::from(modifier_mask);
}
// Deliver releases before closing the connection, even without a key remap.
conn.get_input_focus()?.reply()?;
// If we borrowed a spare keycode for this keysym, give the target client a
// moment to translate the synthetic event under the temporary mapping before
// we restore it. The keycode->keysym lookup is client-side, so restoring too
// eagerly would race delivery. A server round-trip (which only returns once
// our queued requests have been processed) plus a short settle keeps that
// race closed; the guard then reinstates the original keysyms on drop.
if remap_guard.is_some() || !remap_guards.is_empty() {
sleep(Duration::from_millis(KEY_DELAY_MS));
}
drop(remap_guard);
settle_synthetic_events(&conn);
Ok(())
}
/// Find the keycode that emits `keysym`, plus whether Shift must be held (the
/// keysym sits in the shifted column of the keyboard map). Prefers the
/// unshifted column when a keysym appears in both. Keysym for ASCII / Latin-1
/// is just the codepoint.
fn char_to_keycode_shift(mapping: &GetKeyboardMappingReply, keysym: u32) -> Option<(u8, bool)> {
let per = mapping.keysyms_per_keycode as usize;
if per == 0 {
return None;
}
for (i, syms) in mapping.keysyms.chunks(per).enumerate() {
if syms.first() == Some(&keysym) {
return Some(((8 + i) as u8, false));
}
if per > 1 && syms.get(1) == Some(&keysym) {
return Some(((8 + i) as u8, true));
}
}
None
}
/// Map a human key name (e.g. "Return", "F5", "a") to its X11 keysym. Pure name
/// resolution — no server interaction — split out from keycode lookup so the
/// keysym can be remapped onto a spare keycode when the keymap lacks it.
/// Resolve a key name in the shared X keysym vocabulary, or error on an
/// unknown name. Exposed crate-wide so input-adjacent paths (e.g. the
/// press_key terminal short-circuit gate) can test key identity against
/// this canonical mapping instead of a local string comparison.
pub(crate) fn key_name_to_keysym(key: &str) -> Result<u32> {
// Common X11 keysym names.
let keysym: u32 = match key.to_lowercase().as_str() {
"return" | "enter" => 0xFF0D,
"tab" => 0xFF09,
"escape" | "esc" => 0xFF1B,
"space" | " " => 0x0020,
"backspace" => 0xFF08,
"delete" | "del" => 0xFFFF,
"insert" | "ins" => 0xFF63,
"home" => 0xFF50,
"end" => 0xFF57,
"pageup" | "pgup" | "page_up" => 0xFF55,
"pagedown" | "pgdn" | "page_down" => 0xFF56,
"up" => 0xFF52,
"down" => 0xFF54,
"left" => 0xFF51,
"right" => 0xFF53,
"f1" => 0xFFBE,
"f2" => 0xFFBF,
"f3" => 0xFFC0,
"f4" => 0xFFC1,
"f5" => 0xFFC2,
"f6" => 0xFFC3,
"f7" => 0xFFC4,
"f8" => 0xFFC5,
"f9" => 0xFFC6,
"f10" => 0xFFC7,
"f11" => 0xFFC8,
"f12" => 0xFFC9,
"shift" => 0xFFE1,
"ctrl" | "control" => 0xFFE3,
"alt" => 0xFFE9,
"super" | "meta" | "win" | "cmd" => 0xFFEB,
"capslock" => 0xFFE5,
"numlock" => 0xFF7F,
// Common X keysym names for punctuation. The single-char branch below
// already resolves the literal glyph ("+", "=", "*", "/"), but callers
// that speak the X keysym-name vocabulary may pass the spelled-out name.
// For the ASCII range the keysym value equals the codepoint.
"plus" => 0x2B,
"minus" | "dash" => 0x2D,
"equal" | "equals" => 0x3D,
"asterisk" | "star" => 0x2A,
"slash" => 0x2F,
"backslash" => 0x5C,
"period" | "dot" => 0x2E,
"comma" => 0x2C,
"semicolon" => 0x3B,
"colon" => 0x3A,
"underscore" => 0x5F,
"parenleft" => 0x28,
"parenright" => 0x29,
s if s.len() == 1 => s.chars().next().unwrap() as u32,
_ => anyhow::bail!("Unknown key: {key}"),
};
Ok(keysym)
}
#[cfg(test)]
mod admission_tests {
use super::*;
#[test]
fn an_x11_send_past_its_action_is_refused_before_it_is_queued() {
let action = action::Action::new(Duration::from_secs(60));
let _bound = action::bind(action.clone());
assert_eq!(admitted(|| Ok::<_, anyhow::Error>(1)).unwrap(), 1);
action.abandon();
admitted(|| -> Result<()> { panic!("queued after abandon") }).unwrap_err();
let _expired = action::bind(action::Action::new(Duration::ZERO));
admitted(|| -> Result<()> { panic!("queued past the deadline") }).unwrap_err();
}
#[test]
fn a_drag_abandoned_after_its_press_still_releases_the_button() {
use std::io::{BufRead, BufReader};
struct Server(std::process::Child);
impl Drop for Server {
fn drop(&mut self) {
let _ = self.0.kill();
let _ = self.0.wait();
}
}
let mut server = Server(
std::process::Command::new("Xvfb")
.args(["-displayfd", "1", "-nolisten", "tcp"])
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::null())
.spawn()
.expect("install xvfb to run X11 input tests"),
);
let mut number = String::new();
BufReader::new(server.0.stdout.take().unwrap())
.read_line(&mut number)
.unwrap();
let display = format!(":{}", number.trim());
let _display = crate::test_env::x11_display(&display);
let action = action::Action::new(Duration::from_secs(60));
let dragging = {
let action = action.clone();
std::thread::spawn(move || {
let _bound = action::bind(action);
send_drag_xtest_desktop_with_modifiers(10, 10, 200, 200, 1, 3000, 30, &[])
})
};
let (observer, screen) = RustConnection::connect(Some(&display)).unwrap();
let root = observer.setup().roots[screen].root;
let held = || {
let mask = observer.query_pointer(root).unwrap().reply().unwrap().mask;
mask.contains(KeyButMask::BUTTON1)
};
let pressed_by = std::time::Instant::now() + Duration::from_secs(2);
while !held() {
assert!(
std::time::Instant::now() < pressed_by,
"the drag never pressed"
);
sleep(Duration::from_millis(20));
}
action.abandon();
dragging.join().unwrap().unwrap_err();
assert!(!held(), "the abandoned drag left button 1 held");
}
}
#[cfg(test)]
mod own_dialog_tests {
use super::*;
use std::io::{BufRead, BufReader};
use std::process::{Command, Stdio};
use x11rb::protocol::Event;
use x11rb::wrapper::ConnectionExt as _;
struct Server(std::process::Child);
impl Drop for Server {
fn drop(&mut self) {
let _ = self.0.kill();
let _ = self.0.wait();
}
}
fn set32(conn: &RustConnection, win: u32, name: &str, ty: AtomEnum, values: &[u32]) {
let atom = crate::x11::get_atom(conn, name).unwrap();
conn.change_property32(PropMode::REPLACE, win, atom, ty, values)
.unwrap();
}
#[test]
fn focus_restore_leaves_focus_on_a_dialog_the_app_opened() {
let mut server = Server(
Command::new("Xvfb")
.args(["-displayfd", "1", "-nolisten", "tcp"])
.stdout(Stdio::piped())
.spawn()
.expect("install xvfb to run focus tests"),
);
let mut number = String::new();
BufReader::new(server.0.stdout.take().unwrap())
.read_line(&mut number)
.unwrap();
let name = format!(":{}", number.trim());
let (conn, screen) = RustConnection::connect(Some(&name)).unwrap();
let root = conn.setup().roots[screen].root;
let window = |pid, transient| {
let win = conn.generate_id().unwrap();
conn.create_window(
0,
win,
root,
0,
0,
50,
50,
0,
WindowClass::INPUT_OUTPUT,
0,
&CreateWindowAux::new(),
)
.unwrap();
if pid != 0 {
set32(&conn, win, "_NET_WM_PID", AtomEnum::CARDINAL, &[pid]);
}
if transient != 0 {
set32(
&conn,
win,
"WM_TRANSIENT_FOR",
AtomEnum::WINDOW,
&[transient],
);
}
conn.map_window(win).unwrap();
win
};
let main = window(4242, 0);
let dialog = window(4242, main);
let sibling = window(4242, 0);
let foreign = window(4343, main);
let typed = window(4242, 0);
let pidless = window(0, main);
set32(
&conn,
typed,
"_NET_WM_WINDOW_TYPE",
AtomEnum::ATOM,
&[crate::x11::get_atom(&conn, "_NET_WM_WINDOW_TYPE_DIALOG").unwrap()],
);
assert!(is_own_dialog(&conn, 4242, dialog.into()));
assert!(is_own_dialog(&conn, 4242, typed.into()));
for win in [sibling, foreign, pidless] {
assert!(!is_own_dialog(&conn, 4242, win.into()));
}
conn.get_input_focus().unwrap().reply().unwrap();
let cname = std::ffi::CString::new(name.clone()).unwrap();
let display = open_named_display(cname.as_ptr()).unwrap();
// The WM honors every activation, except the first delayed request opens a dialog.
for delayed in [false, true] {
let (wm, _) = RustConnection::connect(Some(&name)).unwrap();
wm.change_window_attributes(
root,
&ChangeWindowAttributesAux::new().event_mask(EventMask::SUBSTRUCTURE_REDIRECT),
)
.unwrap()
.check()
.unwrap();
set32(
&conn,
root,
"_NET_ACTIVE_WINDOW",
AtomEnum::WINDOW,
&[sibling],
);
conn.set_input_focus(InputFocus::PARENT, sibling, 0u32)
.unwrap();
conn.get_input_focus().unwrap().reply().unwrap();
let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let done = stop.clone();
let thread = std::thread::spawn(move || {
let mut first = delayed;
while !done.load(std::sync::atomic::Ordering::Relaxed) {
match wm.poll_for_event().unwrap() {
Some(Event::ClientMessage(event)) => {
let target = if first { dialog } else { event.window };
first = false;
set32(&wm, root, "_NET_ACTIVE_WINDOW", AtomEnum::WINDOW, &[target]);
wm.set_input_focus(InputFocus::PARENT, target, 0u32)
.unwrap();
wm.flush().unwrap();
}
_ => std::thread::sleep(Duration::from_millis(1)),
}
}
});
restore_focus_state(
display,
&SavedFocus {
ewmh_active: Some(main.into()),
core_focus: 0,
core_revert_to: 0,
},
);
let focus = conn.get_input_focus().unwrap().reply().unwrap().focus;
stop.store(true, std::sync::atomic::Ordering::Relaxed);
thread.join().unwrap();
assert_eq!(focus, if delayed { dialog } else { main });
}
// A click that closed the saved window leaves nothing to re-activate.
let (wm, _) = RustConnection::connect(Some(&name)).unwrap();
wm.change_window_attributes(
root,
&ChangeWindowAttributesAux::new().event_mask(EventMask::SUBSTRUCTURE_REDIRECT),
)
.unwrap()
.check()
.unwrap();
set32(
&conn,
root,
"_NET_ACTIVE_WINDOW",
AtomEnum::WINDOW,
&[sibling],
);
conn.destroy_window(main).unwrap();
conn.get_input_focus().unwrap().reply().unwrap();
restore_focus_state(
display,
&SavedFocus {
ewmh_active: Some(main.into()),
core_focus: 0,
core_revert_to: 0,
},
);
let mut activations = 0;
while let Some(event) = wm.poll_for_event().unwrap() {
activations += usize::from(matches!(event, Event::ClientMessage(_)));
}
assert_eq!(activations, 0);
unsafe { x11::xlib::XCloseDisplay(display) };
}
}
#[cfg(test)]
mod key_name_alias_tests {
use super::{
char_to_keycode_shift, key_name_to_keysym, reserve_spare_keycode,
type_text_in_spare_batches, GetKeyboardMappingReply,
};
#[test]
fn text_batches_types_more_distinct_unmapped_characters_than_spares() {
use std::cell::RefCell;
struct Restore<'a>(u8, &'a RefCell<Vec<(&'static str, u8)>>);
impl Drop for Restore<'_> {
fn drop(&mut self) {
self.1.borrow_mut().push(("restore", self.0));
}
}
let mapping = GetKeyboardMappingReply {
keysyms_per_keycode: 2,
sequence: 0,
keysyms: vec!['a' as u32, 'A' as u32, 0, 0, 0, 0],
};
let log = RefCell::new(Vec::new());
type_text_in_spare_batches(
"a你好你世a世",
&mapping,
|ch, mapping| {
reserve_spare_keycode(
mapping,
super::mpx_keyboard::keysym_for_char(ch),
|spare, _, _, _| {
log.borrow_mut().push(("remap", spare));
Ok(Restore(spare, &log))
},
)
.map(|(keycode, guard)| (keycode, Some(guard)))
},
|keycode, _| {
log.borrow_mut().push(("send", keycode));
Ok(())
},
|| true,
)
.unwrap();
assert_eq!(
log.into_inner(),
[
("remap", 10),
("remap", 9),
("send", 8),
("send", 10),
("send", 9),
("send", 10),
("restore", 10),
("restore", 9),
("remap", 10),
("send", 10),
("send", 8),
("send", 10),
("restore", 10),
]
);
}
#[test]
fn spare_keycodes_skip_keycode_8() {
let mut mapping = GetKeyboardMappingReply {
keysyms_per_keycode: 2,
sequence: 0,
keysyms: vec![0, 0, 0, 0, 'a' as u32, 'A' as u32],
};
let mut reserve = || reserve_spare_keycode(&mut mapping, 0x100_4f60, |_, _, _, _| Ok(()));
assert_eq!(reserve().unwrap().0, 9);
assert_eq!(
reserve().unwrap_err().to_string(),
"no spare keycode available to remap keysym 0x1004F60"
);
}
#[test]
fn text_batches_do_not_count_keycode_8_as_spare() {
let mapping = GetKeyboardMappingReply {
keysyms_per_keycode: 2,
sequence: 0,
keysyms: vec![0, 0, 0, 0, 'a' as u32, 'A' as u32],
};
let mut events = Vec::new();
type_text_in_spare_batches(
"你好",
&mapping,
|ch, mapping| {
reserve_spare_keycode(
mapping,
super::mpx_keyboard::keysym_for_char(ch),
|_, _, _, _| Ok(()),
)
.map(|(keycode, guard)| (keycode, Some(guard)))
},
|keycode, _| {
events.push(keycode);
Ok(())
},
|| true,
)
.unwrap();
assert_eq!(events, [9, 9]);
}
#[test]
fn text_batches_reports_progress_when_a_later_batch_fails() {
let mapping = GetKeyboardMappingReply {
keysyms_per_keycode: 2,
sequence: 0,
keysyms: vec!['a' as u32, 'A' as u32, 0, 0],
};
let mut events = Vec::new();
let error = type_text_in_spare_batches::<()>(
"你a好",
&mapping,
|ch, _| match ch {
'你' => Ok((9, None)),
_ => anyhow::bail!("keymap changed"),
},
|keycode, _| {
events.push(keycode);
Ok(())
},
|| true,
)
.unwrap_err();
assert_eq!(error.to_string(), "typed 2 of 3 characters: keymap changed");
assert_eq!(events, [9, 8]);
}
#[test]
fn text_batches_stop_before_rebinding_keycodes_the_client_has_not_read() {
let mapping = GetKeyboardMappingReply {
keysyms_per_keycode: 2,
sequence: 0,
keysyms: vec!['a' as u32, 'A' as u32, 0, 0],
};
for (text, result) in [
("你", Ok(vec![9])),
("你好", Err("typed 1 of 2 characters: the client has not confirmed reading the keys on the spare keycodes the next characters need")),
] {
let mut events = Vec::new();
let typed = type_text_in_spare_batches(
text,
&mapping,
|ch, mapping| {
reserve_spare_keycode(
mapping,
super::mpx_keyboard::keysym_for_char(ch),
|_, _, _, _| Ok(()),
)
.map(|(keycode, guard)| (keycode, Some(guard)))
},
|keycode, _| {
events.push(keycode);
Ok(())
},
|| false,
)
.map(|()| events)
.map_err(|error| error.to_string());
assert_eq!(typed, result.map_err(String::from), "{text}");
}
}
#[test]
fn shifted_column_glyphs_need_shift_and_base_glyphs_do_not() {
let per = 2usize;
let mut keysyms = vec![0u32; (248 - 8 + 1) * per];
let mut set = |keycode: usize, syms: [u32; 2]| {
let idx = (keycode - 8) * per;
keysyms[idx..idx + per].copy_from_slice(&syms);
};
set(43, [0x68, 0x48]);
set(11, [0x32, 0x40]);
let mapping = GetKeyboardMappingReply {
keysyms_per_keycode: per as u8,
sequence: 0,
keysyms,
};
for (ch, keycode, needs_shift) in [
('H', 43, true),
('@', 11, true),
('h', 43, false),
('2', 11, false),
] {
assert_eq!(
char_to_keycode_shift(&mapping, ch as u32),
Some((keycode, needs_shift)),
"{ch:?}"
);
}
}
#[test]
fn common_key_name_aliases_resolve_to_the_expected_keysym() {
// Page_Up / Page_Down: the underscore form is the literal X11 keysym
// name and a common cross-platform prompt spelling; only the
// no-underscore "pageup"/"pgup" aliases existed before.
assert_eq!(key_name_to_keysym("Page_Up").unwrap(), 0xFF55);
assert_eq!(key_name_to_keysym("page_up").unwrap(), 0xFF55);
assert_eq!(
key_name_to_keysym("Page_Up").unwrap(),
key_name_to_keysym("pageup").unwrap()
);
assert_eq!(key_name_to_keysym("Page_Down").unwrap(), 0xFF56);
assert_eq!(
key_name_to_keysym("Page_Down").unwrap(),
key_name_to_keysym("pgdn").unwrap()
);
// "cmd": common cross-platform prompt name for the Super/Meta/Windows
// key; must alias to the same keysym as "super"/"meta"/"win".
assert_eq!(key_name_to_keysym("cmd").unwrap(), 0xFFEB);
assert_eq!(
key_name_to_keysym("cmd").unwrap(),
key_name_to_keysym("super").unwrap()
);
}
}
/// A keycode we have *temporarily* rebound to host a keysym that is absent from
/// the current X keyboard map (sparse/headless keymaps such as a minimal
/// Xwayland). On drop it reinstates the keycode's original keysyms so the
/// server's mapping is left exactly as we found it. The remap goes through
/// `XChangeKeyboardMapping` on a spare keycode.
pub(crate) struct RemappedKeycode<'a> {
conn: &'a RustConnection,
keycode: u8,
keysyms_per_keycode: u8,
original_keysyms: Vec<u32>,
}
impl Drop for RemappedKeycode<'_> {
fn drop(&mut self) {
let _ = self.conn.change_keyboard_mapping(
1,
self.keycode,
self.keysyms_per_keycode,
&self.original_keysyms,
);
let _ = self.conn.get_input_focus().map(|cookie| cookie.reply());
}
}
/// Whether a text may borrow `keycode`: every keysym slot is NoSymbol (0) — i.e.
/// completely unused — so borrowing it cannot clobber a real key. Keycode 8 is
/// evdev KEY_RESERVED, which a virtual keyboard cannot send, so it is never
/// borrowed.
fn is_spare_keycode(keycode: usize, keysyms: &[u32]) -> bool {
keycode > 8 && keysyms.iter().all(|&s| s == 0)
}
/// Reserve a fully unused keycode for `keysym`, calling `bind` before updating
/// the local mapping. Returns the keycode and the value produced by `bind`.
fn reserve_spare_keycode<G>(
mapping: &mut GetKeyboardMappingReply,
keysym: u32,
mut bind: impl FnMut(u8, u8, &[u32], &[u32]) -> Result<G>,
) -> Result<(u8, G)> {
let per = mapping.keysyms_per_keycode as usize;
if per == 0 {
bail!("empty keyboard mapping; cannot remap keysym 0x{keysym:X}");
}
// Scan high-to-low: high keycodes are far likelier to be free than the
// low, populated ones.
let spare = mapping
.keysyms
.chunks(per)
.enumerate()
.rev()
.find(|&(i, syms)| is_spare_keycode(8 + i, syms))
.map(|(i, _)| (8 + i) as u8)
.ok_or_else(|| anyhow!("no spare keycode available to remap keysym 0x{keysym:X}"))?;
// Snapshot the original keysyms (all NoSymbol, but capture them so restore is
// exact regardless), then bind the requested keysym across every column of
// the borrowed keycode so it resolves irrespective of modifier state/group.
let idx = (spare as usize - 8) * per;
let original_keysyms = mapping.keysyms[idx..idx + per].to_vec();
let new_keysyms = vec![keysym; per];
let guard = bind(spare, per as u8, &original_keysyms, &new_keysyms)?;
mapping.keysyms[idx..idx + per].copy_from_slice(&new_keysyms);
Ok((spare, guard))
}
/// Resolve `keysym` to a keycode usable in a synthetic key event. First scans
/// the existing keyboard mapping; if no keycode emits the keysym (common on
/// sparse headless keymaps like a minimal Xwayland) it borrows a spare keycode
/// and remaps it, returning a guard that restores the original mapping on drop.
/// The guard is `None` when the keysym was already present (no cleanup needed).
fn keycode_for_keysym<'a>(
conn: &'a RustConnection,
mapping: &mut GetKeyboardMappingReply,
keysym: u32,
key: &str,
) -> Result<(u8, Option<RemappedKeycode<'a>>)> {
let per = mapping.keysyms_per_keycode as usize;
if per > 0 {
for (i, syms) in mapping.keysyms.chunks(per).enumerate() {
if syms.contains(&keysym) {
return Ok(((8 + i) as u8, None));
}
}
}
// Not in the map — fall back to remapping a spare keycode.
let (keycode, guard) = reserve_spare_keycode(mapping, keysym, |spare, per, original, new| {
conn.change_keyboard_mapping(1, spare, per, new)?;
let guard = RemappedKeycode {
conn,
keycode: spare,
keysyms_per_keycode: per,
original_keysyms: original.to_vec(),
};
let _ = conn.get_input_focus()?.reply();
Ok(guard)
})
.with_context(|| {
format!("Keysym 0x{keysym:X} not in keyboard map for key '{key}' and no spare keycode could be remapped")
})?;
Ok((keycode, Some(guard)))
}
fn text_keycode(
client: &mut TextClient<'_>,
mapping: &mut GetKeyboardMappingReply,
ch: char,
) -> Result<(u8, Option<()>)> {
let keysym = mpx_keyboard::keysym_for_char(ch);
let (keycode, guard) = keycode_for_keysym(client.conn, mapping, keysym, &ch.to_string())?;
let Some(guard) = guard else {
return Ok((keycode, None));
};
client.borrowed.push(guard);
if let Some(window) = client.recipient() {
client.ping(window);
}
Ok((keycode, Some(())))
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum ClientSync {
Confirmed,
Unsupported,
Unanswered,
}
struct TextClient<'a> {
conn: &'a RustConnection,
target: Option<Window>,
borrowed: Vec<RemappedKeycode<'a>>,
sent: Vec<Window>,
unanswered: Vec<Window>,
}
impl<'a> TextClient<'a> {
fn new(conn: &'a RustConnection, target: Option<Window>) -> Self {
Self {
conn,
target,
borrowed: Vec::new(),
sent: Vec::new(),
unanswered: Vec::new(),
}
}
fn recipient(&self) -> Option<Window> {
self.target.or_else(|| {
let cookie = self.conn.get_input_focus().ok()?;
cookie.reply().ok().map(|reply| reply.focus)
})
}
fn record_recipient(&mut self, keycode: u8) {
if !self.borrowed.iter().any(|guard| guard.keycode == keycode) {
return;
}
if let Some(window) = self.recipient() {
if !self.sent.contains(&window) {
self.sent.push(window);
}
}
}
fn ping(&mut self, window: Window) {
if self.unanswered.contains(&window) {
return;
}
if sync_client(self.conn, Some(window)) == ClientSync::Unanswered {
self.unanswered.push(window);
}
}
fn release(&mut self) -> bool {
let sent = std::mem::take(&mut self.sent);
for &window in &sent {
self.ping(window);
}
self.borrowed.clear();
let unanswered = std::mem::take(&mut self.unanswered);
!sent.iter().any(|window| unanswered.contains(window))
}
}
impl Drop for TextClient<'_> {
fn drop(&mut self) {
self.release();
}
}
fn sync_client(conn: &RustConnection, window: Option<Window>) -> ClientSync {
let atom = |name: &str| {
conn.intern_atom(false, name.as_bytes())
.ok()?
.reply()
.ok()
.map(|reply| reply.atom)
};
let (Some(window), Some(protocols), Some(ping)) =
(window, atom("WM_PROTOCOLS"), atom("_NET_WM_PING"))
else {
return ClientSync::Unsupported;
};
let Some(window) = ping_window(conn, window, protocols, ping) else {
return ClientSync::Unsupported;
};
let root = conn.setup().roots[0].root;
let listen = ChangeWindowAttributesAux::new().event_mask(EventMask::SUBSTRUCTURE_NOTIFY);
let serial = PING_SERIAL.fetch_add(1, Ordering::Relaxed).max(1);
let event = ClientMessageEvent::new(32, window, protocols, [ping, serial, window, 0, 0]);
if conn.change_window_attributes(root, &listen).is_err()
|| conn
.send_event(false, window, EventMask::NO_EVENT, event)
.is_err()
|| conn.flush().is_err()
{
return ClientSync::Unanswered;
}
let deadline = std::time::Instant::now() + PING_TIMEOUT;
while std::time::Instant::now() < deadline {
match conn.poll_for_event() {
Ok(Some(x11rb::protocol::Event::ClientMessage(pong)))
if pong.type_ == protocols
&& pong.data.as_data32()[..3] == [ping, serial, window] =>
{
return ClientSync::Confirmed;
}
Ok(Some(_)) => {}
Ok(None) => sleep(Duration::from_millis(1)),
Err(_) => return ClientSync::Unanswered,
}
}
ClientSync::Unanswered
}
fn ping_window(
conn: &RustConnection,
focus: Window,
protocols: Atom,
ping: Atom,
) -> Option<Window> {
if focus == x11rb::NONE || focus == u32::from(InputFocus::POINTER_ROOT) {
return None;
}
let client = !conn.setup().resource_id_mask;
let mut window = focus;
while window != x11rb::NONE && window & client == focus & client {
let protocols = conn
.get_property(false, window, protocols, AtomEnum::ATOM, 0, 64)
.ok()?
.reply()
.ok()?;
if protocols
.value32()
.is_some_and(|mut atoms| atoms.any(|atom| atom == ping))
{
return Some(window);
}
window = conn.query_tree(window).ok()?.reply().ok()?.parent;
}
None
}
fn modifiers_to_state(modifiers: &[&str]) -> KeyButMask {
let mut state = 0u16;
for m in modifiers {
match m.to_lowercase().as_str() {
"shift" => state |= u16::from(KeyButMask::SHIFT),
"ctrl" | "control" => state |= u16::from(KeyButMask::CONTROL),
"alt" | "mod1" => state |= u16::from(KeyButMask::MOD1),
"super" | "mod4" | "win" | "meta" => state |= u16::from(KeyButMask::MOD4),
_ => {}
}
}
KeyButMask::from(state)
}
/// Inject text into a Tk window via Tk's `send` command — the Tk-specific
/// override for focus-free writes (Tk has no AT-SPI bridge). Requires the target
/// app to have registered itself with a known name via `tk appname <name>`.
/// Returns Ok(true) if text was sent, Ok(false) if the target isn't reachable
/// (not a Tk app or `wish` unavailable), Err on a send failure.
pub fn inject_tk_send(text: &str) -> Result<bool> {
use std::io::Write;
// Escape the text for safe Tcl interpolation (braces for literal strings).
// Tcl's `send` command: `send <target-app-name> <tcl-command>`.
// We target "cua-tk-target" (the name the test app registers with) and
// insert at the entry widget's current cursor position.
let tcl_text = text
.replace("\\", "\\\\")
.replace("{", "\\{")
.replace("}", "\\}");
// Tk's `send` is synchronous: it blocks the sender until the *target's* Tcl
// event loop services the request and replies. If the target is wedged, or
// the X server refuses `send` (SECURITY ext / xauth mismatch), it can block
// forever. Guard against that two ways:
// 1. A Tcl-level `after` timer that force-exits wish if the send hasn't
// completed in time. We issue the write with `send -async` so the local
// event loop stays live to fire the timer, then `vwait` on a flag.
// 2. A Rust-level wall-clock kill below, so even a totally wedged wish
// (e.g. blocked before reaching the event loop) can't hang the driver.
let tcl_script = format!(
r#"set ::done 0
set ::rc 0
after 5000 {{ set ::rc 2; set ::done 1 }}
if {{[catch {{send -async cua-tk-target {{.entry insert insert {{{}}}}}}} err]}} {{
puts stderr "tk send failed: $err"
exit 1
}}
after 500 {{ set ::done 1 }}
vwait ::done
if {{$::rc == 2}} {{
puts stderr "tk send timed out"
exit 1
}}
exit 0"#,
tcl_text
);
// Try to spawn wish (Tk's shell). If it's not available, this isn't a
// Tk-based environment and we should fall back to XSendEvent.
let mut child = match std::process::Command::new("wish")
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::piped())
.spawn()
{
Ok(c) => c,
Err(_) => return Ok(false),
};
if let Some(mut stdin) = child.stdin.take() {
// Ignore write errors: if wish already exited we observe it via wait().
let _ = stdin.write_all(tcl_script.as_bytes());
// stdin drops here → EOF, so wish runs the script to completion.
}
// Wall-clock backstop: poll for exit and hard-kill if wish overruns the
// deadline. Guarantees the driver task can never hang on a blocked Tk send,
// regardless of whether the Tcl-level timer fired.
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(15);
loop {
match child.try_wait()? {
Some(status) => {
let mut stderr = String::new();
if let Some(mut err) = child.stderr.take() {
use std::io::Read;
let _ = err.read_to_string(&mut stderr);
}
if status.success() {
return Ok(true);
}
// Target not registered or send timed out → not a usable Tk
// target; let the caller fall back to XSendEvent.
if stderr.contains("application named")
|| stderr.contains("no registered")
|| stderr.contains("timed out")
{
return Ok(false);
}
anyhow::bail!("wish send failed: {}", stderr);
}
None => {
if std::time::Instant::now() >= deadline {
let _ = child.kill();
let _ = child.wait();
return Ok(false);
}
std::thread::sleep(std::time::Duration::from_millis(50));
}
}
}
}
#[cfg(test)]
mod path_tests {
use super::{
click_event_target, create_uinput_pointer, ensure_master_pointer_for_session,
guarded_uinput_creation, is_uinput_unavailable, kde_x11_uinput_hotplug_is_unsafe,
master_pointer_name, modifiers_to_state, mpx_op_guard, normalize_uinput_device_name,
path_cumulative, point_on_path, real_pointer_capabilities_available, sample_function,
slave_pointer_name, EVDEV_UINPUT_NAME_MAX_BYTES, UINPUT_POINTER_SUFFIX,
};
use x11rb::protocol::xproto::{EventMask, KeyButMask};
/// Regression for the `XSetErrorHandler` swap race: every caller that
/// could swap the process-global X11 error handler while an MPX
/// operation is mid-swap (`send_virtual_pointer_*`, `deliver`, and now
/// `x11_activate_window_persistent`) must take `MPX_OP_LOCK` first. This
/// doesn't touch X11 (no display in CI), but proves the lock itself is
/// exclusive and not reentrant-by-accident: a second `mpx_op_guard` call
/// blocks until the first is dropped, exactly the property the handler
/// swap needs to be race-free.
#[test]
fn mpx_op_guard_is_mutually_exclusive() {
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
let entered_second = Arc::new(AtomicBool::new(false));
let first = mpx_op_guard("test-a");
let entered_second_clone = entered_second.clone();
let handle = std::thread::spawn(move || {
let _second = mpx_op_guard("test-b");
entered_second_clone.store(true, Ordering::SeqCst);
});
// The second guard cannot have been acquired yet — it is blocked on
// the lock we are still holding.
std::thread::sleep(std::time::Duration::from_millis(50));
assert!(
!entered_second.load(Ordering::SeqCst),
"second guard acquired while the first was still held"
);
drop(first);
handle.join().unwrap();
assert!(entered_second.load(Ordering::SeqCst));
}
#[test]
fn synthetic_click_keeps_release_on_press_recipient() {
let path = [
(
10,
394,
220,
EventMask::BUTTON_PRESS | EventMask::BUTTON_RELEASE,
),
(11, 24, 30, EventMask::BUTTON_PRESS),
(12, 6, 8, EventMask::BUTTON_RELEASE),
];
assert_eq!(click_event_target(&path), (11, 24, 30));
}
#[test]
fn synthetic_click_uses_deepest_common_target_for_both_events() {
let path = [
(
10,
394,
220,
EventMask::BUTTON_PRESS | EventMask::BUTTON_RELEASE,
),
(
11,
24,
30,
EventMask::BUTTON_PRESS | EventMask::BUTTON_RELEASE,
),
(12, 6, 8, EventMask::NO_EVENT),
];
assert_eq!(click_event_target(&path), (11, 24, 30));
}
#[test]
fn synthetic_click_preserves_recipient_local_coordinates_and_event_fallback() {
let path = [
(10, 394, 220, EventMask::BUTTON_PRESS),
(11, 24, 30, EventMask::NO_EVENT),
(12, 6, 8, EventMask::NO_EVENT),
];
assert_eq!(click_event_target(&path), (10, 394, 220));
}
#[test]
fn click_modifier_state_combines_canonical_names_and_aliases() {
let state = modifiers_to_state(&["ctrl", "shift", "meta"]);
assert!(state.contains(KeyButMask::CONTROL));
assert!(state.contains(KeyButMask::SHIFT));
assert!(state.contains(KeyButMask::MOD4));
assert!(!state.contains(KeyButMask::MOD1));
assert_eq!(
modifiers_to_state(&["control", "alt"]),
KeyButMask::from(u16::from(KeyButMask::CONTROL) | u16::from(KeyButMask::MOD1))
);
}
#[test]
fn idle_reaper_selects_only_sessions_past_the_ttl() {
use super::{stale_cursor_ids, MPX_IDLE_TTL};
let now = std::time::Instant::now();
let mut last_use = std::collections::HashMap::new();
last_use.insert("fresh".to_owned(), now);
last_use.insert(
"old".to_owned(),
now - (MPX_IDLE_TTL + std::time::Duration::from_secs(60)),
);
last_use.insert("edge".to_owned(), now - MPX_IDLE_TTL);
let mut stale = stale_cursor_ids(&last_use, now, MPX_IDLE_TTL);
stale.sort();
assert_eq!(stale, vec!["edge".to_owned(), "old".to_owned()]);
assert!(stale_cursor_ids(&std::collections::HashMap::new(), now, MPX_IDLE_TTL).is_empty());
}
fn popup_removal_due(cursor_id: &str) -> Option<Option<std::time::Instant>> {
super::mpx_click_popups()
.lock()
.unwrap()
.get(cursor_id)
.map(|popups| popups.removal_due)
}
fn mpx_op_lock() -> std::sync::MutexGuard<'static, ()> {
super::MPX_OP_LOCK
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
fn end_session_after_click(cursor_id: &str, opened: &[u64]) {
super::mark_mpx_use(cursor_id);
super::track_click_popups(cursor_id, opened.iter().copied());
super::forget_master_pointer_locked(cursor_id);
}
#[test]
fn a_second_end_leaves_the_master_to_the_pending_popup_waiter() {
let _op = mpx_op_lock();
let cursor_id = "popup-test-double-end";
end_session_after_click(cursor_id, &[0x7fff_0001]);
let due = popup_removal_due(cursor_id);
assert!(matches!(due, Some(Some(_))));
super::forget_master_pointer_locked(cursor_id);
assert_eq!(popup_removal_due(cursor_id), due);
assert!(!super::mpx_last_use()
.lock()
.unwrap()
.contains_key(cursor_id));
}
#[test]
fn an_end_without_tracked_popups_removes_the_master_at_once() {
let _op = mpx_op_lock();
end_session_after_click("popup-test-no-popup", &[]);
assert_eq!(popup_removal_due("popup-test-no-popup"), None);
assert!(!super::mpx_last_use()
.lock()
.unwrap()
.contains_key("popup-test-no-popup"));
}
#[test]
fn a_click_that_opens_nothing_keeps_earlier_tracked_popups() {
let _op = mpx_op_lock();
let cursor_id = "popup-test-union";
super::track_click_popups(cursor_id, [5, 3]);
super::track_click_popups(cursor_id, []);
super::track_click_popups(cursor_id, [3, 7]);
let windows = super::mpx_click_popups().lock().unwrap()[cursor_id]
.windows
.clone();
assert_eq!(windows, vec![3, 5, 7]);
}
#[test]
fn reusing_an_ended_session_disowns_its_popup_waiter() {
let _op = mpx_op_lock();
let cursor_id = "popup-test-reuse";
end_session_after_click(cursor_id, &[0x7fff_0003]);
assert!(matches!(popup_removal_due(cursor_id), Some(Some(_))));
super::mark_mpx_use(cursor_id);
assert_eq!(popup_removal_due(cursor_id), Some(None));
super::forget_master_pointer_locked(cursor_id);
assert!(matches!(popup_removal_due(cursor_id), Some(Some(_))));
}
#[test]
fn a_popup_that_remaps_during_the_quiet_wait_keeps_the_master_until_the_deadline() {
use super::{popup_wait_over, MPX_POPUP_QUIET};
let now = std::time::Instant::now();
let deadline = now + std::time::Duration::from_secs(60);
let quiet_elapsed = Some(now - MPX_POPUP_QUIET * 2);
let mut quiet = quiet_elapsed;
assert!(!popup_wait_over(Some(true), &mut quiet, deadline));
assert_eq!(quiet, None);
assert!(!popup_wait_over(Some(false), &mut quiet, deadline));
assert!(quiet.is_some());
let mut quiet = quiet_elapsed;
assert!(!popup_wait_over(None, &mut quiet, deadline));
assert_eq!(quiet, None);
let mut quiet = quiet_elapsed;
assert!(popup_wait_over(Some(false), &mut quiet, deadline));
assert!(popup_wait_over(Some(true), &mut None, now));
}
#[test]
fn a_popup_belongs_to_the_live_session_whose_click_saw_it_appear() {
use super::{popup_owner, ClickPopups};
use std::collections::HashMap;
let appeared = HashMap::from([
(
"ctx".to_owned(),
ClickPopups {
windows: vec![25165852],
removal_due: None,
},
),
("combo".to_owned(), ClickPopups::default()),
]);
let live = |_: &str| true;
assert_eq!(
popup_owner(25165852, &appeared, live).as_deref(),
Some("ctx")
);
assert_eq!(popup_owner(25165982, &appeared, live), None);
assert_eq!(
popup_owner(25165852, &appeared, |id: &str| id != "ctx"),
None
);
}
#[test]
fn a_click_that_sees_a_popup_appear_takes_it_from_other_sessions() {
use super::{mpx_click_popups, popup_owner, track_click_popups};
let _op = mpx_op_lock();
track_click_popups("popup-reuse-a", [77_001, 77_002]);
track_click_popups("popup-reuse-b", [77_001]);
let mut tracked = mpx_click_popups().lock().unwrap();
assert_eq!(tracked["popup-reuse-a"].windows, vec![77_002]);
assert_eq!(
popup_owner(77_001, &tracked, |_: &str| true).as_deref(),
Some("popup-reuse-b")
);
tracked.remove("popup-reuse-a");
tracked.remove("popup-reuse-b");
}
#[test]
fn keys_for_a_popup_neither_stamp_nor_recreate_the_owner_pair() {
use super::{
mpx_last_use, mpx_pointers, popup_owner_guard, MasterPointerIds, PopupOwnerGone,
};
let gone = popup_owner_guard(90_001).unwrap_err();
assert!(gone.is::<PopupOwnerGone>());
super::track_click_popups("popup-owner-live", [90_001]);
mpx_pointers().lock().unwrap().insert(
"popup-owner-live".to_owned(),
MasterPointerIds {
pointer_id: 90,
keyboard_id: 91,
_slave_pointer_id: 92,
slave_keyboard_id: None,
},
);
assert_eq!(popup_owner_guard(90_001).unwrap().1, "popup-owner-live");
super::track_click_popups("popup-owner-next", [90_001]);
assert!(popup_owner_guard(90_001)
.unwrap_err()
.is::<PopupOwnerGone>());
mpx_pointers().lock().unwrap().insert(
"popup-owner-next".to_owned(),
MasterPointerIds {
pointer_id: 93,
keyboard_id: 94,
_slave_pointer_id: 95,
slave_keyboard_id: None,
},
);
assert_eq!(popup_owner_guard(90_001).unwrap().1, "popup-owner-next");
mpx_pointers().lock().unwrap().remove("popup-owner-next");
mpx_pointers().lock().unwrap().remove("popup-owner-live");
let mut tracked = super::mpx_click_popups().lock().unwrap();
tracked.remove("popup-owner-live");
tracked.remove("popup-owner-next");
drop(tracked);
let last_use = mpx_last_use().lock().unwrap();
assert!(!last_use.contains_key("popup-owner-live"));
assert!(!last_use.contains_key("popup-owner-next"));
}
#[test]
fn slave_pointer_name_fits_evdev_uinput_limit() {
for cursor_id in ["m".repeat(200), "cursor-鼠".repeat(50)] {
let name = slave_pointer_name(&master_pointer_name(&cursor_id));
assert!(
name.len() <= 78,
"evdev 0.12 requires uinput names to be at most 78 bytes, got {}",
name.len()
);
}
let cursor_id = "same-long-cursor".repeat(20);
let first = slave_pointer_name(&master_pointer_name(&cursor_id));
let second = slave_pointer_name(&master_pointer_name(&cursor_id));
assert_ne!(first, second, "truncation must retain the unique nonce");
assert!(first.ends_with(UINPUT_POINTER_SUFFIX));
assert!(second.ends_with(UINPUT_POINTER_SUFFIX));
}
#[test]
fn uinput_name_normalization_covers_byte_boundaries_and_multibyte_text() {
let exact = "a".repeat(EVDEV_UINPUT_NAME_MAX_BYTES);
assert_eq!(normalize_uinput_device_name(&exact), exact);
let overlong_ascii = "a".repeat(EVDEV_UINPUT_NAME_MAX_BYTES + 1);
assert_eq!(
normalize_uinput_device_name(&overlong_ascii),
"a".repeat(EVDEV_UINPUT_NAME_MAX_BYTES)
);
let exact_multibyte = format!("{}鼠", "a".repeat(75));
assert_eq!(exact_multibyte.len(), EVDEV_UINPUT_NAME_MAX_BYTES);
assert_eq!(
normalize_uinput_device_name(&exact_multibyte),
exact_multibyte
);
let split_multibyte = format!("{}鼠", "a".repeat(77));
let normalized = normalize_uinput_device_name(&split_multibyte);
assert_eq!(normalized, "a".repeat(77));
assert!(normalized.is_char_boundary(normalized.len()));
assert_eq!(
normalize_uinput_device_name("CUA\0pointer\n"),
"CUA_pointer_"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn uinput_creation_panic_is_contained_and_daemon_worker_remains_usable() {
let failed = tokio::task::spawn_blocking(|| {
guarded_uinput_creation::<()>("panic", |_| panic!("synthetic evdev panic"))
})
.await
.expect("the blocking worker must not unwind");
let error = failed.expect_err("the panic must become an error");
assert!(is_uinput_unavailable(&error));
assert!(error.to_string().contains("device creation panicked"));
let subsequent = tokio::task::spawn_blocking(|| {
guarded_uinput_creation("subsequent", |name| Ok(name.to_owned()))
})
.await
.expect("the runtime must remain usable after the contained panic")
.expect("a subsequent device operation must succeed");
assert_eq!(subsequent, "subsequent");
}
#[test]
fn uinput_creation_error_is_stably_typed() {
let error =
guarded_uinput_creation::<()>("failure", |_| anyhow::bail!("permission denied"))
.expect_err("the injected builder error must be returned");
assert!(is_uinput_unavailable(&error));
assert_eq!(
error.to_string(),
"Linux uinput device unavailable: permission denied"
);
}
#[test]
#[ignore = "requires a writable /dev/uinput device"]
fn real_uinput_accepts_normalized_overlong_multibyte_name() {
let overlong_name = format!("CUA {}{UINPUT_POINTER_SUFFIX}", "鼠".repeat(100));
let device = create_uinput_pointer(&overlong_name)
.expect("normalized device name should create a real uinput pointer");
drop(device);
}
#[test]
fn real_pointer_capabilities_require_uinput_access() {
assert!(real_pointer_capabilities_available(
true, false, true, false
));
assert!(!real_pointer_capabilities_available(
true, false, false, false
));
assert!(!real_pointer_capabilities_available(
false, false, true, false
));
assert!(!real_pointer_capabilities_available(
true, true, true, false
));
assert!(!real_pointer_capabilities_available(
true, false, true, true
));
}
#[test]
fn kde_x11_sessions_disable_uinput_pointer_hotplug() {
assert!(kde_x11_uinput_hotplug_is_unsafe(
Some("x11"),
Some("KDE"),
None,
None,
None,
Some(":0"),
None,
));
assert!(kde_x11_uinput_hotplug_is_unsafe(
Some("x11"),
Some("KDE"),
None,
None,
None,
Some(":0"),
Some("wayland-0"),
));
assert!(kde_x11_uinput_hotplug_is_unsafe(
None,
None,
Some("plasma"),
None,
Some("true"),
Some(":1"),
None,
));
assert!(!kde_x11_uinput_hotplug_is_unsafe(
Some("wayland"),
Some("KDE"),
None,
None,
Some("true"),
Some(":0"),
Some("wayland-0"),
));
assert!(!kde_x11_uinput_hotplug_is_unsafe(
Some("x11"),
Some("GNOME"),
None,
None,
None,
Some(":0"),
None,
));
let error = ensure_master_pointer_for_session("regression-test", true)
.expect_err("the creation choke point must refuse before opening X11 or uinput");
assert!(is_uinput_unavailable(&error));
assert!(error.to_string().contains("delivery_mode='foreground'"));
}
#[test]
fn sample_linear_function() {
let pts = sample_function("x", 0.0, 10.0, 11).unwrap();
assert_eq!(pts.len(), 11);
assert_eq!(pts.first().unwrap(), &(0.0, 0.0));
assert_eq!(pts.last().unwrap(), &(10.0, 10.0));
assert!((pts[5].0 - 5.0).abs() < 1e-9 && (pts[5].1 - 5.0).abs() < 1e-9);
}
#[test]
fn sample_affine_and_trig() {
let pts = sample_function("2*x+1", 0.0, 4.0, 5).unwrap();
for (x, y) in pts {
assert!((y - (2.0 * x + 1.0)).abs() < 1e-9);
}
// sin(x) parses and yields finite, bounded values.
let s = sample_function("100+50*sin(x)", 0.0, std::f64::consts::TAU, 40).unwrap();
assert!(s.iter().all(|(_, y)| (49.9..=150.1).contains(y)));
}
#[test]
fn invalid_expression_errors() {
assert!(sample_function("x +", 0.0, 1.0, 4).is_err());
assert!(sample_function("3*z", 0.0, 1.0, 4).is_err()); // unknown var
}
#[test]
fn non_finite_points_are_dropped() {
// ln(x) is -inf/NaN for x<=0; the finite tail must still sample.
let pts = sample_function("ln(x)", -2.0, 5.0, 50).unwrap();
assert!(pts.iter().all(|(_, y)| y.is_finite()));
assert!(pts.len() >= 2);
}
#[test]
fn cumulative_lengths_and_total() {
// 3-4-5 triangle then a zero-length repeat.
let path = [(0, 0), (3, 4), (3, 4)];
let (cum, total) = path_cumulative(&path);
assert_eq!(cum.len(), 3);
assert!((cum[0] - 0.0).abs() < 1e-9);
assert!((cum[1] - 5.0).abs() < 1e-9);
assert!((cum[2] - 5.0).abs() < 1e-9);
assert!((total - 5.0).abs() < 1e-9);
}
#[test]
fn straight_segment_interpolates_by_fraction() {
let path = [(0, 0), (10, 0)];
let (cum, total) = path_cumulative(&path);
assert_eq!(point_on_path(&path, &cum, total, 0.0), (0, 0));
assert_eq!(point_on_path(&path, &cum, total, 0.5), (5, 0));
assert_eq!(point_on_path(&path, &cum, total, 1.0), (10, 0));
}
#[test]
fn multi_segment_follows_arc_length() {
// L-shape: (0,0)->(10,0)->(10,10), total length 20.
let path = [(0, 0), (10, 0), (10, 10)];
let (cum, total) = path_cumulative(&path);
assert!((total - 20.0).abs() < 1e-9);
// Halfway by arc length lands exactly on the corner.
assert_eq!(point_on_path(&path, &cum, total, 0.5), (10, 0));
// 3/4 of the way is 5px down the second segment.
assert_eq!(point_on_path(&path, &cum, total, 0.75), (10, 5));
}
#[test]
fn fraction_is_clamped_and_endpoints_exact() {
let path = [(2, 2), (8, 2), (8, 8)];
let (cum, total) = path_cumulative(&path);
// t past the ends clamps to the terminal points (no overshoot).
assert_eq!(point_on_path(&path, &cum, total, -0.5), (2, 2));
assert_eq!(point_on_path(&path, &cum, total, 2.0), (8, 8));
}
#[test]
fn degenerate_path_returns_last_point() {
let path = [(5, 5), (5, 5)];
let (cum, total) = path_cumulative(&path);
assert!((total - 0.0).abs() < 1e-9);
assert_eq!(point_on_path(&path, &cum, total, 0.3), (5, 5));
}
}