craft-libs/crates/window/README.md

craft-window

Decide who draws the window frame — the desktop or the app — so every Craft app shows the same titlebar and borders on a given desktop, make the app's own top strip act as the title bar when it draws one, and keep the window list, cascade placement and Window menu for apps with one window per document.

Why

egui apps either keep the desktop's window frame (title bar, borders, window buttons) or turn it off and draw their own. This crate makes that decision in one place, so every Craft app wears the same title bar on a given desktop.

The rule

The app's own bar is the title bar by default (Frame::Integrated). The user setting "Use system title bar" (TitleBarPref::System) gives the frame to the OS, window manager or compositor (Frame::Native).

Platform, desktop, backend	Default	With "Use system title bar"
macOS	Inset: full-size content view, hidden title, traffic lights over the app's bar	Native
Windows	Integrated(Windows): minimize, maximize, close at the right	Native
GNOME, Wayland or XWayland	Integrated(Adwaita), in the order of button-layout	Native
KDE, Wayland or X11	Integrated(Breeze), in the order of KWin's ButtonsOnLeft and ButtonsOnRight	Native
COSMIC, Xfce, Cinnamon, MATE, other floating desktops	Integrated(Generic) in the order of gtk-decoration-layout; Adwaita or Breeze when the GTK theme is one of those	Native
Tiling compositors and window managers (Sway, Hyprland, i3, niri, river, from XDG_CURRENT_DESKTOP)	Native	Native
Wayland without server-side decorations, not GNOME	Integrated(Generic)	Native
Web	Native; no frame code runs	Native

The backend is the one the app opens its window on: an app that forces XWayland on a Wayland session passes Backend::X11. The Wayland registry is probed (500 ms at most) only for Backend::Wayland.

policy::decide is pure and takes the OS, backend, desktop, setting and override. decide_for reads the platform once and calls it.

Override

<PREFIX>_TITLEBAR wins over the setting. With the default prefix CRAFT: CRAFT_TITLEBAR=app forces the app's bar (also on tiling compositors), =system or =desktop forces the native frame. Apps pass their own prefix (Prefix::new("PDFCRAFT") reads PDFCRAFT_TITLEBAR). When <PREFIX>_TITLEBAR is unset, CRAFT_TITLEBAR applies, so one variable covers every app. Decision::overridden reports Some(true) or Some(false) when the variable decided.

Use

use craft_window::Prefix;
use craft_window::policy::{Backend, Frame, TitleBarPref, apply, decide_for};

// Once at startup, before the window is created:
let pref = if settings.system_title_bar { TitleBarPref::System } else { TitleBarPref::Integrated };
// Backend::from_env() is what winit opens; an app that forces XWayland passes Backend::X11.
let decision = decide_for(Prefix::new("PHOTOCRAFT"), Backend::from_env(), pref);
let viewport = apply(egui::ViewportBuilder::default().with_title("PhotoCraft"), &decision.frame);

if let Frame::Integrated(captions) = &decision.frame {
    // captions.family picks the button look; captions.layout.left / .right place the buttons.
}

This crate decides whether and where; drawing the buttons stays in each app.

Older API

Choice::probe, the root Frame::{Desktop, App} and decorate follow the earlier two-way rule (the desktop draws the frame, except on Wayland without server-side decorations). They still work; policy supersedes them.

The egui feature adds [decorate], the title_bar module and Viewports. Without it, the crate is pure decision and bookkeeping logic with no egui dependency.

The app's own title bar

An app that draws over the title bar — a hidden macOS title bar with a full-size content view, or Frame::App — makes its top strip act as one with craft_window::title_bar (egui feature):

Where the drag or double-click starts	What happens
The strip's empty part	A drag moves the window (ViewportCommand::StartDrag); a double-click follows the system setting (macOS AppleActionOnDoubleClick: zoom, minimize or nothing; zoom elsewhere)
A control on the strip	The control gets it; the window stays put
An in-window panel over the strip (an Order::Middle layer: a floating dock, an egui::Window)	The panel gets it; the window stays put
A modal's backdrop or a tooltip (Foreground/Tooltip)	The window moves, as under AppKit's own title bar
Anything, in full screen	Nothing happens to the window

egui::Panel::top("app_bar").show(ui, |ui| {
    // Before the bar's controls, so they sit on top and take their own clicks.
    craft_window::title_bar::empty_area(ui, ui.max_rect());
    // ... the bar's controls ...
});
// macOS, once per frame after the UI: `applied` is app state, starting at `None`.
#[cfg(target_os = "macos")]
craft_window::title_bar::sync_movable(ui.ctx(), &mut self.applied);

On macOS, AppKit moves a full-size-content window from a drag anywhere in the title-bar band, the app's controls and panels included, unless NSWindow.movable is false. sync_movable sets that flag from title_bar::window_movable, which is false while the pointer is on a control or a panel over the strip. It leaves windows with hidden window buttons alone, such as floating panels in their own windows.

One window per document

For apps that open each document in its own top-level window, the crate also keeps the shared window bookkeeping. The core has no egui dependency.

Type	What it does
WindowList<T>	Open windows with the app's per-window data T. Opening order (stable, for menus) and most-recent order; the first in most-recent order is the active window, which menu commands go to. close returns the data and, when the active window closed, the window to focus next. find returns the most recent window whose data matches, e.g. the window already showing a file.
WindowId	A window's id: Copy, Hash, Ord, from one process-wide counter, so never reused while the app runs. Use it as the key for per-window state (UI state, pending dialogs).
cascade	Places a new window one step (about a title bar, CASCADE_STEP) right of and below the most recent window. Each axis that would run off the bounds (monitor or work area) starts over at the bounds' edge.
monitor_of	The monitor a window is on: the one showing most of it or, when none shows it, the nearest.
WindowMenu	The Window menu (macOS) or View › Switch Windows list: (id, title, dirty, active) per window, in opening order. Windows on the same document are titled Name:1, Name:2, numbered by opening order; a document with one window keeps its plain name. The app supplies each window's document key, name and dirty flag.

With the egui feature, Viewports shows the windows as egui immediate viewports:

• Call show once per frame from the root viewport's UI. It runs the app's callback for each window inside that window's viewport, so ui.ctx() input (close requests, IME) and commands belong to that window. A window's viewport id is child_viewport_id(id).
• New windows get decorate (the frame decision above) and a cascade position from the most recently focused window. On Wayland, where windows have no known position, the compositor places them.
• Give the driver the monitors with set_monitors, in physical pixels from available_monitors(): egui reports only a monitor's size, so without them the driver guesses that monitors tile the desktop, which is wrong when monitors differ in size or sit at other offsets. It asks only when it places a new window. A window keeps to the monitor of the window before it, at any size, place or scale; set_bounds overrides that with an area the app chooses.
• The root viewport stays the app's. set_root(Some(id)) draws window id in it. When the root's window closes while others stay open, adopt moves another window into the root viewport (its position, size and focus); that window's id and data stay the same.
• show returns WindowEvent::Focused and WindowEvent::CloseRequested. Focus also updates the list's active window. Close and quit policy stay with the app: a child window closes when the app removes it from the list, and for the root's window the app sends ViewportCommand::CancelClose to the root in the same frame unless the app should quit.

use craft_window::{Document, Viewports, WindowEvent, WindowList, WindowMenu};

let menu = WindowMenu::new(&windows, |_, w| Document { key: w.doc, name: name_of(w.doc), dirty: is_dirty(w.doc) });
let base = egui::ViewportBuilder::default().with_inner_size([1000.0, 700.0]);
for event in viewports.show(
    ui,
    &mut windows,
    |id, _| base.clone().with_title(menu.title(id).unwrap_or_default()),
    |ui, id, window| draw_window(ui, id, window),
) {
    if let WindowEvent::CloseRequested(id) = event {
        // The app's policy: prompt for the document's last dirty window, then `windows.close(id)`,
        // and `adopt` or `focus` the window `Closed::focus` names.
    }
}

Immediate viewports repaint every window when one repaints, so cache expensive per-window drawing.

Window restore

Feature restore (no egui): craft_window::restore.

• place(saved, monitors, home, &Defaults) -> Placement is pure. First launch: the default size fitted to the home monitor, maximized when it does not fit. Saved sizes are points at interface zoom 1. A window with less than 64×64 pt of its top strip on any one monitor moves to its saved monitor, else the nearest, else the primary; sizes clamp to the monitor's usable area and min. Positions are physical pixels (negative left of or above the primary). Defaults::no_position (Wayland) neither reads nor returns a position. Full screen returns only with Defaults::restore_fullscreen.
• Store::open(app_id) keeps window.json beside config.toml (same folder rules as craft-settings), Store::in_memory() keeps nothing. get, set, save. Format: { "schema_version": 1, "windows": { "main": Placement, "<key>": Placement } }. Writes are atomic and private; a damaged file is moved aside as window.broken-<ts>.json; a newer schema_version is read-only; unknown keys are written back unchanged.
• restore::legacy reads eframe's "window" entry of app.ron (without a RON crate) and has small JSON helpers for an app's own old format.

Notes

• The Wayland probe opens a short-lived connection and reads the global registry once, on its own thread with a 500 ms timeout; on failure or timeout it keeps the desktop's frame. Call it once at startup.
• It never touches the connection winit inherits: when WAYLAND_SOCKET is set (a compositor handed the app an open descriptor), the probe skips connecting and keeps the desktop frame, so it can't consume the socket winit needs.
• The GNOME button-layout lookup (gsettings) runs behind the same bounded worker, so a stalled gsettings can't block startup either.
• #![forbid(unsafe_code)], and the never-crash lints the workspace requires.