Struct HeadlessShell 

pub struct HeadlessShell { /* private fields */ }

A Shell with no window system behind it.

See the module docs for what it models and where it deliberately differs from a real compositor.

Implementations

impl HeadlessShell

pub fn new() -> Self

A shell with one 1920×1080 monitor at scale 1.0 and every capability.

pub fn with_caps(self, caps: ShellCaps) -> Self

This shell, reporting only caps.

The lever that makes the capability system testable; see the module docs.

pub fn with_monitors(self, monitors: Vec<MonitorInfo>) -> Self

This shell, with monitors instead of the default one.

Panics

If monitors is empty. A shell with no monitor cannot answer where a borderless window goes, and every backend that could report zero monitors (a headless X server, a disconnected session) is a case the engine treats as “no display”.

If two monitors share a MonitorId, or if one uses u32::MAX. Ids are the key Shell::monitor looks up and the ones plug_monitor hands out afterwards, so a duplicate makes the lookup ambiguous and u32::MAX leaves no id for the next hotplug.

pub fn with_scale_factor(self, scale_factor: f64) -> Self

This shell, with the primary monitor at scale_factor.

Convenience for the common DPI test, which otherwise has to build a whole MonitorInfo.

pub const fn with_configure_delay(self, pumps: u32) -> Self

This shell, delivering the first configure after pumps calls to pump.

See set_configure_delay.

pub const fn set_configure_delay(&mut self, pumps: u32)

How many pumps a configure waits before it is delivered.

Defaults to DEFAULT_CONFIGURE_DELAY. Raise it to prove that a consumer’s create-then-wait loop is a real loop rather than an off-by-one that happens to work; drop it to 0 when a test is about something else entirely and wants a window configured on the first pump.

Applies to configures scheduled after this call.

pub fn set_caps(&mut self, caps: ShellCaps)

Replaces the reported capabilities mid-session.

Real backends must not do this — Shell::caps is latched — but a test building one shell per capability set is noise. Setting it before the first create_window is the intended use.

pub fn now(&self) -> EventTime

The shell’s current time, which every injected event is stamped with.

pub fn advance(&mut self, delta: Duration)

Moves the shell’s clock forward.

Injected events are stamped with the time after the advance, so advance(200ms) between a press and a release produces a 200 ms hold — which is how the P2 pattern evaluator’s tap/hold table gets tested.

pub fn set_time(&mut self, now: Duration)

Slaves the shell’s clock to an absolute timestamp.

Pass time.elapsed() from the test’s own ManualTime each frame and the shell’s event timestamps land on the same timeline as the FrameClock’s, which is what EventTime’s epoch contract requires of a real backend.

pub fn set_modifiers(&mut self, modifiers: Modifiers)

The modifier state stamped onto subsequent injected events.

Sticky, like a real backend’s tracked state — see event for why modifiers ride on each event rather than arriving separately.

pub fn pending_events(&self) -> usize

How many events are queued and not yet pumped.

pub const fn wait_count(&self) -> u32

How many times Shell::wait_events has been called.

A test for an editor-style idle loop asserts that it actually waits instead of spinning, and there is nothing else observable about a headless wait.

pub fn inject(&mut self, event: ShellEvent)

Queues an event verbatim, with no state update and no validation.

The escape hatch: use it to inject sequences a well-behaved compositor would not produce — a resize that violates the constraints, events for a destroyed window, a scale change with no resize — because those are exactly the cases a consumer is most likely to get wrong. The typed helpers below keep the shell’s state consistent; this one does not.

pub fn schedule( &mut self, pumps: u32, script: impl FnOnce(&mut Self) + Send + 'static, )

Runs script on this shell at the top of the pump pumps pumps from now, so what it injects is delivered by that pump; 0 is the next one.

Everything injected directly arrives in the next pump, so a consumer that runs its own loop over this shell would see a whole scripted run at once, before it has drawn a frame. A schedule spreads the run over frames: layout, present and an out-of-date retry happen between keys. The script runs then, not now, so the typed helpers it calls stamp the clock as it stands at that pump and see the windows as they are then.

Every turn of the window system counts, as for set_configure_delay: a script that comes due in keep_alive runs there, and what it injects waits for the next pump. Scripts due at the same pump run in the order they were scheduled; one scheduled by a script is counted from the pump after the one it was scheduled in. While a script waits, wait_events returns at once, since only pumping brings it closer.

pub fn resize( &mut self, window: WindowId, size: PhysicalSize, ) -> Result<(), ShellError>

Delivers a configure at size immediately, as a compositor answering a resize would.

This is the compositor speaking, not the client asking, so it takes effect at once and supersedes any pending configure. It is therefore also the one-line way to get a configured window in a test that is about something other than the configure handshake.

The window’s constraints are applied, because a compositor that honours hints would have applied them. Use inject to feed a size that violates them, which is what a tiling window manager does.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn change_scale_factor( &mut self, window: WindowId, scale_factor: f64, ) -> Result<(), ShellError>

Changes a window’s scale factor, as dragging it to another monitor would.

The window’s logical size is preserved and the physical size recomputed, which is what both Wayland (wl_surface.set_buffer_scale against an unchanged window geometry) and Win32 (WM_DPICHANGED’s suggested rectangle) do. Queues a ScaleFactorChanged carrying both facts, so a consumer cannot hold a mismatched size/scale pair, followed by the Resized it implies — which is the pair both Linux backends emit for a scale change, and the pair deliver_due_configures emits for a scale change that arrives with a configure.

Errors

ShellError::InvalidWindow if the handle is stale.

Panics

If scale_factor is not positive.

pub fn set_focus( &mut self, window: WindowId, focused: bool, ) -> Result<(), ShellError>

Gives or takes keyboard focus.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn request_close(&mut self, window: WindowId) -> Result<(), ShellError>

Asks the application to close the window, as a title-bar button would.

The window stays open until reply_close_request.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn key( &mut self, window: WindowId, key: KeyCode, state: ButtonState, ) -> Result<(), ShellError>

Injects a key press or release.

The scancode and keysym are synthesized deterministically from key: the scancode is the key’s index in KeyCode::ALL offset by 8 (evdev’s convention, so the numbers look plausible in a log), and the keysym is the US-layout symbol where there is one. Neither is a claim about any real keyboard; they exist so a consumer reading those fields is exercised rather than reading zero.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn key_press( &mut self, window: WindowId, key: KeyCode, ) -> Result<(), ShellError>

Injects a key press.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn key_release( &mut self, window: WindowId, key: KeyCode, ) -> Result<(), ShellError>

Injects a key release.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn key_repeat( &mut self, window: WindowId, key: KeyCode, ) -> Result<(), ShellError>

Injects an auto-repeat press, the kind a text field wants and a jump button must ignore.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn move_pointer( &mut self, window: WindowId, position: PhysicalPoint, raw_delta: (f64, f64), ) -> Result<(), ShellError>

Moves the pointer to an absolute position, reporting the implied relative delta as well.

Under PointerMode::Locked the absolute position is dropped, matching what the mode documents — which is what makes a camera that wrongly reads abs fail here rather than in a playtest.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn set_pointer_focus( &mut self, window: WindowId, entered: bool, position: Option<PhysicalPoint>, ) -> Result<(), ShellError>

Moves the pointer into or out of the window.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn button( &mut self, window: WindowId, button: PointerButton, state: ButtonState, position: Option<PhysicalPoint>, ) -> Result<(), ShellError>

Injects a pointer button press or release.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn scroll( &mut self, window: WindowId, delta: ScrollDelta, position: Option<PhysicalPoint>, ) -> Result<(), ShellError>

Injects a scroll.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn touch( &mut self, window: WindowId, contact: ContactId, phase: TouchPhase, position: PhysicalPoint, ) -> Result<(), ShellError>

Injects one contact’s landing, move, lift or cancellation.

One call is one contact, so a scripted two-finger gesture is two interleaved sequences of these — which is the point, and is why there is no “set the whole contact list” call that would let a script express a state a real touchscreen never reports.

Nothing here checks that a Moved follows a Began, or that an id is not reused while it is still down: a test double that refused to produce a malformed stream could not be used to check what a consumer does with one.

The emulated pointer events a real touch backend owes for its primary contact are not synthesized here either — move_pointer and button are how a script states those, and a test that wants the two halves together says so rather than getting a second event it did not ask for.

Errors

ShellError::InvalidWindow if the handle is stale, or ShellError::Unsupported without ShellCaps::TOUCH — a shell configured as a touchless backend must not be able to script a finger, or a test would prove something about a platform that cannot happen.

pub fn commit_text( &mut self, window: WindowId, text: &str, ) -> Result<(), ShellError>

Injects committed text, as an input method would.

Errors

ShellError::InvalidWindow if the handle is stale.

Panics

If text is empty — ShellEvent::TextCommit documents that it never is, and a shell that could produce one would make that a lie.

pub fn preedit_text( &mut self, window: WindowId, text: &str, cursor: Option<usize>, ) -> Result<(), ShellError>

Injects a composition in progress, as an input method would: text so far, its cursor at the byte offset cursor, and an empty text for a composition that ended.

Errors

ShellError::InvalidWindow if the handle is stale.

Panics

If cursor is not on a char boundary of text, or is given for an empty text — ShellEvent::TextPreedit documents both.

pub fn drop_file( &mut self, window: WindowId, path: impl Into<PathBuf>, position: Option<PhysicalPoint>, ) -> Result<(), ShellError>

Drops a file on the window.

Errors

ShellError::InvalidWindow if the handle is stale, or ShellError::Unsupported if the window did not opt into drops or the shell lacks ShellCaps::DRAG_DROP.

pub fn plug_monitor(&mut self, info: MonitorInfo) -> MonitorId

Adds a monitor and queues a MonitorsChanged.

The id is assigned by the shell and never reuses one that has been handed out, which is the obligation monitor places on every backend.

pub fn unplug_monitor(&mut self, id: MonitorId) -> Result<(), ShellError>

Removes a monitor: queues a MonitorRemoved, a CloseRequested for every panel created for it that has none outstanding, and a MonitorsChanged.

Errors

ShellError::NoSuchMonitor if it is not connected.

Panics

If it is the last monitor; see with_monitors.

pub fn title(&self, window: WindowId) -> Result<&str, ShellError>

The window’s title, which no Shell method exposes.

Titles are write-only across the seam — no backend can read one back reliably, since a window manager may decorate or truncate it — so this is a headless-only accessor for tests that assert set_title did something.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn cursor(&self, window: WindowId) -> Result<Option<CursorIcon>, ShellError>

The window’s current cursor, or None if it is hidden.

Headless-only, for the same reason as title.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn text_input( &self, window: WindowId, ) -> Result<Option<TextPurpose>, ShellError>

The text field the window last said is taking typing, with Shell::set_text_input; None while none is.

Headless-only, for the same reason as title.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn text_input_area( &self, window: WindowId, ) -> Result<Option<PhysicalRect>, ShellError>

Where the window last said text is being entered, with Shell::set_text_input_area; None until it said, or once it handed placement back.

Headless-only, for the same reason as title.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn panel( &self, window: WindowId, ) -> Result<Option<PanelDesc<'_>>, ShellError>

What the panel was created with, or last given by Shell::set_panel; None for a window that is not a panel.

Headless-only, for the same reason as title.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn input_region( &self, window: WindowId, ) -> Result<Option<&[PhysicalRect]>, ShellError>

The rectangles the window last limited its pointer input to, with Shell::set_input_region; None while it takes the pointer everywhere.

Headless-only, for the same reason as title. Kept as given, empty rectangles included, so a test reads back what it sent.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn frame_requested(&self, window: WindowId) -> Result<bool, ShellError>

Whether the window has asked for a frame, with Shell::request_frame, that the next pump has yet to answer.

Headless-only, for the same reason as title: a test of a loop that paces itself reads whether the loop asked.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn idle_inhibited(&self, window: WindowId) -> Result<bool, ShellError>

Whether the window is asking, with Shell::set_idle_inhibit, for the display to be kept on.

Headless-only, for the same reason as title: there is no display to keep on, so a test of a game that should keep it on during play reads whether it asked.

Errors

ShellError::InvalidWindow if the handle is stale.

pub fn opened_urls(&self) -> &[(WindowId, WebUrl)]

Every URL Shell::open_url accepted, oldest first, with the window that asked.

Headless-only, for the same reason as title: there is no browser to open, so a test of a menu’s “Wishlist” button reads that it asked for the store page. Kept when the window is destroyed, since the browser it would have opened stays open too.

pub fn set_outputs_powered(&mut self, powered: bool)

Turns every output off or back on, as far as frame requests go.

A compositor’s frame pacing, modelled. Where ShellCaps::FRAME_CALLBACK is set, a window on an output that is off is never asked for a frame: Wayland withholds wl_surface.frame’s done until something of the surface is shown again, which is what swaymsg output HEADLESS-1 power off does to a real one. With this false, a Shell::request_frame is held rather than answered at the next pump, and a held request does not cut a wait_events short; it is answered at the first pump after this is true again, unless its window was destroyed first. Every other event is delivered as before.

On by default: a request is answered at the next pump, as on every backend without the capability.

pub fn clipboard_bytes(&self, mime: MimeType) -> Option<&[u8]>

The bytes currently offered on the in-process clipboard for mime.

Headless-only.

pub fn set_clipboard_readable(&mut self, readable: bool)

Whether the clipboard can be read at all right now.

The focus gate, modelled. On Wayland a client learns what is on the clipboard from wl_data_device.selection, which arrives only while one of its windows has keyboard focus — so a background window cannot read the clipboard, and a read issued a moment before focus arrives has nothing to answer from. HeadlessShell is readable by default, because most platforms have no such gate; set this to false to make a test walk the path a Wayland consumer will walk.

A read issued while this is false is held, not answered: it is answered as soon as this becomes true again, or reported ClipboardContent::Unavailable once clipboard_deadline pumps have gone by. That is the seam’s obligation 5, and this is how a consumer is tested against it.

pub fn set_clipboard_stalled(&mut self, stalled: bool)

Whether a peer holds the clipboard and never hands the data over.

The other way a read can fail to complete, and the one that has no protocol event behind it: on Wayland the transfer is a pipe another application writes, and an application that accepts the descriptor and then hangs produces exactly this. The read is held and then reported ClipboardContent::Unavailable — never Empty, because there really is something on the clipboard.

pub fn require_user_interaction(&mut self, required: bool)

Whether claiming the clipboard requires a recent user interaction.

The serial requirement, modelled. Off by default, because X11 and Win32 have no such rule; on, clipboard_offer fails with ShellError::NeedsUserInteraction until an input event has been injected — a key, a pointer button, a scroll or a motion. That is what Wayland’s set_selection serial and the browser’s user-gesture gate both amount to, and it is a feature: it is what stops a background process taking the clipboard.

use crcbl_shell::{ClipboardOffer, HeadlessShell, KeyCode, Shell, ShellError, WindowDesc};

let mut shell = HeadlessShell::new();
let window = shell.create_window(&WindowDesc::default())?;
shell.require_user_interaction(true);

// Nobody has touched anything, so the clipboard is not ours to take.
let refused = shell.clipboard_offer(window, &[ClipboardOffer::text("x")]);
assert!(matches!(refused, Err(ShellError::NeedsUserInteraction { .. })));

// The copy the user actually asked for goes through.
shell.key_press(window, KeyCode::KeyC)?;
shell.clipboard_offer(window, &[ClipboardOffer::text("x")])?;

pub fn clear_user_interaction(&mut self)

Forgets that any input has been injected.

For a test that wants a second refusal after a successful copy — a real serial goes stale the same way.

pub fn clipboard_deadline(&mut self, pumps: u32)

How many pumps a held read waits before it reports ClipboardContent::Unavailable.

Defaults to DEFAULT_CLIPBOARD_DEADLINE. Zero means the very next pump gives up, which is the shortest way to write the timeout case.

pub fn held_clipboard_reads(&self) -> usize

How many reads have been accepted and not yet answered.

Headless-only, so a test can assert that a request really is being held rather than having been answered and missed.

pub fn set_foreign_clipboard(&mut self, offers: Vec<(ReceivedMime, Vec<u8>)>)

Replaces the clipboard with content spelled the way another application would spell it.

clipboard_offer can only publish the mimes this engine names, so it cannot produce the case that matters: a paste from a foreign application whose mime string is neither 'static nor one of ours. This can.

Trait Implementations

impl Debug for HeadlessShell

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HeadlessShell

fn default() -> Self

Returns the “default value” for a type.

impl Shell for HeadlessShell

fn destroy_window(&mut self, window: WindowId) -> Result<(), ShellError>

Destroys the window and, first, every popup that belongs to it — each with its own ShellEvent::WindowDestroyed — as every window system destroys a popup with its parent.

fn reposition_popup( &mut self, popup: WindowId, anchor: LogicalRect, size: LogicalSize, ) -> Result<(), ShellError>

Takes the new size as a pending configure, like a window system that answers a move with a resize. The anchor places nothing: there is no screen to place against.

fn set_panel( &mut self, window: WindowId, size: LogicalSize, panel: &PanelDesc<'_>, ) -> Result<(), ShellError>

Records the new descriptor, which panel reads back, and takes the new size as a pending configure, as create_window takes a panel’s first.

fn keep_alive(&mut self)

Lets the configures, the held reads and the scheduled scripts come due, and keeps what they produce.

This counts as a pump for each of this shell’s pump-counted delays, set_configure_delay, clipboard_deadline and schedule: each counts the window system’s turns, and delivery is the only part of a turn this leaves out.

fn wait_events(&mut self, timeout: Option<Duration>)

Sleeps as far as a shell with no window system behind it can.

This shell reports ShellCaps::EVENT_WAIT by default, and that bit says wait_events genuinely blocks — so it does: with the capability set, nothing already queued, no frame due and no script scheduled, this really sleeps for timeout, and an editor-style idle loop tested here idles rather than spinning. Without the capability it returns immediately, like every backend that cannot block.

A waker ends the sleep early, from any thread, and so does a wake rung before the wait began.

None — “until something happens” — returns immediately while no waker has been handed out, because then the only thing that can make something happen in a headless shell is the caller, on this thread, and blocking forever would be a deadlock by construction rather than a wait. Once a waker exists, another thread can, so None sleeps until it rings.

fn waker(&mut self) -> Option<ShellWaker>

The headless doorbell: a condition variable wait_events sleeps on, rung from any thread.

fn align_event_clock(&mut self, elapsed: Duration)

The seam-level spelling of set_time.

Both exist because a test drives this shell through the concrete type and calls set_time every frame, while a consumer written against dyn Shell can only reach the trait — and the trait method is the one a real backend has to implement, so it must be exercised here too.

fn set_text_input( &mut self, window: WindowId, field: Option<TextPurpose>, ) -> Result<(), ShellError>

Records the request, which text_input reads back; there is no input method to tell.

fn set_text_input_area( &mut self, window: WindowId, area: Option<PhysicalRect>, ) -> Result<(), ShellError>

Records the area, which text_input_area reads back; there is no input method to place.

fn set_input_region( &mut self, window: WindowId, region: Option<&[PhysicalRect]>, ) -> Result<(), ShellError>

Records the region, which input_region reads back; there is no pointer to route. A passthrough popup records it too, though no backend acts on it there.

fn set_idle_inhibit( &mut self, window: WindowId, inhibit: bool, ) -> Result<(), ShellError>

Records the request, which idle_inhibited reads back; there is no display to keep on. Refused without ShellCaps::IDLE_INHIBIT, as a backend that cannot act on it refuses.

fn open_url(&mut self, window: WindowId, url: &WebUrl) -> Result<(), ShellError>

Records the request, which opened_urls reads back; there is no browser to open. Refused without ShellCaps::OPEN_URL, as a backend that cannot act on it refuses.

fn request_frame(&mut self, window: WindowId) -> Result<(), ShellError>

Answered at the next pump, as every backend without ShellCaps::FRAME_CALLBACK answers; there is no compositor to hold it back. frame_requested reads whether one is outstanding.

fn clipboard_offer( &mut self, window: WindowId, offers: &[ClipboardOffer<'_>], ) -> Result<(), ShellError>

Claims the in-process clipboard.

Errors

ShellError::Unsupported without ShellCaps::CLIPBOARD, ShellError::InvalidWindow for a stale handle, or ShellError::NeedsUserInteraction when require_user_interaction is on and no input has been injected since — the modelled form of Wayland’s serial requirement and the browser’s user-gesture gate.

fn clipboard_request( &mut self, window: WindowId, mime: MimeType, ) -> Result<ClipboardRequestId, ShellError>

Accepts a read, answering it now if the clipboard is readable and holding it if it is not.

The held path is the seam’s obligation 5, modelled: with set_clipboard_readable(false) the answer waits, exactly as it does on Wayland while another client has focus, and a consumer that assumed an immediate empty answer sees the difference here rather than on someone’s desktop.

Errors

ShellError::Unsupported without ShellCaps::CLIPBOARD, or ShellError::InvalidWindow for a stale handle.

fn clipboard_readable(&self, window: WindowId) -> bool

Whether a read would be answered without waiting.

The default would be “yes, always”; this one can be told otherwise, so that a consumer can be tested against a backend that has a focus gate without there being a compositor in the room.

fn backend(&self) -> ShellBackend

Which implementation this is. Logs and bug reports only — behaviour branches on caps.

fn caps(&self) -> ShellCaps

What this backend can do. Fixed for the shell’s lifetime.

fn create_window( &mut self, desc: &WindowDesc<'_>, ) -> Result<WindowId, ShellError>

Creates a window. The window has no size yet.

fn window_state(&self, window: WindowId) -> Result<WindowState, ShellError>

A snapshot of the window’s current state.

fn set_title(&mut self, window: WindowId, title: &str) -> Result<(), ShellError>

Sets the title bar text.

fn set_visible( &mut self, window: WindowId, visible: bool, ) -> Result<(), ShellError>

Maps or unmaps the window.

fn set_mode( &mut self, window: WindowId, mode: DisplayMode, ) -> Result<(), ShellError>

Asks for windowed or borderless.

fn set_constraints( &mut self, window: WindowId, constraints: SizeConstraints, ) -> Result<(), ShellError>

Asks for resize limits and an aspect lock.

fn monitors(&self) -> &[MonitorInfo]

Every connected monitor.

fn pump(&mut self, sink: &mut dyn FnMut(ShellEvent))

Drains everything that has arrived from the window system into sink.

fn surface_target(&self, window: WindowId) -> Result<SurfaceTarget, ShellError>

The native handles a HAL backend needs to create a surface for this window.

fn set_pointer_mode( &mut self, window: WindowId, mode: PointerMode, ) -> Result<(), ShellError>

Frees, confines or locks the pointer.

fn set_cursor( &mut self, window: WindowId, cursor: Option<CursorIcon>, ) -> Result<(), ShellError>

Sets the cursor shape, or hides the cursor with None.

fn warp_pointer( &mut self, window: WindowId, position: PhysicalPoint, ) -> Result<(), ShellError>

Moves the pointer to a position in the window.

fn reply_close_request( &mut self, window: WindowId, reply: CloseReply, ) -> Result<(), ShellError>

Answers a ShellEvent::CloseRequested.

fn monitor(&self, id: MonitorId) -> Option<&MonitorInfo>

One monitor by id, or None if it is not connected.

fn activation_token( &mut self, window: WindowId, ) -> Result<Option<String>, ShellError>

A token another program can raise its own window with, made from window and the latest input this program received.