Struct DesktopController 

pub struct DesktopController { /* private fields */ }

Top-level entry point.

Cheap Clone is deliberately not implemented; sharing across threads is done via Arc<DesktopController> on the caller side. The worker thread is joined on Drop.

Implementations

impl DesktopController

pub fn new<B: DesktopBackend>(backend: B) -> Result<Self, DesktopError>

Spawn a worker thread that owns backend and start serving requests.

pub fn from_boxed( backend: Box<dyn DesktopBackend>, ) -> Result<Self, DesktopError>

Same as Self::new but takes an already-boxed backend, useful when the backend type is only known dynamically.

pub fn list_icons(&self) -> Result<Vec<IconSnapshot>, DesktopError>

Snapshot every icon currently on the desktop.

pub fn get_flags(&self) -> Result<u32, DesktopError>

Read the raw desktop folder-view flag word.

pub fn apply_flags(&self, mask: u32, values: u32) -> Result<(), DesktopError>

Perform a masked update of the desktop folder-view flags.

new_flags = (old_flags & !mask) | (values & mask).

Returns DesktopError::AnimationBusy while an animation is in flight — a mid-animation flag write can un-hide the real icons behind the overlay. Use AnimationOptions::before_flags / after_flags to bracket an animation with flag changes.

pub fn set_flags(&self, flags: u32) -> Result<(), DesktopError>

OR-set semantics — matches the legacy set_desktop_flags(flags).

pub fn unset_flags(&self, flags: u32) -> Result<(), DesktopError>

AND-clear semantics — matches the legacy unset_desktop_flags(flags).

pub fn toggle_flags(&self, flags: u32) -> Result<(), DesktopError>

XOR-toggle semantics — matches the legacy switch_desktop_flags(flags).

pub fn set_flags_exactly(&self, flags: u32) -> Result<(), DesktopError>

Exactly-set semantics — matches the legacy exactly_set_desktop_flags(flags).

pub fn set_positions( &self, moves: Vec<(IconId, Point)>, ) -> Result<Vec<IconId>, DesktopError>

Instantly move a batch of icons to the specified positions (no animation). Returns the ids the backend could not resolve.

Returns DesktopError::AnimationBusy while an animation is in flight — the positions would be overwritten by the animation’s final commit. Stop the animation first.

pub fn list_monitors(&self) -> Result<Vec<MonitorInfo>, DesktopError>

Enumerate every connected display in virtual-screen coordinates.

The returned MonitorInfo entries share the same coordinate system as icon positions, so a caller can decide “put this icon on the second monitor” by checking monitor.bounds and building a Point inside those bounds.

pub fn desktop_info(&self) -> Result<DesktopInfo, DesktopError>

Read current screen and icon-grid metrics, including during playback.

pub fn render_overlay_snapshot( &self, width_px: u32, height_px: u32, dpi_scale: f32, positions: Vec<(IconId, Point)>, render_options: OverlayRenderOptions, ) -> Result<SnapshotFrame, DesktopError>

Render one frame of the overlay off-screen and return the raw pixel buffer + dimensions. Never touches an on-screen window, DirectComposition, the real desktop, or the display mode.

positions are in overlay-local pixel coordinates (top-left origin). dpi_scale is the scale factor to render at (1.0 → 96 DPI, 2.5 → 240 DPI).

The backend must have been populated with icon metadata by a prior Self::list_icons call for icon bitmaps + labels to appear; ids missing from the backend’s caches render as placeholder tiles.

Returns DesktopError::OverlayUnavailable on backends that do not implement rendering (the cross-platform stub, the test fake, or platforms other than Windows).

pub fn prepare_scene(&self, scene: Scene) -> Result<RenderSession, DesktopError>

pub fn prepare( &self, specs: Vec<IconAnimationSpec>, options: AnimationOptions, ) -> Result<PreparedAnimation, DesktopError>

Build overlay resources now without displaying or moving anything. The snapshot is fixed at preparation; reprepare after desktop changes.

pub fn animate( &self, specs: Vec<IconAnimationSpec>, options: AnimationOptions, ) -> Result<AnimationHandle, DesktopError>

Start an animation.

Returns immediately with a handle. Use AnimationHandle::wait to block until completion, or the various on_* observers for non-blocking notification.

Observer race warning: callbacks attached via AnimationHandle::on_start / on_tick / on_icon_complete / on_finish are inherently racy — the worker may already be ticking (and firing events) by the time your registration lands. If precise counts matter, use Self::animate_with_observers instead, which installs the callbacks before the worker enters its tick loop.

pub fn animate_with_observers( &self, specs: Vec<IconAnimationSpec>, options: AnimationOptions, observers: PreObservers, ) -> Result<AnimationHandle, DesktopError>

Same as Self::animate but atomically pre-attaches a bundle of observers, guaranteeing that every event fired by the worker is delivered to those callbacks.

pub fn shutdown(&self)

Stop the worker thread and block until it has exited.

Idempotent, and called by Drop. Exposed separately so embedders that must not block on the calling thread’s own resources — notably PyO3, which runs Drop with the GIL held while the worker may be waiting to acquire the GIL inside an observer callback — can perform the join at a point of their choosing.

Trait Implementations

impl Drop for DesktopController

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.