feat(backend): frame(id) is a cheap live frame query with the reason for a failure

Windows call sites read the frame about 60 times and rely on the Win32
error (or unwrap_or_default). The shared window_rect is built on window(id),
which also asks title, class, exe and path and gives None for every failure.
Add the provided method Backend::frame(id) -> Result<Rect>: WindowGone for
an unknown window, Platform for a failed read. The default goes through
window() (a table lookup on KDE through Shared<B> and on the fake, so the
cached/requested-rect semantics of seam.md section 2 row 2 are kept);
WindowsBackend overrides it with Window::window_rect (one DWM call) and
MacosBackend with MacosApi::window_rect (the two Accessibility reads, no
metadata). The contract tests check frame agrees with window().rect and is
WindowGone for an unknown id; FakeBackend gets a test. A provided method, so
no adapter had to change to compile.

Not a behaviour change (nothing calls it yet). Verified: tools/fast-check
(native crate tests pass, Windows clippy -D warnings, KDE check + lib tests,
macOS fake-CC type-check) PASS; macOS cannot be run here.
This commit is contained in:
LGUG2Z committed 2026-10-31 10:22:38 -07:00
1 parent 69073153d9
commit 0a2562b9cf
5 files changed
+51

No files matched your search

+16
View File
@@ -325,6 +325,22 @@ pub trait Backend: Send + Sync + 'static {
self.window(id).map(|w| w.rect)
}
/// Returns the window's frame, or why there is none: [`Error::WindowGone`] when the backend
/// does not know the window, [`Error::Platform`] when the platform could not say. A **cheap
/// live frame query**: unlike [`Backend::window`] it never asks for the title, class,
/// executable or path, and unlike [`Backend::window_rect`] it keeps the reason for a failure.
///
/// The frame is the same value as the `rect` of [`Backend::window`]: Windows the visible
/// bounds (`DWMWA_EXTENDED_FRAME_BOUNDS`, fallback `GetWindowRect`), macOS the Accessibility
/// position and size (two round trips), KDE the daemon's table (the requested rect until an
/// event corrects it, see "Reads after writes").
///
/// The default goes through [`Backend::window`], which is a table lookup on KDE and the fake;
/// Windows and macOS override it.
fn frame(&self, id: WindowId) -> Result<Rect> {
self.window(id).map(|w| w.rect).ok_or(Error::WindowGone(id))
}
/// Returns the id of the monitor whose bounds contain the point. A point outside every
/// monitor gives `None` on KDE and macOS, and the **nearest** monitor on Windows
/// (`MONITOR_DEFAULTTONEAREST`), so callers must not use `None` to detect "off screen".
+6
View File
@@ -208,6 +208,7 @@ fn window_agrees_with_windows<H: Harness>() {
assert!(info.alive);
assert!(h.backend().is_window(id));
assert_eq!(h.backend().window_rect(id), Some(info.rect));
assert_eq!(h.backend().frame(id).ok(), Some(info.rect));
assert!(h.backend().windows().iter().any(|w| w.id == id));
}
@@ -219,6 +220,11 @@ fn an_unknown_window_is_not_a_window<H: Harness>() {
assert!(h.backend().window(unknown).is_none());
assert!(!h.backend().is_window(unknown));
assert!(h.backend().window_rect(unknown).is_none());
assert!(
h.backend()
.frame(unknown)
.is_err_and(|e| e.is_window_gone())
);
}
fn commands_on_an_unknown_window<H: Harness>() {
+11
View File
@@ -1056,6 +1056,17 @@ mod tests {
Ok(())
}
#[test]
fn frame_is_the_requested_rect_and_an_unknown_window_is_gone() -> Result<()> {
let fake = fake_with(&[1]);
fake.set_rect(ONE, &tile(10, 500))?;
assert_eq!(fake.frame(ONE)?, tile(10, 500));
assert!(fake.frame(WindowId(99)).is_err_and(|e| e.is_window_gone()));
Ok(())
}
#[test]
fn a_window_keeps_to_its_minimum_size() -> Result<()> {
let fake = fake_with(&[1]);
@@ -187,6 +187,15 @@ impl Backend for MacosBackend {
Ok(monitors)
}
fn frame(&self, id: WindowId) -> Result<Rect> {
// the Accessibility position and size only, without the title, executable and path
// lookups of `window`
let window = self.lookup(id)?;
MacosApi::window_rect(&window.element)
.map(Rect::from)
.map_err(|e| Self::failed(id, &window, e))
}
fn cursor_pos(&self) -> Option<(i32, i32)> {
let point = MacosApi::cursor_pos();
#[allow(clippy::cast_possible_truncation)]
+9
View File
@@ -126,6 +126,15 @@ impl Backend for WindowsBackend {
Ok(monitors)
}
fn frame(&self, id: WindowId) -> Result<Rect> {
// one `DwmGetWindowAttribute` (fallback `GetWindowRect`), no title, class or exe lookups,
// and no `IsWindow` first: the Win32 error is the answer, as for every `window_rect`
// caller; `failed` says whether the window died
Window::from(id.to_hwnd())
.window_rect()
.map_err(|e| failed(id, e))
}
fn cursor_pos(&self) -> Option<(i32, i32)> {
WindowsApi::cursor_pos().ok().map(|p| (p.x, p.y))
}