Trait Input 

pub trait Input {
    // Required method
    fn poll_event(&mut self, timeout: Duration) -> Option<Event>;

    // Provided method
    fn push_event(&mut self, _event: Event) { ... }
}

Polls for and accepts input events.

Backends that never receive events from outside their own poll_event implementation (e.g. Crossterm, which reads its own event stream) can use the default no-op push_event via an empty impl Input for X {}.

Examples

use core::time::Duration;
use retroglyph_core::backend::Input;
use retroglyph_core::event::Event;
use std::collections::VecDeque;

struct QueuedInput(VecDeque<Event>);

impl Input for QueuedInput {
    fn poll_event(&mut self, _timeout: Duration) -> Option<Event> {
        self.0.pop_front()
    }

    fn push_event(&mut self, event: Event) {
        self.0.push_back(event);
    }
}

Required Methods

fn poll_event(&mut self, timeout: Duration) -> Option<Event>

Poll for an input event, waiting up to timeout.

Provided Methods

fn push_event(&mut self, _event: Event)

Push an event into the backend’s event buffer.

Backends that receive events externally (e.g., from a window event loop or a test harness) override this to queue events for poll_event. The default is a no-op.

• Windowed backends: called by ApplicationHandler on each event.
• Headless: called by tests to inject synthetic events.
• Crossterm: also queues events pushed here (a test harness injecting synthetic input, or a driver handing back an event it already read off the real terminal); its own poll_event still reads the real terminal’s stream separately.

Coalescing a burst of consecutive Event::Mouse(MouseEventKind::Moved) pushes down to the latest one is not required of every implementation, only of backends whose events can arrive at device-polling rate from an external source (a windowed backend’s motion events, for example); see retroglyph_core::testing::conformance::assert_input_contract for the harness that pins it, and that module’s doc for which backends it binds.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl Input for SoftwareRenderer

fn poll_event(&mut self, _timeout: Duration) -> Option<Event>

fn push_event(&mut self, event: Event)

impl Input for TerminalWasm

fn push_event(&mut self, event: Event)

The sole public way to push an event onto a TerminalWasm; forwards to the crate-private inherent push_event.

fn poll_event(&mut self, _timeout: Duration) -> Option<Event>

impl<P> Input for WindowBackend<P>

where P: Presenter,

fn poll_event(&mut self, _timeout: Duration) -> Option<Event>

fn push_event(&mut self, event: Event)

impl<W> Input for Crossterm<W>

where W: Write,

fn poll_event(&mut self, timeout: Duration) -> Option<Event>

Polls for the next input event, blocking up to timeout. See the crate-level “Event polling and CPU cost” doc section for what a zero timeout costs and where the actual CPU cost of an uncapped game loop comes from.

Backends and examples in this workspace that need a frame cap (e.g. software + WASM, gated on requestAnimationFrame) already throttle themselves upstream of this call; a crossterm-driven loop wanting the same tradeoff should add its own std::thread::sleep/tick budget around drain_events() rather than expecting this method to throttle on its behalf.

fn push_event(&mut self, event: Event)

Queues event ahead of the real terminal’s own stream; the next poll_event returns it.

See the pushed_events field comment for why this backend implements this at all, when it has a perfectly good event source of its own.

Deliberately does not coalesce consecutive Mouse(Moved) pushes the way retroglyph-window’s WindowBackend, retroglyph-software’s SoftwareRenderer, and Headless do; this backend is intentionally exempt from retroglyph_core::testing::conformance::assert_input_contract (see that module’s doc for the coverage table). That coalescing exists to bound queue growth against a device-polling-rate motion firehose (winit’s CursorMoved, retroglyph#294/retroglyph#768); pushed_events has no such source feeding it, it only ever receives events a test harness or driver replays by hand, one at a time, so there is nothing to bound and coalescing would just be dead code here.

Implementors

impl Input for Headless