desktop

tape
import desktop from "desktop";
import process from "process";
import time from "time";
import io from "io";

fn main() -> i32 {
    var c = process.command("notepad.exe");
    var child: process.Child = c.spawn() or { return 1; };
    let found: ?desktop.Window = desktop.wait_for("Untitled - Notepad", time.seconds(5)) or { return 2; };
    if (found == null) { io.println("no window"); return 3; }
    let w: desktop.Window = found!;
    let screen: desktop.Screen = desktop.primary() or { return 4; };
    // the left half of the work area, on top
    w.place(desktop.Rect {
        x: screen.work.x; y: screen.work.y; w: screen.work.w / 2; h: screen.work.h;
    }) or { io.println("place: {err}"); };
    w.set_topmost(true) or {};
    time.sleep(time.seconds(3));
    w.close() or {};
    child.wait() or {};
    return 0;
}

desktop arranges other programs’ windows: a presenter that puts an editor next to a terminal, a recorder that frames what it records. It is Windows only for now; on Linux, macOS and Uusi every call fails with Unsupported.

Coordinates are pixels of the whole desktop: the primary screen’s top-left corner is 0, 0, and a screen to its left has negative x. They are real pixels at any display scaling.

Finding windows

FunctionDoes
windows() -> Vec_Window or io.IoErrorThe visible top-level windows with a title, front to back
find(title) -> ?Window or io.IoErrorThe front-most window titled exactly title
find_containing(part) -> ?Window or io.IoErrorOne whose title contains part
find_pid(pid) -> ?Window or io.IoErrorThe front-most window of a process (child.pid())
wait_for(title, timeout) -> ?Window or io.IoErrorfind until the window appears; null after timeout

A program you just started takes a moment to show its window: use wait_for. Free the Vec that windows() returns.

A window

FunctionDoes
w.info() -> WindowInfo or io.IoErrorIts title, pid, bounds (the visible frame), client area, minimized, topmost
w.title() -> string or io.IoErrorIts title
w.is_open() -> boolWhether it still exists
w.place(r: Rect)Put its visible frame at r (restoring it if minimized or maximized)
w.set_topmost(on: bool)Keep it above other windows, or stop
w.close()Ask it to close, as its close button does

A window belongs to its program and can close at any time: then every call on it fails with NotFound. place never activates the window. close doesn’t wait, and the program may ask the user first. A window of a program running as administrator can’t be moved by one that isn’t (PermissionDenied).

Screens

FunctionDoes
screens() -> Vec_Screen or io.IoErrorEvery screen, the primary first
primary() -> Screen or io.IoErrorThe primary screen

A Screen has its bounds, its work area (without the taskbar), its dpi (96 at 100 % scaling, 144 at 150 %) and primary.

Last modified: