rusty_desktop_icons.DesktopController¶

class rusty_desktop_icons.DesktopController¶

Top-level entry point for animating the current user’s desktop.

On Windows this drives the real IFolderView2 COM interface. On other platforms every method raises UnsupportedPlatform.

Spawn the worker thread and connect to the desktop backend.

animate(specs: Iterable[IconAnimationSpec | dict[str, object]], options: AnimationOptions | dict[str, object] | None = None) → AnimationHandle¶: Start a fixed set of icon animations and return immediately with a handle.

apply_flags(mask: int, values: int) → None¶

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

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

Raises AnimationBusy while an animation is running.

desktop_info() → DesktopInfo¶

get_flags() → int¶: Read the raw desktop folder-view flag word.

list_icons() → list[IconSnapshot]¶: Snapshot every icon currently on the desktop.

list_monitors() → list[MonitorInfo]¶

Enumerate every connected display.

Returns a list of [MonitorInfo] objects whose bounds share the same virtual-screen coordinate space as icon positions. Callers can pick a monitor and build target positions within its work_area to place icons intelligently on multi-monitor setups.

monitor_for_point(point: Sequence[int]) → MonitorInfo | None¶

Look up which monitor contains a given (x, y) point.

Returns None if the point falls outside every monitor’s bounds — which can happen for points in the “dead” space between mismatched-resolution monitors.

prepare(specs: Iterable[IconAnimationSpec | dict[str, object]], options: AnimationOptions | dict[str, object] | None = None) → PreparedAnimation¶: Prepare artwork and GPU resources without starting the visual clock.

prepare_scene(canvas: Canvas, specs: Iterable[IconAnimationSpec | dict[str, object]], positions: Iterable[tuple[str, Sequence[int]] | dict[str, object]], options: AnimationOptions | dict[str, object] | None = None) → RenderSession¶

Prepare artwork and GPU resources without starting the visual clock.

Scene positions are independent of real desktop coordinates. Every spec must have exactly one origin; absent desktop icons/artwork fail preparation.

render_overlay_snapshot(width: int, height: int, dpi_scale: float, positions: Iterable[tuple[str, Sequence[int]] | dict[str, object]], options: AnimationOptions | dict[str, object] | None = None) → dict[str, object]¶

Render one frame of the overlay off-screen with pixel and geometry data.

positions is an iterable of (icon_id, (x, y)) pairs (or dicts with id / position keys), where (x, y) are in overlay-local pixel coordinates — i.e. the top-left of the snapshot buffer is (0, 0). dpi_scale picks the render DPI (1.0 → 96 DPI, 2.5 → 240 DPI). options accepts the same three feature toggles as AnimationOptions (draw_labels, draw_shortcut_overlay, draw_shield_overlay).

Returns a dictionary with pixels (premultiplied BGRA bytes), width, height and geometry. Each geometry entry contains id, icon_rect_px, label_rect_px and arrow_rect_px. The pixel buffer has length width * height * 4. Wrap it with Pillow using Image.frombuffer("RGBA", (width, height), result["pixels"], "raw", "BGRA", 0, 1).

Never touches the display mode or an on-screen window. Call list_icons() first so the backend’s PIDL/name caches are populated; unknown ids render as placeholder tiles.

set_flags(flags: int) → None¶: OR-set semantics.

set_flags_exactly(flags: int) → None¶: Exactly-set semantics — expands flags via build_true_mask.

set_positions(moves: Iterable[tuple[str, Sequence[int]] | dict[str, object]]) → list[str]¶

Instantly move a batch of icons.

moves is an iterable of (icon_id, (x, y)) pairs (or dicts with id / position keys). Returns the list of icon ids the backend could not resolve. Raises AnimationBusy while an animation is running.

toggle_flags(flags: int) → None¶: XOR-toggle semantics.

unset_flags(flags: int) → None¶: AND-clear semantics.