lurq 0.65.1

A Rust UI toolkit with typed components, retained state, reactive signals, GPU rendering, and DevTools.
Documentation
//! Synthetic input: driving a running window as if the OS had delivered the
//! events.
//!
//! Automation harnesses (screenshot-driven UI tests, agent tooling) need to
//! click and type into a real window. Posting native messages from outside the
//! process does not work reliably — the shell tracks its own cursor position
//! and modifier state, so a bare button-press arrives with no hover established
//! and lands on whatever the toolkit last thought was under the pointer.
//!
//! These events are queued through the same internal window-command channel the
//! window's own controls use and are drained by the shell inside its event
//! loop, so they reach exactly the entry points real winit events reach and
//! observe the same ordering guarantees.

use crate::app::{
  events::{ClipboardContent, DraggedPaths, MouseButton, ScrollPhase},
  runtime::Tree,
};

/// Modifier state to apply to a synthetic event, matching what the shell would
/// have read from `ModifiersChanged`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub struct SyntheticModifiers {
  pub shift: bool,
  pub ctrl: bool,
  pub alt: bool,
  pub meta: bool,
}

#[cfg(feature = "devtools")]
impl crate::app::component::DevtoolsInspectable for SyntheticModifiers {
  fn inspect(&self, formatter: &mut crate::app::component::DevtoolsFormatter<'_>) {
    formatter.value_debug(self);
  }
}

impl SyntheticModifiers {
  pub fn shift(mut self) -> Self {
    self.shift = true;
    self
  }

  pub fn ctrl(mut self) -> Self {
    self.ctrl = true;
    self
  }

  pub fn alt(mut self) -> Self {
    self.alt = true;
    self
  }

  pub fn meta(mut self) -> Self {
    self.meta = true;
    self
  }
}

/// What a synthetic event does. Positions are **physical** pixels in the
/// window's own coordinate space — the same units `WindowEvent::CursorMoved`
/// carries, and the same units a captured frame is measured in, so a caller can
/// click what it sees in a screenshot without converting.
#[derive(Clone, Debug, PartialEq)]
pub enum SyntheticInputKind {
  MouseMove {
    x: f32,
    y: f32,
  },
  MouseDown {
    x: f32,
    y: f32,
    button: MouseButton,
  },
  MouseUp {
    x: f32,
    y: f32,
    button: MouseButton,
  },
  /// Move, press, release — in that order.
  ///
  /// Hover is established before the press because that is what real input
  /// does: hit-testing runs off the last motion event, so a press with no
  /// preceding move is delivered against a stale position.
  Click {
    x: f32,
    y: f32,
    button: MouseButton,
  },
  Wheel {
    x: f32,
    y: f32,
    delta_x: f32,
    delta_y: f32,
  },
  KeyDown {
    key: String,
    code: String,
  },
  KeyUp {
    key: String,
    code: String,
  },
  /// One printable character, delivered as a press/release pair.
  Char(char),
  /// A paste of this content into the focused text input, as Ctrl+V pastes
  /// the OS clipboard. Synthetic input never reads the OS clipboard: a
  /// synthetic Ctrl+V is refused, and this carries the content instead.
  Paste(ClipboardContent),
  /// Files from the OS come over the window at this point, or move there
  /// (`on_file_drag_enter`, `on_file_drag_over`).
  FileDragEnter {
    x: f32,
    y: f32,
    paths: DraggedPaths,
  },
  /// The drag moves to this point (`on_file_drag_over`, and enter and leave
  /// of the elements it crosses).
  FileDragOver {
    x: f32,
    y: f32,
  },
  /// The drag leaves the window without a drop (`on_file_drag_leave`).
  FileDragLeave,
  /// Files are dropped at this point (`on_file_drop`); enters first when no
  /// drag is in progress.
  FileDrop {
    x: f32,
    y: f32,
    paths: DraggedPaths,
  },
}

/// A queued synthetic event.
#[derive(Clone, Debug, PartialEq)]
pub struct SyntheticInput {
  kind: SyntheticInputKind,
  modifiers: SyntheticModifiers,
}

impl SyntheticInput {
  pub fn new(kind: SyntheticInputKind) -> Self {
    Self {
      kind,
      modifiers: SyntheticModifiers::default(),
    }
  }

  pub fn with_modifiers(mut self, modifiers: SyntheticModifiers) -> Self {
    self.modifiers = modifiers;
    self
  }

  pub fn kind(&self) -> &SyntheticInputKind {
    &self.kind
  }

  pub fn modifiers(&self) -> SyntheticModifiers {
    self.modifiers
  }

  pub fn mouse_move(x: f32, y: f32) -> Self {
    Self::new(SyntheticInputKind::MouseMove { x, y })
  }

  pub fn mouse_down(x: f32, y: f32, button: MouseButton) -> Self {
    Self::new(SyntheticInputKind::MouseDown { x, y, button })
  }

  pub fn mouse_up(x: f32, y: f32, button: MouseButton) -> Self {
    Self::new(SyntheticInputKind::MouseUp { x, y, button })
  }

  pub fn click(x: f32, y: f32) -> Self {
    Self::new(SyntheticInputKind::Click {
      x,
      y,
      button: MouseButton::Left,
    })
  }

  pub fn click_button(x: f32, y: f32, button: MouseButton) -> Self {
    Self::new(SyntheticInputKind::Click { x, y, button })
  }

  pub fn wheel(x: f32, y: f32, delta_x: f32, delta_y: f32) -> Self {
    Self::new(SyntheticInputKind::Wheel { x, y, delta_x, delta_y })
  }

  /// A named key such as `Enter`, `Tab`, `Escape`, `ArrowDown`, or a single
  /// character. `code` defaults to the key name when the caller has no
  /// physical-key information, which is what every non-layout-sensitive
  /// consumer wants.
  pub fn key_down(key: impl Into<String>) -> Self {
    let key = key.into();
    Self::new(SyntheticInputKind::KeyDown {
      code: physical_code_for(&key),
      key,
    })
  }

  pub fn key_up(key: impl Into<String>) -> Self {
    let key = key.into();
    Self::new(SyntheticInputKind::KeyUp {
      code: physical_code_for(&key),
      key,
    })
  }

  pub fn char(character: char) -> Self {
    Self::new(SyntheticInputKind::Char(character))
  }

  /// Expand a string into one [`SyntheticInputKind::Char`] per character.
  pub fn text(value: &str) -> Vec<Self> {
    value.chars().map(Self::char).collect()
  }

  /// A paste of `content` into the focused text input; see
  /// [`SyntheticInputKind::Paste`].
  pub fn paste(content: ClipboardContent) -> Self {
    Self::new(SyntheticInputKind::Paste(content))
  }

  /// Files from the OS come over the window at `(x, y)`, as
  /// [`Tree::file_drag_enter`](crate::app::Tree::file_drag_enter).
  pub fn file_drag_enter(paths: DraggedPaths, x: f32, y: f32) -> Self {
    Self::new(SyntheticInputKind::FileDragEnter { x, y, paths })
  }

  /// The file drag moves to `(x, y)`.
  pub fn file_drag_over(x: f32, y: f32) -> Self {
    Self::new(SyntheticInputKind::FileDragOver { x, y })
  }

  /// The file drag leaves the window without a drop.
  pub fn file_drag_leave() -> Self {
    Self::new(SyntheticInputKind::FileDragLeave)
  }

  /// Files are dropped at `(x, y)`, as [`Tree::file_drop`](crate::app::Tree::file_drop).
  pub fn file_drop(paths: DraggedPaths, x: f32, y: f32) -> Self {
    Self::new(SyntheticInputKind::FileDrop { x, y, paths })
  }
}

/// Deliver one synthetic event into the tree through the same entry points the
/// winit shell uses for real events. Handlers see
/// [`InputSource::Synthetic`](crate::app::events::InputSource::Synthetic) while it is delivered.
///
/// Kept beside the event type rather than in the shell so both shells share one
/// implementation and the ordering rules are stated once. Public because a
/// headless harness drives a [`Tree`] directly, with no window to queue through.
pub fn apply(tree: &mut Tree, input: &SyntheticInput) {
  crate::app::events::with_synthetic_input(|| deliver(tree, input));
}

fn deliver(tree: &mut Tree, input: &SyntheticInput) {
  let m = input.modifiers();
  match input.kind() {
    SyntheticInputKind::MouseMove { x, y } => {
      tree.mouse_move_with_meta(*x, *y, m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::MouseDown { x, y, button } => {
      tree.mouse_down_with_meta(*x, *y, *button, m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::MouseUp { x, y, button } => {
      tree.mouse_up_with_meta(*x, *y, *button, m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::Click { x, y, button } => {
      // Hover first: hit-testing reads the last motion event, so a press with
      // no preceding move lands wherever the pointer was left.
      tree.mouse_move_with_meta(*x, *y, m.shift, m.ctrl, m.alt, m.meta);
      tree.mouse_down_with_meta(*x, *y, *button, m.shift, m.ctrl, m.alt, m.meta);
      tree.mouse_up_with_meta(*x, *y, *button, m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::Wheel { x, y, delta_x, delta_y } => {
      // A wheel notch is a complete gesture: scroll containers latch on Start
      // and release on End, so omitting either leaves one latched. It is a
      // mouse's wheel, so the scroll is animated as a real notch is
      // (`Tree::wheel`): the content is where it was sent once the tree has
      // no animation left.
      tree.mouse_move_with_meta(*x, *y, m.shift, m.ctrl, m.alt, m.meta);
      tree.scroll(*x, *y, 0.0, 0.0, ScrollPhase::Start);
      tree.wheel_with_meta(
        *x,
        *y,
        *delta_x,
        *delta_y,
        ScrollPhase::Scroll,
        m.shift,
        m.ctrl,
        m.alt,
        m.meta,
      );
      tree.scroll(*x, *y, 0.0, 0.0, ScrollPhase::End);
    }
    SyntheticInputKind::KeyDown { key, code } => {
      tree.key_down_with_meta(key.clone(), code.clone(), m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::KeyUp { key, code } => {
      tree.key_up_with_meta(key.clone(), code.clone(), m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::Char(character) => {
      let key = character.to_string();
      let code = physical_code_for(&key);
      tree.key_down_with_meta(key.clone(), code.clone(), m.shift, m.ctrl, m.alt, m.meta);
      tree.key_up_with_meta(key, code, m.shift, m.ctrl, m.alt, m.meta);
    }
    SyntheticInputKind::Paste(content) => {
      tree.paste(content.clone());
    }
    SyntheticInputKind::FileDragEnter { x, y, paths } => {
      tree.file_drag_enter(paths.clone(), *x, *y);
    }
    SyntheticInputKind::FileDragOver { x, y } => {
      tree.file_drag_over(*x, *y);
    }
    SyntheticInputKind::FileDragLeave => {
      tree.file_drag_leave();
    }
    SyntheticInputKind::FileDrop { x, y, paths } => {
      tree.file_drop(paths.clone(), *x, *y);
    }
  }
}

/// Best-effort `KeyboardEvent.code` for a key name.
///
/// The shell derives this from the physical scancode; a synthetic caller
/// usually has only the logical key, and consumers that branch on `code` are
/// looking for letters and digits.
fn physical_code_for(key: &str) -> String {
  let mut chars = key.chars();
  match (chars.next(), chars.next()) {
    (Some(single), None) if single.is_ascii_alphabetic() => {
      format!("Key{}", single.to_ascii_uppercase())
    }
    (Some(single), None) if single.is_ascii_digit() => format!("Digit{single}"),
    _ => key.to_owned(),
  }
}

#[cfg(test)]
mod tests {
  use super::*;

  #[test]
  fn letters_and_digits_get_physical_codes() {
    assert_eq!(physical_code_for("a"), "KeyA");
    assert_eq!(physical_code_for("Z"), "KeyZ");
    assert_eq!(physical_code_for("7"), "Digit7");
    assert_eq!(physical_code_for("Enter"), "Enter");
    assert_eq!(physical_code_for("ArrowDown"), "ArrowDown");
  }

  #[test]
  fn text_expands_to_one_event_per_character() {
    let events = SyntheticInput::text("hi!");
    assert_eq!(events.len(), 3);
    assert_eq!(events[0].kind(), &SyntheticInputKind::Char('h'));
    assert_eq!(events[2].kind(), &SyntheticInputKind::Char('!'));
  }

  #[test]
  fn modifiers_are_carried_with_the_event() {
    let event = SyntheticInput::click(1.0, 2.0).with_modifiers(SyntheticModifiers::default().shift().ctrl());
    assert!(event.modifiers().shift);
    assert!(event.modifiers().ctrl);
    assert!(!event.modifiers().alt);
  }
}