#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] #![forbid(unsafe_code)] //! Decide who draws the window frame, so every Craft app shows the same titlebar and borders on a //! given desktop. //! //! egui apps either let the desktop draw the window frame (the title bar, borders and window //! buttons) or turn it off and draw their own. Across the suite this decision had drifted: some //! apps always drew their own frame on Linux, some always kept the desktop's, and some probed the //! compositor — so on KDE, say, one app wore KWin's title bar while another wore its own. This //! crate makes the decision one place. //! //! The current rule is in [`policy`]: the app's own bar is the title bar by default, and the user //! setting "Use system title bar" turns that off. The first-generation rule ([`Choice::probe`], //! [`Frame`]), by platform: //! //! - **macOS and Windows:** the OS always draws the frame ([`Frame::Desktop`]). (An app that insets //! its content under the traffic lights, or draws its own caption buttons on Windows, still asks //! the OS for a decorated window and overdraws it; that is the app's choice and not this crate's.) //! - **Linux and the BSDs, X11:** the window manager draws the frame ([`Frame::Desktop`]). //! - **Linux and the BSDs, Wayland:** a compositor that offers server-side decorations //! (`zxdg_decoration_manager_v1` — KDE, Sway, Hyprland, COSMIC) draws the frame //! ([`Frame::Desktop`]). One that does not (GNOME's Mutter) leaves the frame to the app //! ([`Frame::App`]): without this, winit draws an imitation frame that matches no desktop. //! //! An environment variable overrides the choice, for users whose compositor the probe can't read //! or who simply prefer the other frame. With the default prefix `CRAFT`, `CRAFT_TITLEBAR=app` //! forces [`Frame::App`] and `=system` (or `=desktop`) forces [`Frame::Desktop`]; apps may pass //! their own prefix (`PDFCRAFT`, `FIGCRAFT`, …) so each keeps its own variable name. //! //! When the app draws the frame, [`Frame::App`] carries the [`Layout`] of window buttons the //! desktop names (GNOME's `button-layout`), so the app's header bar puts minimize, maximize and //! close where that desktop puts them. This crate decides *whether* and *where*; drawing the //! buttons stays with each app (their title bars differ). //! //! The probe opens a short-lived Wayland connection and reads the global registry once; it never //! touches the connection winit inherits. Call it once at startup. //! //! # One window per document //! //! [`WindowList`] and [`WindowMenu`] keep the bookkeeping for apps that open each document in its //! own top-level window. They have no egui dependency: //! //! - [`WindowList`]: open windows with the app's per-window data, a [`WindowId`] for each (never //! reused while the process runs), the active window and most-recent order. Menu commands go to //! [`WindowList::active`]; when the active window closes, [`Closed::focus`] names the next one. //! - [`WindowMenu`]: the Window menu (macOS) or View › Switch Windows list. Windows on the same //! document are titled "Name:1", "Name:2". //! //! # The application menu bar //! //! [`native_menu`] makes the platform's own menu bar (macOS, feature `appkit`) from a plain //! description of the menus and reports the chosen items by id. On other platforms it does nothing. //! //! # Window restore //! //! [`restore`] (no egui) decides where a window opens, from the last session's geometry and the //! connected monitors, and keeps the `window.json` store beside `config.toml` on desktop (memory on the web). #![warn(missing_docs)] pub mod capture; pub mod desktop; mod layout; mod list; mod lock_state; pub mod mac; mod menu; pub mod native; pub mod native_menu; pub mod policy; pub mod system; #[cfg(windows)] mod win32; pub mod restore; pub use list::{Closed, WindowId, WindowList}; pub use lock_state::caps_lock; pub use menu::{Document, MenuEntry, WindowMenu}; /// The environment-variable prefix an app overrides the frame with: `_TITLEBAR`. /// /// `Prefix::default()` is `CRAFT`, so `CRAFT_TITLEBAR`. An app that wants its own name passes /// [`Prefix::new`] (`Prefix::new("PDFCRAFT")` reads `PDFCRAFT_TITLEBAR`). The name is used as /// given; it should be ASCII letters, digits and underscores, as environment names are. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Prefix(&'static str); impl Default for Prefix { fn default() -> Self { Self("CRAFT") } } impl Prefix { /// An app-specific prefix, so the override variable is `_TITLEBAR`. pub const fn new(prefix: &'static str) -> Self { Self(prefix) } /// The environment variable this prefix reads, e.g. `CRAFT_TITLEBAR`. pub fn var_name(self) -> String { format!("{}_TITLEBAR", self.0) } /// The environment variable that picks the caption style: `_CAPTION_STYLE`. pub fn caption_style_var(self) -> String { format!("{}_CAPTION_STYLE", self.0) } /// The environment variable that picks the caption layout: `_CAPTION_LAYOUT`. pub fn caption_layout_var(self) -> String { format!("{}_CAPTION_LAYOUT", self.0) } } /// Who draws the window frame. Superseded by [`policy::Frame`]; kept for apps that have not moved. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Frame { /// The desktop draws it: the OS on macOS and Windows, the window manager on X11, the /// compositor on a Wayland session with server-side decorations. The app leaves decorations on. Desktop, /// The app draws it (GNOME's Wayland session, or an override). The app turns decorations off /// and draws a header bar with the window buttons in this [`Layout`]. App(Layout), } impl Frame { /// Whether the app should keep the OS/compositor decorations on (`true` for [`Frame::Desktop`]). /// This is the value to pass to `egui::ViewportBuilder::with_decorations`. pub fn decorations(&self) -> bool { matches!(self, Frame::Desktop) } /// The window-button layout when the app draws the frame, else `None`. pub fn layout(&self) -> Option<&Layout> { match self { Frame::App(layout) => Some(layout), Frame::Desktop => None, } } } /// How the frame was decided, so an app can log it or offer a "System title bar" preference that /// knows the current state. Superseded by [`policy::Decision`] and [`policy::decide_for`]. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Choice { frame: Frame, /// `Some(true)` when `_TITLEBAR` forced the app frame, `Some(false)` when it forced the /// desktop frame, `None` when the platform decided. overridden: Option, } impl Choice { /// Probe the running platform and desktop and decide who draws the frame. /// /// `prefix` names the override variable (`_TITLEBAR`). On macOS, Windows and X11 this /// does no I/O; on a Wayland session it opens a short-lived connection to read the registry. pub fn probe(prefix: Prefix) -> Self { match override_frame(&prefix.var_name()) { Some(true) => Self { frame: Frame::App(Layout::from_desktop()), overridden: Some(true) }, Some(false) => Self { frame: Frame::Desktop, overridden: Some(false) }, None if app_draws_frame() => Self { frame: Frame::App(Layout::from_desktop()), overridden: None }, None => Self { frame: Frame::Desktop, overridden: None }, } } /// The decided frame. pub fn frame(&self) -> &Frame { &self.frame } /// The decided frame, consumed. pub fn into_frame(self) -> Frame { self.frame } /// Whether `_TITLEBAR` set the frame: `Some(true)` it forced the app's, `Some(false)` /// the desktop's, `None` the platform decided. pub fn overridden(&self) -> Option { self.overridden } } /// Read ``: `app` → force the app frame, `system`/`desktop` → force the desktop frame, /// anything else (or unset) → let the platform decide. fn override_frame(var: &str) -> Option { parse_override(std::env::var(var).ok().as_deref()) } /// The override a `_TITLEBAR` value asks for: `Some(true)` the app frame, `Some(false)` the /// desktop frame, `None` to let the platform decide. Pure, so it is tested without the environment. fn parse_override(value: Option<&str>) -> Option { match value.map(str::trim) { Some("app") => Some(true), Some("system" | "desktop") => Some(false), _ => None, } } /// A window button. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[non_exhaustive] pub enum Button { #[allow(missing_docs)] Minimize, #[allow(missing_docs)] Maximize, #[allow(missing_docs)] Close, } /// Which window buttons go on which end of the app-drawn header bar, outermost last. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Layout { /// Buttons on the left end, outermost last. pub left: Vec