Linux: comments say which VECTORCRAFT_TITLEBAR values take precedence

apps/vectorcraft/src/tests.rs

@@ -193,7 +193,8 @@ fn the_system_title_bar_preference_keeps_the_window_decorations() {
 
 /// Preferences › User Interface › VectorCraft Title Bar on Every Desktop gives the app frame where
 /// the probe chose the desktop's (KDE, X11, a window opened through XWayland); without it the probe
-/// decides, and `VECTORCRAFT_TITLEBAR` takes precedence over both.
+/// decides, and `VECTORCRAFT_TITLEBAR` set to `app`, `system` or `desktop` takes precedence over
+/// both.
 #[test]
 fn the_app_title_bar_preference_gives_the_app_frame_on_desktop_frames() {
     assert!(!super::opted_into_app_title_bar(None), "no preferences: the default");

apps/vectorcraft/src/titlebar.rs

@@ -42,7 +42,7 @@ pub(crate) const CUSTOM_TITLEBAR: bool = !cfg!(target_os = "macos");
 /// Whether the user asked for the system title bar in Preferences › User Interface › System Title
 /// Bar. Read from the saved preferences before the window opens; a missing or unreadable value is
 /// `false` (the default). This preference forces the desktop/native frame back on unless
-/// `VECTORCRAFT_TITLEBAR` is set ([`system_title_bar_applies`]).
+/// `VECTORCRAFT_TITLEBAR` is set to `app`, `system` or `desktop` ([`system_title_bar_applies`]).
 pub(crate) fn opted_into_system_title_bar(saved: Option<&vectorcraft_ui_egui::UiState>) -> bool {
     saved.map(|ui| ui.engine_prefs.get("systemTitleBar").and_then(serde_json::Value::as_bool).unwrap_or(false)).unwrap_or(false)
 }
@@ -56,8 +56,8 @@ pub(crate) fn opted_into_app_title_bar(saved: Option<&vectorcraft_ui_egui::UiSta
 
 /// Whether the app draws the frame on this start, before the System Title Bar preference is
 /// applied ([`custom_titlebar_from`]). `probed_app` is the `craft-window` probe's answer and
-/// `overridden` its `VECTORCRAFT_TITLEBAR` override. In order: the override decides when it is
-/// set; VectorCraft Title Bar on Every Desktop (`opted_into_app`) gives the app frame; a window
+/// `overridden` its `VECTORCRAFT_TITLEBAR` override. In order: the override decides when the
+/// variable is set to `app`, `system` or `desktop`;VectorCraft Title Bar on Every Desktop (`opted_into_app`) gives the app frame; a window
 /// that opens through XWayland (`forced_to_x11`) gets the desktop frame; otherwise the probe
 /// decides.
 pub(crate) fn app_draws_frame(probed_app: bool, overridden: Option<bool>, forced_to_x11: bool, opted_into_app: bool) -> bool {
@@ -89,13 +89,14 @@ fn probed_choice() -> &'static craft_window::Choice {
 
 /// Whether `VECTORCRAFT_TITLEBAR` chose this window's frame (Linux and the BSDs), so Preferences ›
 /// User Interface › System Title Bar and VectorCraft Title Bar on Every Desktop do not apply while
-/// it is set. Always `false` on macOS and Windows.
+/// it is set to `app`, `system` or `desktop`. Always `false` on macOS and Windows.
 pub(crate) fn titlebar_from_env() -> bool {
     cfg!(not(any(target_os = "macos", target_os = "windows"))) && probed_choice().overridden().is_some()
 }
 
 /// Whether System Title Bar decides this start: `opted_into_system` unless `VECTORCRAFT_TITLEBAR`
-/// is set (`from_env`), which chooses the frame for the run it is set in.
+/// is set to `app`, `system` or `desktop` (`from_env`), which chooses the frame for the run it is
+/// set in.
 pub(crate) fn system_title_bar_applies(opted_into_system: bool, from_env: bool) -> bool {
     opted_into_system && !from_env
 }
@@ -107,10 +108,10 @@ pub(crate) fn system_title_bar_applies(opted_into_system: bool, from_env: bool)
 /// ([`craft_window::Frame::Desktop`]) on macOS, Windows, X11 and any Wayland compositor with
 /// server-side decorations (KDE, Sway, Hyprland, COSMIC); the app draws it
 /// ([`craft_window::Frame::App`]) only where the compositor leaves it to the app (GNOME's Mutter),
-/// or when `VECTORCRAFT_TITLEBAR` overrides the probe. VectorCraft draws its own title bar exactly
+/// or when `VECTORCRAFT_TITLEBAR` set to `app`, `system` or `desktop` overrides the probe. VectorCraft draws its own title bar exactly
 /// when `craft-window` says the app owns the frame **and** the user has not opted into the system
 /// title bar; the preference forces the native frame back on unless `VECTORCRAFT_TITLEBAR` is set
-/// ([`system_title_bar_applies`]).
+/// to one of those values ([`system_title_bar_applies`]).
 ///
 /// macOS and Windows keep today's behavior and are decided by [`CUSTOM_TITLEBAR`] rather than the
 /// probe: `craft-window` returns `Frame::Desktop` for both (the OS always draws a frame), but
@@ -132,13 +133,14 @@ pub(crate) fn custom_titlebar_from(_frame: &craft_window::Frame, opted_into_syst
 
 /// Whether this start draws its own title bar. Probes the shared `craft-window` crate once (its
 /// override variable is `VECTORCRAFT_TITLEBAR`) and combines its decision with the saved System
-/// Title Bar preference, which does not apply while the variable is set. Call once at startup,
+/// Title Bar preference, which does not apply while the variable is set to `app`, `system` or
+/// `desktop`. Call once at startup,
 /// before [`native_options`].
 ///
 /// On Linux, Preferences › Performance › Linux Display Server › X11 opens the window through
 /// XWayland (below). A GNOME/Wayland probe would say `Frame::App` there, but the window really runs
 /// on X11, whose window manager draws the frame — so when XWayland is being forced, keep the native
-/// frame, the same as a real X11 session. An explicit `VECTORCRAFT_TITLEBAR` override still wins,
+/// frame, the same as a real X11 session. A recognized `VECTORCRAFT_TITLEBAR` override still wins,
 /// and so does VectorCraft Title Bar on Every Desktop ([`app_draws_frame`]).
 pub(crate) fn custom_titlebar(saved: Option<&vectorcraft_ui_egui::UiState>) -> bool {
     let choice = probed_choice();

crates/engine/src/prefs.rs

@@ -176,7 +176,7 @@ pub struct Prefs {
     pub system_title_bar: bool,
     /// Linux and the BSDs: draw the app bar as the title bar in sessions where the desktop draws
     /// the frame (X11, Wayland compositors with server-side decorations, XWayland), as on GNOME.
-    /// Read when the app starts; System Title Bar and `VECTORCRAFT_TITLEBAR` take precedence over it.
+    /// Read when the app starts; System Title Bar and `VECTORCRAFT_TITLEBAR` set to `app`, `system` or `desktop` take precedence over it.
     pub app_title_bar: bool,
     // Performance
     pub gpu_performance: bool,

crates/ui-egui/src/prefs_dialog.rs

@@ -493,7 +493,8 @@ fn category_fields(ui: &mut egui::Ui, app: &mut VectorcraftApp, d: &mut Dialog,
                 }
             }
             // Linux and the BSDs only, where the desktop may draw the frame: dimmed while System
-            // Title Bar is on or VECTORCRAFT_TITLEBAR is set, which take precedence over it. A note
+            // Title Bar is on or VECTORCRAFT_TITLEBAR is set to `app`, `system` or `desktop`, which
+            // take precedence over it. A note
             // names each one that is in effect.
             PrefKind::Bool if sp.key == "appTitleBar" => {
                 if APP_TITLE_BAR_SHOWN {